@jacebenson/jsn 1.0.1

package/README.md

@@ -0,0 +1,398 @@
+# JSN - ServiceNow CLI
+
+A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.
+
+## Installation
+
+### npm (Cross-platform — recommended for Windows)
+
+```bash
+npm install -g @jacebenson/jsn
+```
+
+Works on macOS, Linux, and Windows. The correct binary for your platform is downloaded automatically during install.
+
+### Download Binary
+
+```bash
+# Download the latest release
+curl -L https://github.com/jacebenson/jsn/releases/latest/download/jsn-linux-amd64 -o jsn
+chmod +x jsn
+sudo mv jsn /usr/local/bin/
+```
+
+### Go Install
+
+```bash
+go install github.com/jacebenson/jsn/cmd/jsn@latest
+```
+
+## Quick Start
+
+### 1. Setup
+
+Run the interactive setup to configure your first ServiceNow instance:
+
+```bash
+jsn setup
+```
+
+This will:
+1. Ask for your ServiceNow instance URL
+2. Open a browser for OAuth authentication
+3. Set the instance as your default
+
+### 2. Verify Authentication
+
+```bash
+jsn auth status
+```
+
+### 3. Start Using
+
+```bash
+# List all incidents
+jsn incidents
+
+# Show a specific incident
+jsn incidents INC0010001
+
+# Create a new incident
+jsn incidents create --description "Server down" --priority 1
+
+# List change requests
+jsn changes
+
+# Query any table
+jsn records list --table incident --query "priority=1^active=true"
+```
+
+## 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
+
+Work with multiple ServiceNow instances using profiles:
+
+```bash
+# Login to a new instance
+jsn auth login https://dev12345.service-now.com
+
+# List all profiles
+jsn profiles list
+
+# Switch to a different profile
+jsn profiles use dev12345
+
+# Show current profile
+jsn profiles show
+```
+
+## Commands
+
+### Work Commands (Day-to-day operations)
+
+| 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 |
+| `users` | `user` | Manage users |
+| `groups` | `group` | Manage user groups |
+| `records` | - | Generic Table API access |
+
+### Dev Commands (Development artifacts)
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Automations** | `dev flows` | Manage Flow Designer flows |
+| | `dev actions` | Manage action definitions |
+| **Scripts** | `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 |
+| **Data** | `dev tables` | View table definitions |
+| | `dev columns` | Manage column definitions |
+| | `dev import` | Manage import sets |
+| **Security** | `dev acls` | Manage access controls |
+| | `dev roles` | Manage roles |
+| **Platform** | `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 |
+
+## Usage Examples
+
+### Incidents
+
+```bash
+# List all incidents
+jsn incidents
+
+# List critical incidents
+jsn incidents list --query "priority=1"
+
+# Show specific incident
+jsn incidents INC0010001
+
+# Create incident
+jsn incidents create --description "Server down" --priority 1
+
+# Update incident
+jsn incidents update INC0010001 --data '{"state": "6"}'
+
+# Delete incident
+jsn incidents delete INC0010001
+```
+
+### Changes
+
+```bash
+# List all change requests
+jsn changes
+
+# List high-risk changes
+jsn changes list --query "risk=high"
+
+# Create change request
+jsn changes create --description "Deploy feature" --risk medium
+
+# Update change
+jsn changes update CHG0010001 --data '{"state": "3"}'
+
+# Delete change
+jsn changes delete CHG0010001
+```
+
+### Development Artifacts
+
+```bash
+# AUTOMATIONS
+# List Flow Designer flows
+jsn dev flows
+
+# List action definitions
+jsn dev actions
+
+# SCRIPTS
+# List script includes
+jsn dev includes
+
+# Get a specific script include
+jsn dev includes MyScriptInclude
+
+# List business rules
+jsn dev rules
+
+# List client scripts
+jsn dev clientscripts
+
+# List UI actions
+jsn dev uiactions
+
+# List UI policies
+jsn dev uipolicies
+
+# DATA
+# View table definition
+jsn dev tables incident
+
+# List table columns
+jsn dev columns --table incident
+
+# SECURITY
+# List access controls (ACLs)
+jsn dev acls
+
+# List roles
+jsn dev roles
+
+# PLATFORM
+# List update sets
+jsn dev updatesets
+
+# Set current update set
+jsn dev updatesets set "My Update Set"
+
+# List application scopes
+jsn dev scopes
+
+# Query system properties
+jsn dev properties
+
+# Query system logs
+jsn dev logs --level error
+jsn dev logs --source "Business Rule" --level warn
+
+# Execute background script
+jsn dev eval "gs.info('Hello World')"
+```
+
+### Generic Table API
+
+```bash
+# List any table
+jsn records list --table incident --limit 10
+
+# Query with encoded query
+jsn records list --table incident --query "priority=1^active=true"
+
+# Show specific columns
+jsn records list --table incident --columns "number,short_description,priority"
+
+# Get a record by sys_id
+jsn records get --table incident --sys-id abc123
+
+# Create a record
+jsn records create --table incident --data '{"short_description": "Test"}'
+
+# Update a record
+jsn records update --table incident --sys-id abc123 --data '{"priority": "1"}'
+
+# Delete a record
+jsn records delete --table incident --sys-id abc123
+```
+
+## Output Formats
+
+JSN supports multiple 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 (for humans) |
+| Markdown | `--markdown` | Markdown tables |
+| Quiet | `--quiet` or `-q` | Data only, no envelope |
+
+```bash
+# JSON output
+jsn incidents --json
+
+# Styled table output
+jsn incidents --styled
+
+# Markdown output for documentation
+jsn incidents --markdown
+
+# Quiet mode for piping
+jsn incidents -q | jq '.[].number'
+```
+
+## Authentication
+
+JSN uses OAuth 2.0 with PKCE for secure authentication:
+
+```bash
+# Login to an instance
+jsn auth login https://dev12345.service-now.com
+
+# Check authentication status
+jsn auth status
+
+# Logout
+jsn auth logout
+```
+
+Credentials are securely stored in your OS keychain (or file fallback at `~/.config/servicenow/credentials/`).
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SERVICENOW_INSTANCE_URL` | Default instance URL |
+| `SERVICENOW_FORMAT` | Default output format |
+| `SERVICENOW_OAUTH_TOKEN` | OAuth token (for CI/CD) |
+
+## CI/CD Integration
+
+For automated environments, use the OAuth token:
+
+```bash
+export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
+export SERVICENOW_OAUTH_TOKEN="your-oauth-token"
+
+# Now run commands without interactive auth
+jsn incidents list
+```
+
+## Shell Completion
+
+```bash
+# Bash
+source <(jsn completion bash)
+
+# Zsh
+source <(jsn completion zsh)
+
+# Fish
+jsn completion fish | source
+```
+
+## Getting Help
+
+```bash
+# General help
+jsn --help
+
+# Command help
+jsn incidents --help
+
+# Subcommand help
+jsn incidents create --help
+```
+
+## Troubleshooting
+
+### Not authenticated
+
+```bash
+⚠️  Not authenticated to https://dev12345.service-now.com
+
+To get started, run:
+  jsn setup           # Interactive setup
+  jsn auth login      # Login to instance
+```
+
+**Solution**: Run `jsn setup` or `jsn auth login <instance>`
+
+### Instance URL required
+
+```bash
+Error (usage): Instance URL required. Set via --instance flag, SERVICENOW_INSTANCE_URL env, or config file.
+```
+
+**Solution**: Set the instance with one of:
+- `jsn setup`
+- `jsn auth login <instance>`
+- `--instance` flag
+- `SERVICENOW_INSTANCE_URL` environment variable
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Acknowledgments
+
+This project follows the architectural patterns from [basecamp-cli](https://github.com/basecamp/basecamp-cli).

package/bin/jsn.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * JSN CLI binary wrapper
+ *
+ * This script finds the downloaded platform-specific binary and spawns it,
+ * forwarding all arguments, stdin, stdout, and stderr.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function getBinaryPath() {
+  const binaryDir = path.join(__dirname, '..', 'binary');
+  const binaryName = os.platform() === 'win32' ? 'jsn.exe' : 'jsn';
+  const binaryPath = path.join(binaryDir, binaryName);
+
+  if (fs.existsSync(binaryPath)) {
+    return binaryPath;
+  }
+
+  // Fallback: check if running from source/build
+  const devPath = path.join(__dirname, '..', 'jsn');
+  if (fs.existsSync(devPath)) {
+    return devPath;
+  }
+
+  // Another fallback for dev
+  const devPath2 = path.join(__dirname, '..', 'jsn.exe');
+  if (fs.existsSync(devPath2)) {
+    return devPath2;
+  }
+
+  console.error('Error: JSN binary not found.');
+  console.error('');
+  console.error('The binary should have been downloaded during npm install.');
+  console.error('Try reinstalling the package:');
+  console.error('  npm uninstall -g @jacebenson/jsn');
+  console.error('  npm install -g @jacebenson/jsn');
+  console.error('');
+  console.error('Or download manually from:');
+  console.error('  https://github.com/jacebenson/jsn/releases');
+  process.exit(1);
+}
+
+const binaryPath = getBinaryPath();
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start JSN: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@jacebenson/jsn",
+  "version": "1.0.1",
+  "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
+  "homepage": "https://github.com/jacebenson/jsn#readme",
+  "bugs": {
+    "url": "https://github.com/jacebenson/jsn/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jacebenson/jsn.git"
+  },
+  "license": "MIT",
+  "author": "Jace Benson",
+  "type": "commonjs",
+  "files": [
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "jsn": "bin/jsn.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/npm-install.js"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/install.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# JSN CLI Installer
+# Installs the latest JSN release from GitHub
+#
+# Usage:
+#   curl -fsSL https://jsn.jace.pro/install | bash
+#
+# Environment:
+#   JSN_VERSION    Install specific version (e.g., 0.4.1)
+#   NO_COLOR       Disable colored output (https://no-color.org)
+
+set -euo pipefail
+
+REPO="jacebenson/jsn"
+BINARY_NAME="jsn"
+INSTALL_DIR="${JSN_INSTALL_DIR:-}"
+VERSION="${JSN_VERSION:-}"
+
+# Colors - respect NO_COLOR (https://no-color.org)
+if [[ -z "${NO_COLOR:-}" ]] && [[ -t 1 ]]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  NC='\033[0m'
+  BOLD='\033[1m'
+else
+  RED=''
+  GREEN=''
+  YELLOW=''
+  NC=''
+  BOLD=''
+fi
+
+info() { echo -e "${GREEN}✓${NC} $1"; }
+step() { echo -e "${BOLD}→${NC} $1"; }
+warn() { echo -e "${YELLOW}⚠${NC} $1"; }
+error() { echo -e "${RED}✗${NC} $1" >&2; exit 1; }
+
+detect_platform() {
+  local os arch
+  
+  os=$(uname -s | tr '[:upper:]' '[:lower:]')
+  case "$os" in
+    linux) PLATFORM="linux" ;;
+    darwin) PLATFORM="darwin" ;;
+    mingw*|msys*|cygwin*) 
+      PLATFORM="windows"
+      BINARY_NAME="jsn.exe"
+      ;;
+    *) error "Unsupported OS: $os" ;;
+  esac
+  
+  arch=$(uname -m)
+  case "$arch" in
+    x86_64|amd64) ARCH="amd64" ;;
+    arm64|aarch64) ARCH="arm64" ;;
+    armv7l) ARCH="arm" ;;
+    *) error "Unsupported architecture: $arch" ;;
+  esac
+}
+
+get_latest_version() {
+  # Use redirect URL instead of API to avoid rate limits
+  local url
+  url=$(curl -fsSL -o /dev/null -w '%{url_effective}' "https://github.com/${REPO}/releases/latest" 2>/dev/null) || true
+  local version="${url##*/}"
+  version="${version#v}"
+  
+  if [[ ! $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    error "Could not determine latest version. Check your network connection."
+  fi
+  
+  echo "$version"
+}
+
+setup_install_dir() {
+  if [[ -z "$INSTALL_DIR" ]]; then
+    if [[ -w "/usr/local/bin" ]]; then
+      INSTALL_DIR="/usr/local/bin"
+    else
+      INSTALL_DIR="$HOME/.local/bin"
+    fi
+  fi
+  mkdir -p "$INSTALL_DIR"
+}
+
+download_and_install() {
+  local version="$1"
+  local tmp_dir
+  tmp_dir=$(mktemp -d)
+  trap "rm -rf '$tmp_dir'" EXIT
+  
+  # Determine archive extension
+  local ext
+  if [[ "$PLATFORM" == "windows" ]]; then
+    ext="zip"
+  else
+    ext="tar.gz"
+  fi
+  
+  local filename="jsn_v${version}_${PLATFORM}_${ARCH}.${ext}"
+  local url="https://github.com/${REPO}/releases/download/v${version}/${filename}"
+  
+  step "Downloading JSN v${version} for ${PLATFORM}/${ARCH}..."
+  if ! curl -fsSL "$url" -o "${tmp_dir}/${filename}"; then
+    error "Download failed from $url"
+  fi
+  
+  step "Extracting..."
+  cd "$tmp_dir"
+  if [[ "$PLATFORM" == "windows" ]]; then
+    unzip -q "$filename"
+  else
+    tar -xzf "$filename"
+  fi
+  
+  # Find binary using shell globbing (Windows find is different)
+  local binary_file=""
+  for f in jsn jsn.exe jsn_*; do
+    if [[ -f "$f" ]] && [[ "$f" != "*.tar.gz" ]] && [[ "$f" != "*.zip" ]]; then
+      binary_file="$f"
+      break
+    fi
+  done
+  
+  if [[ -z "$binary_file" ]]; then
+    error "Could not find binary in archive"
+    ls -la
+    exit 1
+  fi
+  
+  step "Installing to $INSTALL_DIR..."
+  if [[ -w "$INSTALL_DIR" ]]; then
+    mv "$binary_file" "$INSTALL_DIR/$BINARY_NAME"
+  else
+    mv "$binary_file" "$INSTALL_DIR/$BINARY_NAME" 2>/dev/null || {
+      warn "Need sudo access to install to $INSTALL_DIR"
+      sudo mv "$binary_file" "$INSTALL_DIR/$BINARY_NAME"
+    }
+  fi
+  
+  chmod +x "$INSTALL_DIR/$BINARY_NAME" 2>/dev/null || true
+}
+
+setup_path() {
+  # Check if already in PATH
+  if [[ ":$PATH:" == *":$INSTALL_DIR:"* ]]; then
+    return 0
+  fi
+  
+  # Determine shell config file
+  local shell_rc=""
+  if [[ "$PLATFORM" == "windows" ]]; then
+    # On Windows, always use .bashrc for Git Bash
+    shell_rc="$HOME/.bashrc"
+  else
+    case "${SHELL:-}" in
+      */zsh) shell_rc="$HOME/.zshrc" ;;
+      */bash) shell_rc="$HOME/.bashrc" ;;
+      *) shell_rc="$HOME/.profile" ;;
+    esac
+  fi
+  
+  # Check if already in config
+  if [[ -f "$shell_rc" ]] && grep -qF "$INSTALL_DIR" "$shell_rc" 2>/dev/null; then
+    return 0
+  fi
+  
+  step "Adding $INSTALL_DIR to PATH in $shell_rc"
+  echo "" >> "$shell_rc"
+  echo "# Added by JSN installer" >> "$shell_rc"
+  echo "export PATH=\"$INSTALL_DIR:\$PATH\"" >> "$shell_rc"
+  info "Added to $shell_rc"
+  warn "Run: source $shell_rc"
+  
+  # On Windows, also warn about CMD/PowerShell
+  if [[ "$PLATFORM" == "windows" ]]; then
+    echo ""
+    warn "For Command Prompt or PowerShell, add this to your PATH manually:"
+    echo "  $INSTALL_DIR"
+    echo "  setx PATH \"%PATH%;$INSTALL_DIR\""
+  fi
+}
+
+verify_install() {
+  local installed_version
+  if installed_version=$("$INSTALL_DIR/$BINARY_NAME" version 2>/dev/null | tail -1); then
+    info "${installed_version}"
+    return 0
+  fi
+  error "Installation failed - JSN not working"
+}
+
+main() {
+  step "Installing JSN..."
+  
+  detect_platform
+  
+  if [[ -n "$VERSION" ]]; then
+    # Strip leading 'v' if present
+    VERSION="${VERSION#v}"
+    if [[ ! $VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+      error "Invalid version format: $VERSION (expected: 0.4.1)"
+    fi
+  else
+    VERSION=$(get_latest_version)
+  fi
+  
+  setup_install_dir
+  download_and_install "$VERSION"
+  setup_path
+  verify_install "$PLATFORM"
+  
+  echo ""
+  info "JSN installed successfully!"
+  echo ""
+  echo "  Run 'jsn' to get started (setup will run automatically on first use)"
+  echo ""
+  
+  if [[ "$PLATFORM" == "windows" ]]; then
+    warn "Windows users: Add $INSTALL_DIR to your PATH manually:"
+    echo "  setx PATH \"%PATH%;$INSTALL_DIR\""
+    echo ""
+  fi
+}
+
+main "$@"

package/scripts/npm-install.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * JSN npm postinstall script
+ *
+ * Downloads the correct platform-specific binary from GitHub releases
+ * and places it in the `binary/` directory for the wrapper to find.
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const REPO = 'jacebenson/jsn';
+const BINARY_DIR = path.join(__dirname, '..', 'binary');
+
+const PLATFORM_MAP = {
+  darwin: 'darwin',
+  linux: 'linux',
+  win32: 'windows',
+};
+
+const ARCH_MAP = {
+  x64: 'amd64',
+  arm64: 'arm64',
+};
+
+function detectPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const mappedPlatform = PLATFORM_MAP[platform];
+  const mappedArch = ARCH_MAP[arch];
+
+  if (!mappedPlatform) {
+    throw new Error(
+      `Unsupported platform: ${platform}. ` +
+        `Supported platforms: ${Object.keys(PLATFORM_MAP).join(', ')}`
+    );
+  }
+
+  if (!mappedArch) {
+    throw new Error(
+      `Unsupported architecture: ${arch}. ` +
+        `Supported architectures: ${Object.keys(ARCH_MAP).join(', ')}`
+    );
+  }
+
+  // Windows arm64 can run amd64 binaries, so fall back
+  if (mappedPlatform === 'windows' && mappedArch === 'arm64') {
+    console.log(
+      'Warning: Windows arm64 build not available, using amd64 binary.'
+    );
+    return { platform: 'windows', arch: 'amd64', fallback: true };
+  }
+
+  return { platform: mappedPlatform, arch: mappedArch };
+}
+
+function getVersion() {
+  // npm sets this during install
+  if (process.env.npm_package_version) {
+    return process.env.npm_package_version;
+  }
+
+  // Fallback: read package.json
+  const pkgPath = path.join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  return pkg.version;
+}
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    https
+      .get(url, { timeout: 30000 }, (response) => {
+        if (response.statusCode === 301 || response.statusCode === 302) {
+          // Follow redirect
+          return downloadFile(response.headers.location, dest)
+            .then(resolve)
+            .catch(reject);
+        }
+
+        if (response.statusCode !== 200) {
+          reject(
+            new Error(
+              `Download failed: HTTP ${response.statusCode} for ${url}`
+            )
+          );
+          return;
+        }
+
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close(resolve);
+        });
+      })
+      .on('error', (err) => {
+        fs.unlink(dest, () => {});
+        reject(err);
+      })
+      .on('timeout', () => {
+        fs.unlink(dest, () => {});
+        reject(new Error('Download timeout'));
+      });
+  });
+}
+
+function extractArchive(archivePath, destDir) {
+  const ext = path.extname(archivePath);
+  const isWindows = os.platform() === 'win32';
+
+  if (archivePath.endsWith('.zip')) {
+    // Use PowerShell on Windows, unzip elsewhere
+    if (isWindows) {
+      execSync(
+        `powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force"`,
+        { stdio: 'inherit' }
+      );
+    } else {
+      execSync(`unzip -q -o "${archivePath}" -d "${destDir}"`, {
+        stdio: 'inherit',
+      });
+    }
+  } else if (archivePath.endsWith('.tar.gz')) {
+    execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, {
+      stdio: 'inherit',
+    });
+  } else {
+    throw new Error(`Unknown archive format: ${archivePath}`);
+  }
+}
+
+function findBinary(extractDir) {
+  const binaryName = os.platform() === 'win32' ? 'jsn.exe' : 'jsn';
+
+  // The archive contains just the binary directly
+  const directPath = path.join(extractDir, binaryName);
+  if (fs.existsSync(directPath)) {
+    return directPath;
+  }
+
+  // Sometimes archives have nested directories
+  const entries = fs.readdirSync(extractDir);
+  for (const entry of entries) {
+    const entryPath = path.join(extractDir, entry);
+    const stat = fs.statSync(entryPath);
+    if (stat.isDirectory()) {
+      const nestedPath = path.join(entryPath, binaryName);
+      if (fs.existsSync(nestedPath)) {
+        return nestedPath;
+      }
+    }
+  }
+
+  throw new Error(
+    `Could not find ${binaryName} in extracted archive. Contents: ${entries.join(', ')}`
+  );
+}
+
+async function main() {
+  // Skip if running in development (from git repo)
+  if (fs.existsSync(path.join(__dirname, '..', 'go.mod'))) {
+    console.log('Development environment detected. Skipping binary download.');
+    console.log('Build the binary manually: go build ./cmd/jsn');
+    return;
+  }
+
+  const { platform, arch } = detectPlatform();
+  const version = getVersion();
+
+  // Development placeholder version
+  if (version === '0.0.0') {
+    console.log('Warning: version is 0.0.0, skipping binary download.');
+    console.log('This is expected when installing from source.');
+    return;
+  }
+
+  const ext = platform === 'windows' ? 'zip' : 'tar.gz';
+  const filename = `jsn_v${version}_${platform}_${arch}.${ext}`;
+  const url = `https://github.com/${REPO}/releases/download/v${version}/${filename}`;
+
+  console.log(`Downloading JSN v${version} for ${platform}/${arch}...`);
+  console.log(`  ${url}`);
+
+  // Ensure binary directory exists
+  if (!fs.existsSync(BINARY_DIR)) {
+    fs.mkdirSync(BINARY_DIR, { recursive: true });
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'jsn-install-'));
+  const archivePath = path.join(tmpDir, filename);
+
+  try {
+    await downloadFile(url, archivePath);
+    console.log('Extracting...');
+    extractArchive(archivePath, tmpDir);
+
+    const extractedBinary = findBinary(tmpDir);
+    const binaryName = platform === 'windows' ? 'jsn.exe' : 'jsn';
+    const finalPath = path.join(BINARY_DIR, binaryName);
+
+    // Move binary to final location
+    fs.copyFileSync(extractedBinary, finalPath);
+
+    // Make executable on Unix
+    if (platform !== 'windows') {
+      fs.chmodSync(finalPath, 0o755);
+    }
+
+    console.log(`Installed JSN binary to ${finalPath}`);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    console.error('');
+    console.error('Failed to download the JSN binary.');
+    console.error('You can still use the CLI if you have a binary installed manually.');
+    console.error('Download from: https://github.com/jacebenson/jsn/releases');
+
+    // Don't fail the npm install — the user can fix this later
+    process.exit(0);
+  } finally {
+    // Cleanup temp directory
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(`Unexpected error: ${err.message}`);
+  process.exit(0); // Don't fail npm install
+});

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