@jacebenson/jsn 4.3.11 → 4.3.12-dev.70

package/src/commands/docs/search.js

@@ -1,7 +1,7 @@
 // CLI search against the docs SQLite database.
 
 import fs from 'node:fs';
-import { getDocsDbPath, hasEmbeddings, openDocsDb, closeDocsDb, getMeta } from './db.js';
+import { getDocsDbPath, hasEmbeddings, openDocsDb, closeDocsDb, withDocsDb, getMeta } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
 function safeParse(s) {
@@ -50,119 +50,119 @@ export function searchDocs(opts = {}) {
     throw new Error(`Database not found: ${dbPath}. Run "jsn docs sync" first.`);
   }
 
-  const db = openDocsDb({ dbPath });
-  const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
-  const offset = parseInt(opts.offset, 10) || 0;
-  const bundle = opts.bundle ? String(opts.bundle) : null;
-  const docType = opts.docType ? String(opts.docType) : null;
-  const mode = opts.mode === 'keyword' ? 'keyword' : 'hybrid';
-  const useHybrid = mode === 'hybrid' && hasEmbeddings(db);
-
-  const filters = [];
-  const params = { q, limit, offset };
-  if (bundle) {
-    filters.push('d.bundle = @bundle');
-    params.bundle = bundle;
-  }
-  if (docType) {
-    filters.push('d.doc_type = @docType');
-    params.docType = docType;
-  }
-  const where = filters.length ? ' AND ' + filters.join(' AND ') : '';
-
-  // Total matching docs (for pagination)
-  const total = db
-    .prepare(`SELECT COUNT(*) AS n FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH @q${where}`)
-    .get({ q, ...(bundle && { bundle }), ...(docType && { docType }) }).n;
-
-  let rows;
-  if (!useHybrid) {
-    rows = db
-      .prepare(
-        `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release,
-                json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
-                snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
-                bm25(docs_fts) AS score
-         FROM docs_fts
-         JOIN docs d ON d.id = docs_fts.rowid
-         WHERE docs_fts MATCH @q${where}
-         ORDER BY score
-         LIMIT @limit OFFSET @offset`
-      )
-      .all(params);
-  } else {
-    const candParams = { q, cand: (limit + offset) * 4 + 20 };
-    if (bundle) candParams.bundle = bundle;
-    if (docType) candParams.docType = docType;
-    const candidates = db
-      .prepare(
-        `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release, d.hrr_vector,
-                json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
-                snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
-                bm25(docs_fts) AS bm25
-         FROM docs_fts
-         JOIN docs d ON d.id = docs_fts.rowid
-         WHERE docs_fts MATCH @q${where}
-         ORDER BY bm25
-         LIMIT @cand`
-      )
-      .all(candParams);
-
-    if (candidates.length === 0) {
-      rows = [];
+  return withDocsDb({ dbPath }, (db) => {
+    const limit = Math.min(parseInt(opts.limit, 10) || 20, 1000);
+    const offset = parseInt(opts.offset, 10) || 0;
+    const bundle = opts.bundle ? String(opts.bundle) : null;
+    const docType = opts.docType ? String(opts.docType) : null;
+    const mode = opts.mode === 'keyword' ? 'keyword' : 'hybrid';
+    const useHybrid = mode === 'hybrid' && hasEmbeddings(db);
+
+    const filters = [];
+    const params = { q, limit, offset };
+    if (bundle) {
+      filters.push('d.bundle = @bundle');
+      params.bundle = bundle;
+    }
+    if (docType) {
+      filters.push('d.doc_type = @docType');
+      params.docType = docType;
+    }
+    const where = filters.length ? ' AND ' + filters.join(' AND ') : '';
+
+    // Total matching docs (for pagination)
+    const total = db
+      .prepare(`SELECT COUNT(*) AS n FROM docs_fts JOIN docs d ON d.id = docs_fts.rowid WHERE docs_fts MATCH @q${where}`)
+      .get({ q, ...(bundle && { bundle }), ...(docType && { docType }) }).n;
+
+    let rows;
+    if (!useHybrid) {
+      rows = db
+        .prepare(
+          `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release,
+                  json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
+                  snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
+                  bm25(docs_fts) AS score
+           FROM docs_fts
+           JOIN docs d ON d.id = docs_fts.rowid
+           WHERE docs_fts MATCH @q${where}
+           ORDER BY score
+           LIMIT @limit OFFSET @offset`
+        )
+        .all(params);
     } else {
-      const hrrDim = (() => {
-        const value = getMeta(db, 'hrr_dim');
-        const n = parseInt(value, 10);
-        return Number.isInteger(n) ? n : DEFAULT_DIM;
-      })();
-      const queryVec = encodeText(q, hrrDim);
-      const queryTokens = new Set(q.toLowerCase().split(/\s+/).filter(Boolean));
-
-      const bmVals = candidates.map((c) => c.bm25);
-      const bmMin = Math.min(...bmVals);
-      const bmMax = Math.max(...bmVals);
-      const bmRange = bmMax - bmMin || 1;
-
-      const FTS_W = 0.4, JACCARD_W = 0.3, HRR_W = 0.3;
-
-      for (const c of candidates) {
-        const ftsScore = 1 - (c.bm25 - bmMin) / bmRange;
-        const contentTokens = new Set(
-          `${c.title || ''} ${c.path || ''}`.toLowerCase().split(/\s+/).filter(Boolean)
-        );
-        let inter = 0;
-        for (const t of queryTokens) if (contentTokens.has(t)) inter++;
-        const union = queryTokens.size + contentTokens.size - inter;
-        const jaccard = union ? inter / union : 0;
-
-        let hrrSim = 0.5;
-        if (c.hrr_vector) {
-          hrrSim = (similarity(queryVec, bytesToPhases(c.hrr_vector)) + 1) / 2;
+      const candParams = { q, cand: (limit + offset) * 4 + 20 };
+      if (bundle) candParams.bundle = bundle;
+      if (docType) candParams.docType = docType;
+      const candidates = db
+        .prepare(
+          `SELECT d.id, d.path, d.title, d.bundle, d.doc_type, d.release, d.hrr_vector,
+                  json_extract(d.frontmatter, '$.canonical_url') AS canonical_url,
+                  snippet(docs_fts, 1, '[', ']', ' … ', 12) AS snippet,
+                  bm25(docs_fts) AS bm25
+           FROM docs_fts
+           JOIN docs d ON d.id = docs_fts.rowid
+           WHERE docs_fts MATCH @q${where}
+           ORDER BY bm25
+           LIMIT @cand`
+        )
+        .all(candParams);
+
+      if (candidates.length === 0) {
+        rows = [];
+      } else {
+        const hrrDim = (() => {
+          const value = getMeta(db, 'hrr_dim');
+          const n = parseInt(value, 10);
+          return Number.isInteger(n) ? n : DEFAULT_DIM;
+        })();
+        const queryVec = encodeText(q, hrrDim);
+        const queryTokens = new Set(q.toLowerCase().split(/\s+/).filter(Boolean));
+
+        const bmVals = candidates.map((c) => c.bm25);
+        const bmMin = Math.min(...bmVals);
+        const bmMax = Math.max(...bmVals);
+        const bmRange = bmMax - bmMin || 1;
+
+        const FTS_W = 0.4, JACCARD_W = 0.3, HRR_W = 0.3;
+
+        for (const c of candidates) {
+          const ftsScore = 1 - (c.bm25 - bmMin) / bmRange;
+          const contentTokens = new Set(
+            `${c.title || ''} ${c.path || ''}`.toLowerCase().split(/\s+/).filter(Boolean)
+          );
+          let inter = 0;
+          for (const t of queryTokens) if (contentTokens.has(t)) inter++;
+          const union = queryTokens.size + contentTokens.size - inter;
+          const jaccard = union ? inter / union : 0;
+
+          let hrrSim = 0.5;
+          if (c.hrr_vector) {
+            hrrSim = (similarity(queryVec, bytesToPhases(c.hrr_vector)) + 1) / 2;
+          }
+
+          c.score = FTS_W * ftsScore + JACCARD_W * jaccard + HRR_W * hrrSim;
+          delete c.hrr_vector;
+          delete c.bm25;
         }
 
-        c.score = FTS_W * ftsScore + JACCARD_W * jaccard + HRR_W * hrrSim;
-        delete c.hrr_vector;
-        delete c.bm25;
+        candidates.sort((a, b) => b.score - a.score);
+        rows = candidates.slice(offset, offset + limit);
       }
-
-      candidates.sort((a, b) => b.score - a.score);
-      rows = candidates.slice(offset, offset + limit);
     }
-  }
 
-  closeDocsDb(db);
 
-  // Post-process canonical_url JSON strings that may contain escaped content.
-  for (const row of rows) {
-    if (row.canonical_url) row.canonical_url = safeParse(row.canonical_url) || row.canonical_url;
-  }
+    // Post-process canonical_url JSON strings that may contain escaped content.
+    for (const row of rows) {
+      if (row.canonical_url) row.canonical_url = safeParse(row.canonical_url) || row.canonical_url;
+    }
 
-  return {
-    query: q,
-    mode: useHybrid ? 'hybrid' : 'keyword',
-    total,
-    count: rows.length,
-    results: rows,
-  };
+    return {
+      query: q,
+      mode: useHybrid ? 'hybrid' : 'keyword',
+      total,
+      count: rows.length,
+      results: rows,
+    };
+  });
 }

package/src/commands/docs/serve.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import http from 'node:http';
 import { URL } from 'node:url';
 import Database from 'better-sqlite3';
-import { getDocsDbPath, hasEmbeddings } from './db.js';
+import { getDocsDbPath, hasEmbeddings, closeDocsDb } from './db.js';
 import { encodeText, similarity, bytesToPhases, DEFAULT_DIM } from './hrr.js';
 
 const PUBLIC_DIR = path.join(import.meta.dirname, 'public');
@@ -236,6 +236,8 @@ export function serveDocs(opts = {}) {
     }
   });
 
+  server.once('close', () => closeDocsDb(db));
+
   return new Promise((resolve, reject) => {
     let currentPort = parseInt(port, 10);
     const maxAttempts = 10;
@@ -263,6 +265,7 @@ export function serveDocs(opts = {}) {
         err.message = `Could not find an open port between ${port} and ${currentPort}. Try specifying one with --port.`;
       }
       resolved = true;
+      closeDocsDb(db);
       reject(err);
     }
 

package/src/commands/groups.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, assertSafeExactMatch, buildRecordPayload } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('groups', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -94,12 +94,12 @@ export function groupsCmd(wrap) {
           builder: (y) => y
             .option('name', { alias: 'n', type: 'string', describe: 'Group name' })
             .option('manager', { type: 'string', describe: 'Manager name or sys_id' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.name) recordData.name = argv.name;
             if (argv.manager) recordData.manager = argv.manager;
             if (!recordData.name) {
@@ -118,11 +118,14 @@ export function groupsCmd(wrap) {
           command: 'update <name>',
           describe: 'Update a group by name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.name;
             assertSafeExactMatch(id);
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const isSysID = id.length === 32 && /^[0-9a-fA-F]+$/.test(id);
             const params = new URLSearchParams();
             params.set('sysparm_query', isSysID ? `sys_id=${id}` : `name=${id}`);

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, buildRecordPayload, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -142,7 +142,7 @@ export function recordsCmd(wrap) {
             }
 
             const breadcrumbs = [
-              { action: 'create', cmd: `jsn records create --table ${table} --data '{...}'`, description: 'Create a new record' },
+              { action: 'create', cmd: `jsn records create --table ${table} -f name=value`, description: 'Create a new record' },
               { action: 'filter', cmd: `jsn records list --table ${table} --query "priority=1"`, description: 'Filter: priority 1 only' },
               { action: 'columns', cmd: `jsn columns --table ${table}`, description: 'View available columns' },
             ];
@@ -221,12 +221,13 @@ export function recordsCmd(wrap) {
           describe: 'Create a new record',
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -249,12 +250,13 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
-            .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
+            .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('strict', { type: 'boolean', default: false, describe: 'Exit non-zero if any supplied field was not persisted (write-back check)' }),
           handler: wrap(async (argv, app) => {
-            const recordData = parseDataArg(argv);
+            const recordData = buildRecordPayload(argv);
             const warnings = checkDerivedFields(argv.table, recordData);
             for (const w of warnings) {
               process.stderr.write(`⚠ ${w.hint}\n`);
@@ -401,22 +403,15 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('query', { type: 'string', demandOption: true, describe: 'Encoded query selecting the records to update (e.g. "priority=1^state=1")' })
-            .option('set', { type: 'string', demandOption: true, describe: 'JSON object of fields to set (e.g. \'{"state":"3"}\')' })
+            .option('set', { type: 'string', describe: 'JSON object of fields to set' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' })
             .option('dry-run', { type: 'boolean', default: true, describe: 'Preview the count + a sample without mutating (default)' })
             .option('execute', { type: 'boolean', default: false, describe: 'Perform the update after confirmation' })
             .option('limit', { type: 'number', default: 200, describe: 'Max records to update when executing' })
             .option('force', { type: 'boolean', default: false, describe: 'Skip confirmation (with --execute)' }),
           handler: wrap(async (argv, app) => {
             app.requireInstance();
-            let set;
-            try {
-              set = JSON.parse(argv.set);
-            } catch (e) {
-              throw new Error(`Invalid --set JSON: ${e.message}`, { cause: e });
-            }
-            if (!set || typeof set !== 'object' || Array.isArray(set)) {
-              throw new Error('--set must be a JSON object of field=value pairs');
-            }
+            const set = buildRecordPayload({ ...argv, data: argv.set }, { required: true });
             if (!argv['dry-run'] && !argv.execute) {
               argv.execute = true; // explicit --no-dry-run implies execute intent
             }

package/src/commands/requests.js

@@ -53,7 +53,7 @@ async function enrichedShowHandler(argv, app) {
   app.ok(record, {
     summary: `Request ${number}`,
     breadcrumbs: [
-      { action: 'update', cmd: `jsn req update ${number} --data '{...}'`, description: 'Update this request' },
+      { action: 'update', cmd: `jsn req update ${number} -f state=2`, description: 'Update this request' },
       { action: 'list', cmd: `jsn req list`, description: 'Back to all requests' },
     ],
   });

package/src/commands/setup.js

@@ -1,4 +1,3 @@
-import { createPrompt, useKeypress, usePagination, useState, isDownKey, isEnterKey, isUpKey } from '@inquirer/core';
 import { loginWizard, loginProfile, showAuthStatus, switchProfile, modifyProfile, logoutProfile, removeConnection } from './auth.js';
 import { errUsage } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
@@ -18,32 +17,35 @@ const HUB_CHOICES = [
 ];
 
 /** The setup hub prompt; q and Escape resolve with no selected action. */
-export const authHubPrompt = createPrompt((config, done) => {
-  const [active, setActive] = useState(0);
-  const choices = config.choices;
+export const authHubPrompt = async (...args) => {
+  const { createPrompt, useKeypress, usePagination, useState, isDownKey, isEnterKey, isUpKey } = await import('@inquirer/core');
+  return createPrompt((config, done) => {
+    const [active, setActive] = useState(0);
+    const choices = config.choices;
 
-  useKeypress((key) => {
-    if (key.name === 'q' || key.name === 'escape') {
-      done(undefined);
-      return;
-    }
-    if (isEnterKey(key)) {
-      done(choices[active].value);
-      return;
-    }
-    if (isUpKey(key) && active > 0) setActive(active - 1);
-    if (isDownKey(key) && active < choices.length - 1) setActive(active + 1);
-  });
+    useKeypress((key) => {
+      if (key.name === 'q' || key.name === 'escape') {
+        done(undefined);
+        return;
+      }
+      if (isEnterKey(key)) {
+        done(choices[active].value);
+        return;
+      }
+      if (isUpKey(key) && active > 0) setActive(active - 1);
+      if (isDownKey(key) && active < choices.length - 1) setActive(active + 1);
+    });
 
-  const page = usePagination({
-    items: choices,
-    active,
-    pageSize: choices.length,
-    loop: false,
-    renderItem: ({ item, isActive }) => `${isActive ? '❯' : ' '} ${item.name}`,
-  });
-  return `${config.message}\n${page}\n\n↑↓ navigate • ⏎ select • q/Esc exit`;
-});
+    const page = usePagination({
+      items: choices,
+      active,
+      pageSize: choices.length,
+      loop: false,
+      renderItem: ({ item, isActive }) => `${isActive ? '❯' : ' '} ${item.name}`,
+    });
+    return `${config.message}\n${page}\n\n↑↓ navigate • ⏎ select • q/Esc exit`;
+  })(...args);
+};
 
 /** Interactive hub: what do you want to do? Returns an action or undefined on exit. */
 export async function authHubMenu({ promptFn = authHubPrompt, input, output } = {}) {

package/src/commands/tickets.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -33,7 +33,7 @@ export function ticketsCmd(wrap) {
             const records = await app.sdk.list('task', params);
             const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
-              { action: 'create', cmd: 'jsn tickets create --data \'{...}\'', description: 'Create a new ticket' },
+              { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
             if (records.length === argv.limit) {
               breadcrumbs.push({
@@ -71,9 +71,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const record = await app.sdk.create('task', recordData);
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
@@ -81,9 +85,13 @@ export function ticketsCmd(wrap) {
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y.option('data', { type: 'string', demandOption: true, describe: 'JSON fields (e.g. \'{"state":"2","priority":"1"}\')' }),
+          builder: (y) => y
+            .option('data', { type: 'string', describe: 'JSON fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
             const updated = await app.sdk.update('task', sysID, recordData);
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });

package/src/commands/users.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
 import { resolveRecord, resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
@@ -72,12 +72,12 @@ export function usersCmd(wrap) {
             .option('username', { alias: 'u', type: 'string', describe: 'Username (e.g. john.doe)' })
             .option('name', { alias: 'n', type: 'string', describe: 'Full name (e.g. John Doe)' })
             .option('email', { alias: 'e', type: 'string', describe: 'Email address' })
-            .option('data', { type: 'string', describe: 'JSON data for additional fields' }),
+            .option('data', { type: 'string', describe: 'JSON data for additional fields' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
-            const recordData = {};
-            if (argv.data) {
-              Object.assign(recordData, JSON.parse(argv.data));
-            }
+            const recordData = buildRecordPayload(argv, { required: false });
             if (argv.username) recordData.user_name = argv.username;
             if (argv.name) recordData.name = argv.name;
             if (argv.email) recordData.email = argv.email;
@@ -97,10 +97,13 @@ export function usersCmd(wrap) {
           command: 'update <identifier>',
           describe: 'Update a user by user_name or sys_id',
           builder: (y) => y
-            .option('data', { type: 'string', demandOption: true, describe: 'JSON data to update' }),
+            .option('data', { type: 'string', describe: 'JSON data to update' })
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
+            .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const id = argv.identifier;
-            const recordData = JSON.parse(argv.data);
+            const recordData = buildRecordPayload(argv);
             const sysID = await resolveSysId(app.sdk, { table: 'sys_user', identifier: id, matchField: 'user_name', resource: 'User' });
             const updated = await app.sdk.update('sys_user', sysID, recordData);
             app.ok(updated, {

package/src/commands/version.js

@@ -19,14 +19,28 @@ export function getVersion() {
   }
 }
 
-export async function checkLatest() {
+const backgroundChecks = new Set();
+
+export function cancelBackgroundChecks() {
+  for (const controller of backgroundChecks) controller.abort();
+  backgroundChecks.clear();
+}
+
+export async function checkLatest({ timeout = 1500, background = false } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  timer.unref();
+  if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(NPM_REGISTRY);
+    const res = await fetch(NPM_REGISTRY, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
     return data.version;
   } catch {
     return null;
+  } finally {
+    clearTimeout(timer);
+    backgroundChecks.delete(controller);
   }
 }
 

package/src/frontmatter.js

@@ -1,4 +1,5 @@
-import yaml from 'js-yaml';
+// js-yaml 5 ships ESM-only named exports; there is no default export.
+import { load as loadYaml, dump as dumpYaml } from 'js-yaml';
 
 const DEFAULT_DELIMITERS = ['---', '---'];
 
@@ -27,7 +28,8 @@ export function parseFrontmatter(input, options = {}) {
 
   const closeIndex = frontmatter.indexOf(`\n${close}`);
   const raw = closeIndex === -1 ? frontmatter : frontmatter.slice(0, closeIndex);
-  const parsed = yaml.load(raw);
+  // js-yaml 5 throws on an empty document; an empty block means no metadata.
+  const parsed = raw.trim() === '' ? {} : loadYaml(raw);
   const data = parsed === undefined ? {} : parsed;
 
   if (closeIndex === -1) return { data, content: '' };
@@ -41,7 +43,7 @@ export function parseFrontmatter(input, options = {}) {
 /** Serialize docs metadata and body using gray-matter-compatible YAML framing. */
 export function stringifyFrontmatter(body, data, options = {}) {
   const [open, close] = delimiters(options);
-  const yamlText = yaml.dump(data, options).trim();
+  const yamlText = dumpYaml(data, options).trim();
   const prefix = yamlText === '{}' ? '' : `${open}\n${yamlText}\n${close}\n`;
   const content = String(body);
   return prefix + (content.endsWith('\n') ? content : `${content}\n`);