@jacebenson/jsn 4.3.7 → 4.3.8-dev.47

package/src/errors.js

@@ -10,6 +10,7 @@ export const CodeAPI = 'api_error';
 export const CodeAmbiguous = 'ambiguous';
 export const CodeEmptyResult = 'empty_result';
 export const CodeConfirmationRequired = 'confirmation_required';
+export const CodeExtractionNotFound = 'extraction_not_found';
 
 export class AppError extends Error {
   constructor(code, message, hint = '', status = 0, cause = null) {
@@ -118,17 +119,48 @@ export function errAmbiguous(resource, matches) {
   );
 }
 
+/**
+ * Structured error for `--get <path>` resolving to nothing.
+ *
+ * An unresolvable path (typo, wrong envelope shape, out-of-range index) is a
+ * failure, not a value: printing `undefined` and exiting 0 made a misspelled
+ * extract look like a successful empty result until the next tool in the pipe
+ * tried to parse it. A path that resolves to a present null, false, 0, or ""
+ * is a real value and is returned unchanged — only an unresolved path errors.
+ */
+export function errExtractionNotFound(path) {
+  return new AppError(
+    CodeExtractionNotFound,
+    `No value at --get path "${path}".`,
+    'Check the path against the envelope (run the same command without --get, or with --json, to see its shape). '
+    + 'Present null, false, 0, and "" values are returned as-is; only an unresolvable path fails.'
+  );
+}
+
 /**
  * Structured error for a destructive action that requires confirmation
  * but no human is available to answer (non-TTY, pipes, or AI agents).
+ *
  * The hint is written to be machine-parseable: an agent can read the
- * re-run command and either present it to its user or execute it.
+ * exact re-run command — target, table, pinned profile/instance — and
+ * present it to its user for approval before executing. It deliberately
+ * does NOT recommend permanently disabling confirmations: an approval for
+ * one destructive action is not consent to disarm the guard for every
+ * future action.
+ *
+ * @param {string} question — e.g. `Delete incident INC0010001?`
+ * @param {string} [rerunCmd] — complete re-run command WITHOUT --force,
+ *   already shell-quoted. Empty when the caller cannot reconstruct it.
  */
-export function errConfirmationRequired(question, rerunCmd) {
+export function errConfirmationRequired(question, rerunCmd = '') {
+  const cmd = String(rerunCmd || '').trim();
+  const hint = cmd
+    ? `This is a destructive action. Ask your user to approve this exact command, then re-run:\n  ${cmd} --force`
+    : 'This is a destructive action. Ask your user to approve it, then re-run the same command with --force.';
   return new AppError(
     CodeConfirmationRequired,
-    `${question} — confirmation required. Pass --force to skip, or set skip_confirmations on the profile to disable prompts.`,
-    `This is a destructive action. Ask your user to confirm, then re-run:\n  ${rerunCmd} --force\nOr set skip_confirmations on the profile to disable prompts:\n  jsn auth login <instance> --skip-confirmations`
+    `${question} — confirmation required. Pass --force only after your user approves this operation.`,
+    hint
   );
 }
 
@@ -152,12 +184,20 @@ export function isErrorCode(err, code) {
  *
  * Exit-code contract (observable behavior, pinned by tests):
  *   not_found              → 1   stderr, "Error (not_found): …" + identifier hint
- *   usage / usage_error    → 2   stderr, "Error (usage): …"
+ *   extraction_not_found   → 1   JSON envelope on stdout in JSON mode, else stderr
+ *   usage / usage_error    → 2   JSON envelope on stdout in JSON mode
+ *                                (machine consumers), else stderr "Error (usage): …"
  *   system_error           → 3   stderr, "Error (system): …"
  *   confirmation_required  → 1   JSON envelope on stdout in JSON mode
  *                                (machine consumers), else stderr + hint
  *   anything else          → 1   stderr, "Error: …"
  *
+ * The JSON envelope is the SAME shape for every failure that a machine
+ * consumer can hit — guardError(), the mutation middleware, parse-time
+ * failures routed by cli.js, and handler-thrown AppErrors all end up here, so
+ * `--json` never yields human prose on stdout and never yields a
+ * success-shaped payload for a failed command.
+ *
  * jsonMode resolution: prefer app.output.effectiveFormat() (respects
  * --json/--quiet/etc. shortcuts AND piped-stdout auto-detection); fall
  * back to argv.format for callers without an App (unit tests).
@@ -201,10 +241,35 @@ export function renderAppError(err, { app = null, argv = null, identifier = '' }
     return { stream: 'stderr', text, exitCode: 1 };
   }
 
+  if (code === CodeExtractionNotFound) {
+    // Same contract as every other machine-consumable failure: a parseable
+    // envelope on stdout when the caller is in JSON mode, human text on
+    // stderr otherwise. Exit 1 — the command ran, the value was absent.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 1, appErr: true };
+    }
+    let text = `Error (${code}): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 1 };
+  }
+
   // 'usage' is the legacy literal; CodeUsage ('usage_error') is the
   // exported constant. Both render as the usage class.
   if (code === CodeUsage || code === 'usage') {
-    return { stream: 'stderr', text: `Error (usage): ${err.message}\n`, exitCode: 2 };
+    // Usage failures were the last split-brain case: a parse-time failure
+    // exited 1 with raw prose, a middleware guard exited 2 with a JSON
+    // envelope, and a handler-thrown usage error exited 2 with prose — all
+    // for the same class of mistake. One renderer, one exit code (2), and a
+    // structured envelope whenever the caller is in JSON mode.
+    if (resolveJsonMode(app, argv) && app) {
+      return { stream: 'stdout', text: null, exitCode: 2, appErr: true };
+    }
+    // Keep the actionable hint (the failing command's --help) in the human view
+    // too — it used to be dropped on this path while every other error class
+    // printed one.
+    let text = `Error (usage): ${err.message}\n`;
+    if (err.hint) text += `\nHint: ${err.hint}\n`;
+    return { stream: 'stderr', text, exitCode: 2 };
   }
 
   if (code === 'system_error') {