|
| 1 | +import { test } from 'vitest'; |
| 2 | +import assert from 'node:assert/strict'; |
| 3 | +import { |
| 4 | + AppError, |
| 5 | + asAppError, |
| 6 | + defaultHintForCode, |
| 7 | + isAgentDeviceError, |
| 8 | + KNOWN_APP_ERROR_CODES, |
| 9 | + normalizeAgentDeviceError, |
| 10 | + normalizeError, |
| 11 | + retriableForErrorCode, |
| 12 | + toAppErrorCode, |
| 13 | + type KnownAppErrorCode, |
| 14 | +} from '../errors.ts'; |
| 15 | + |
| 16 | +test('toAppErrorCode falls back when code is missing or empty', () => { |
| 17 | + assert.equal(toAppErrorCode(undefined), 'COMMAND_FAILED'); |
| 18 | + assert.equal(toAppErrorCode(''), 'COMMAND_FAILED'); |
| 19 | + assert.equal(toAppErrorCode(undefined, 'UNAUTHORIZED'), 'UNAUTHORIZED'); |
| 20 | +}); |
| 21 | + |
| 22 | +// --- AppError: construction contract --- |
| 23 | + |
| 24 | +test('AppError is a real Error carrying code/message/details/cause', () => { |
| 25 | + const cause = new Error('root cause'); |
| 26 | + const err = new AppError('DEVICE_NOT_FOUND', 'no device', { hint: 'custom' }, cause); |
| 27 | + assert.ok(err instanceof Error); |
| 28 | + assert.ok(err instanceof AppError); |
| 29 | + assert.equal(err.name, 'Error'); // AppError does not override `name`. |
| 30 | + assert.equal(err.code, 'DEVICE_NOT_FOUND'); |
| 31 | + assert.equal(err.message, 'no device'); |
| 32 | + assert.deepEqual(err.details, { hint: 'custom' }); |
| 33 | + assert.equal(err.cause, cause); |
| 34 | +}); |
| 35 | + |
| 36 | +test('AppError leaves details and cause undefined when the constructor omits them', () => { |
| 37 | + const err = new AppError('UNKNOWN', 'plain'); |
| 38 | + assert.equal(err.details, undefined); |
| 39 | + assert.equal(err.cause, undefined); |
| 40 | +}); |
| 41 | + |
| 42 | +// --- asAppError: identity, wrapping, and duck-typing contract --- |
| 43 | +// |
| 44 | +// Every catch site that normalizes a thrown value (src/cli.ts, src/daemon.ts, |
| 45 | +// src/daemon/server/daemon-runtime.ts, the platform runners) funnels through |
| 46 | +// `asAppError`, so its branch selection is load-bearing: get it wrong and a |
| 47 | +// caller silently loses a real error's message/stack. |
| 48 | + |
| 49 | +test('asAppError returns an AppError input unchanged — no re-wrap, same instance', () => { |
| 50 | + const original = new AppError('TOOL_MISSING', 'missing tool'); |
| 51 | + assert.equal(asAppError(original), original); |
| 52 | +}); |
| 53 | + |
| 54 | +test('asAppError wraps a plain Error under the fallback code, preserving its message and chaining it as cause', () => { |
| 55 | + const original = new Error('boom'); |
| 56 | + const wrapped = asAppError(original); |
| 57 | + assert.ok(wrapped instanceof AppError); |
| 58 | + assert.notEqual(wrapped, original); |
| 59 | + assert.equal(wrapped.code, 'UNKNOWN'); |
| 60 | + assert.equal(wrapped.message, 'boom'); |
| 61 | + assert.equal(wrapped.details, undefined); |
| 62 | + assert.equal(wrapped.cause, original); |
| 63 | +}); |
| 64 | + |
| 65 | +test('asAppError honors an explicit fallback code when wrapping a plain Error', () => { |
| 66 | + const wrapped = asAppError(new Error('boom'), 'COMMAND_FAILED'); |
| 67 | + assert.equal(wrapped.code, 'COMMAND_FAILED'); |
| 68 | + assert.equal(wrapped.message, 'boom'); |
| 69 | +}); |
| 70 | + |
| 71 | +test('asAppError wraps a non-Error throw as "Unknown error" and preserves the raw value in details.err', () => { |
| 72 | + const wrapped = asAppError('a raw string throw'); |
| 73 | + assert.equal(wrapped.code, 'UNKNOWN'); |
| 74 | + assert.equal(wrapped.message, 'Unknown error'); |
| 75 | + assert.equal(wrapped.details?.err, 'a raw string throw'); |
| 76 | + assert.equal(wrapped.cause, undefined); |
| 77 | +}); |
| 78 | + |
| 79 | +test('asAppError applies the fallback code to non-Error throws too, not just Error instances', () => { |
| 80 | + const wrapped = asAppError({ some: 'object' }, 'INVALID_ARGS'); |
| 81 | + assert.equal(wrapped.code, 'INVALID_ARGS'); |
| 82 | + assert.equal(wrapped.message, 'Unknown error'); |
| 83 | + assert.deepEqual(wrapped.details?.err, { some: 'object' }); |
| 84 | +}); |
| 85 | + |
| 86 | +test('asAppError wraps null/undefined the same as any other non-Error value, keeping the raw value in details.err', () => { |
| 87 | + const wrappedNull = asAppError(null); |
| 88 | + assert.equal(wrappedNull.code, 'UNKNOWN'); |
| 89 | + assert.equal(wrappedNull.message, 'Unknown error'); |
| 90 | + assert.equal(wrappedNull.details?.err, null); |
| 91 | + assert.ok(Object.hasOwn(wrappedNull.details ?? {}, 'err')); |
| 92 | + |
| 93 | + const wrappedUndefined = asAppError(undefined); |
| 94 | + assert.equal(wrappedUndefined.message, 'Unknown error'); |
| 95 | + assert.ok(Object.hasOwn(wrappedUndefined.details ?? {}, 'err')); |
| 96 | + assert.equal(wrappedUndefined.details?.err, undefined); |
| 97 | +}); |
| 98 | + |
| 99 | +test('asAppError does not special-case a duck-typed, cross-realm-style Error lookalike — it falls through the non-Error branch', () => { |
| 100 | + // `instanceof Error` fails for a cross-realm Error (different VM context) and |
| 101 | + // for any plain object shaped like one. `asAppError` has no fallback for that |
| 102 | + // case: it treats the value as an opaque non-Error and drops its message and |
| 103 | + // stack into details.err instead of preserving them as `.message`/`.cause`. |
| 104 | + // Every catch-site caller relies on exactly this fallthrough, not a smarter |
| 105 | + // duck-typed detection, so pin it as the contract rather than an accident. |
| 106 | + const duckTypedError = { name: 'Error', message: 'looks like an error', stack: 'fake stack' }; |
| 107 | + const wrapped = asAppError(duckTypedError); |
| 108 | + assert.equal(wrapped.code, 'UNKNOWN'); |
| 109 | + assert.equal(wrapped.message, 'Unknown error'); |
| 110 | + assert.equal(wrapped.details?.err, duckTypedError); |
| 111 | + assert.notEqual(wrapped.message, duckTypedError.message); |
| 112 | +}); |
| 113 | + |
| 114 | +// --- isAgentDeviceError: real instances only, no duck-typing --- |
| 115 | + |
| 116 | +test('isAgentDeviceError is true only for a real AppError instance', () => { |
| 117 | + assert.equal(isAgentDeviceError(new AppError('UNKNOWN', 'x')), true); |
| 118 | +}); |
| 119 | + |
| 120 | +test('isAgentDeviceError is false for a plain Error', () => { |
| 121 | + assert.equal(isAgentDeviceError(new Error('plain error')), false); |
| 122 | +}); |
| 123 | + |
| 124 | +test('isAgentDeviceError is false for an object that merely duck-types the AppError shape', () => { |
| 125 | + const lookalike = { code: 'UNKNOWN', message: 'x', name: 'AppError', details: undefined }; |
| 126 | + assert.equal(isAgentDeviceError(lookalike), false); |
| 127 | +}); |
| 128 | + |
| 129 | +test('isAgentDeviceError is false for nullish and primitive values', () => { |
| 130 | + assert.equal(isAgentDeviceError(null), false); |
| 131 | + assert.equal(isAgentDeviceError(undefined), false); |
| 132 | + assert.equal(isAgentDeviceError('not an error'), false); |
| 133 | + assert.equal(isAgentDeviceError(42), false); |
| 134 | +}); |
| 135 | + |
| 136 | +// --- retriableForErrorCode: table-driven over the module's own code registry --- |
| 137 | +// |
| 138 | +// The enumeration comes from `KNOWN_APP_ERROR_CODES` itself (the module's |
| 139 | +// documented source of truth for "every code that must resolve a verdict"), |
| 140 | +// never a hand-copied subset — a code added to the registry without a matching |
| 141 | +// verdict decision automatically gets a test case here. |
| 142 | + |
| 143 | +/** The only code with a confident retriability verdict today (see RETRIABILITY_BY_CODE in errors.ts). */ |
| 144 | +const RETRIABLE_TRUE_CODES: readonly KnownAppErrorCode[] = ['DEVICE_IN_USE']; |
| 145 | + |
| 146 | +for (const code of KNOWN_APP_ERROR_CODES) { |
| 147 | + const expected = RETRIABLE_TRUE_CODES.includes(code) ? true : undefined; |
| 148 | + test(`retriableForErrorCode('${code}') is ${expected}`, () => { |
| 149 | + assert.equal(retriableForErrorCode(code), expected); |
| 150 | + }); |
| 151 | +} |
| 152 | + |
| 153 | +test('retriableForErrorCode returns undefined for a daemon/runner-originated code outside the known registry', () => { |
| 154 | + assert.equal(retriableForErrorCode('SOME_DAEMON_ONLY_CODE'), undefined); |
| 155 | + assert.equal(retriableForErrorCode(''), undefined); |
| 156 | +}); |
| 157 | + |
| 158 | +// --- defaultHintForCode: table-driven over the module's own code registry --- |
| 159 | + |
| 160 | +/** Mirrors the switch in `defaultHintForCode` — one entry per `KNOWN_APP_ERROR_CODES` member. */ |
| 161 | +const EXPECTED_HINT_BY_CODE: Record<KnownAppErrorCode, string> = { |
| 162 | + INVALID_ARGS: 'Check command arguments and run --help for usage examples.', |
| 163 | + DEVICE_NOT_FOUND: 'Verify the target device is booted/connected and selectors match.', |
| 164 | + DEVICE_IN_USE: 'The device is busy with another agent-device request; retry once it frees up.', |
| 165 | + TOOL_MISSING: 'Install required platform tooling and ensure it is available in PATH.', |
| 166 | + APP_NOT_INSTALLED: |
| 167 | + 'Run apps to discover the exact installed package or bundle id, or install the app before open.', |
| 168 | + UNSUPPORTED_PLATFORM: |
| 169 | + 'This platform is not supported for the requested operation; run devices to inspect available targets.', |
| 170 | + UNSUPPORTED_OPERATION: 'This command is not available for the selected platform/device.', |
| 171 | + NOT_IMPLEMENTED: 'This command is part of the planned API but is not implemented yet.', |
| 172 | + COMMAND_FAILED: 'Retry with --debug and inspect diagnostics log for details.', |
| 173 | + SESSION_NOT_FOUND: 'Run open first or pass an explicit device selector.', |
| 174 | + UNAUTHORIZED: 'Refresh daemon metadata and retry the command.', |
| 175 | + AMBIGUOUS_MATCH: 'Multiple candidates matched. Narrow the query or pass an exact identifier.', |
| 176 | + REPLAY_DIVERGENCE: |
| 177 | + 'Read details.divergence (screen/suggestions) for repair context, or rerun with --json for the full report.', |
| 178 | + REPAIR_SESSION_EXPIRED: |
| 179 | + 'The --save-script repair session was reaped before it was finalized; re-run replay <script> --save-script from the start.', |
| 180 | + REPAIR_COMMIT_FAILED: |
| 181 | + 'The repair transaction completed, but committing its healed script failed at teardown (no-clobber refusal or a filesystem error); inspect the target path/permissions, then re-run replay <script> --save-script to retry.', |
| 182 | + UNKNOWN: |
| 183 | + 'Unexpected internal error. Retry with --debug and report the diagnostics log if it persists.', |
| 184 | +}; |
| 185 | + |
| 186 | +for (const code of KNOWN_APP_ERROR_CODES) { |
| 187 | + test(`defaultHintForCode('${code}') matches the documented hint`, () => { |
| 188 | + assert.equal(defaultHintForCode(code), EXPECTED_HINT_BY_CODE[code]); |
| 189 | + }); |
| 190 | +} |
| 191 | + |
| 192 | +test('EXPECTED_HINT_BY_CODE covers every known code — a registry addition without a hint decision fails loudly', () => { |
| 193 | + assert.deepEqual(Object.keys(EXPECTED_HINT_BY_CODE).sort(), [...KNOWN_APP_ERROR_CODES].sort()); |
| 194 | +}); |
| 195 | + |
| 196 | +test('defaultHintForCode falls back to the generic retry hint for a daemon/runner-originated code outside the registry', () => { |
| 197 | + assert.equal( |
| 198 | + defaultHintForCode('SOME_DAEMON_ONLY_CODE'), |
| 199 | + 'Retry with --debug and inspect diagnostics log for details.', |
| 200 | + ); |
| 201 | +}); |
| 202 | + |
| 203 | +test('defaultHintForCode never returns a falsy hint for any known code — printHumanError silently drops a falsy hint', () => { |
| 204 | + // src/utils/output.ts's printHumanError only prints "Hint: ..." when |
| 205 | + // `normalized.hint` is truthy, so an empty-string hint would silently vanish |
| 206 | + // from CLI output rather than fail loudly. |
| 207 | + for (const code of KNOWN_APP_ERROR_CODES) { |
| 208 | + const hint = defaultHintForCode(code); |
| 209 | + assert.ok(hint, `expected a non-empty hint for ${code}`); |
| 210 | + } |
| 211 | +}); |
| 212 | + |
| 213 | +// --- normalizeAgentDeviceError: the SDK-facing name for normalizeError --- |
| 214 | +// (src/sdk/index.ts re-exports it under this name for public consumers.) |
| 215 | + |
| 216 | +test('normalizeAgentDeviceError delegates to normalizeError, including the context argument', () => { |
| 217 | + const err = new AppError('SESSION_NOT_FOUND', 'gone'); |
| 218 | + const normalized = normalizeAgentDeviceError(err, { |
| 219 | + diagnosticId: 'diag-9', |
| 220 | + logPath: '/tmp/9.log', |
| 221 | + }); |
| 222 | + assert.deepEqual( |
| 223 | + normalized, |
| 224 | + normalizeError(err, { diagnosticId: 'diag-9', logPath: '/tmp/9.log' }), |
| 225 | + ); |
| 226 | + assert.equal(normalized.diagnosticId, 'diag-9'); |
| 227 | + assert.equal(normalized.logPath, '/tmp/9.log'); |
| 228 | +}); |
0 commit comments