Skip to content

Commit 4e12086

Browse files
committed
feat(kernel): publish typed reasons for session-app and session-or-selector refusals
Both refusals answer before anything reaches a device, so a driver must branch on details.reason plus dispatched:no rather than matching the message. Declares the two reason values once at the owning kernel type, with the construction helpers and their normalize/wire coverage. Refs #3181
1 parent 033e55d commit 4e12086

2 files changed

Lines changed: 112 additions & 0 deletions

File tree

‎packages/kernel/src/errors.test.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,76 @@ import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import {
44
AppError,
5+
defaultHintForCode,
56
discloseDispatch,
67
discloseDispatchAfterSteps,
78
normalizeError,
9+
PUBLISHED_ERROR_REASONS,
10+
sessionAppRequiredDetails,
11+
sessionOrDeviceSelectorRequiredDetails,
812
throwDaemonError,
913
readElementMatchCandidateRefs,
1014
readErrorCandidateViews,
1115
summarizeCommandAttemptFailures,
1216
} from './errors.ts';
1317

18+
test('the published reasons are the values consumers branch on', () => {
19+
assert.deepEqual(PUBLISHED_ERROR_REASONS, {
20+
sessionAppRequired: 'session_app_required',
21+
sessionOrDeviceSelectorRequired: 'session_or_device_selector_required',
22+
});
23+
});
24+
25+
for (const [label, details, code, message] of [
26+
[
27+
'sessionAppRequired',
28+
sessionAppRequiredDetails(),
29+
'INVALID_ARGS',
30+
'permission setting requires an active app in session',
31+
],
32+
[
33+
'sessionOrDeviceSelectorRequired',
34+
sessionOrDeviceSelectorRequiredDetails(),
35+
'INVALID_ARGS',
36+
'clipboard requires an active session or an explicit device selector (e.g. --platform ios).',
37+
],
38+
] as const) {
39+
test(`${label} refusal carries its reason and dispatched:no through normalize and the wire`, () => {
40+
const normalized = normalizeError(new AppError(code, message, details));
41+
assert.equal(normalized.message, message);
42+
assert.equal(normalized.details?.reason, details.reason);
43+
assert.equal(normalized.details?.dispatched, 'no');
44+
assert.throws(
45+
() => throwDaemonError(normalized),
46+
(error: unknown) =>
47+
error instanceof AppError &&
48+
error.details?.reason === details.reason &&
49+
error.details?.dispatched === 'no',
50+
);
51+
});
52+
53+
test(`${label} reason survives a second normalization of the wire shape`, () => {
54+
const once = normalizeError(new AppError(code, message, details));
55+
const twice = normalizeError(new AppError(once.code, once.message, once.details));
56+
assert.deepEqual(twice.details, once.details);
57+
});
58+
}
59+
60+
test('a published refusal keeps the INVALID_ARGS default hint — the reason carries the extra fact', () => {
61+
for (const details of [sessionAppRequiredDetails(), sessionOrDeviceSelectorRequiredDetails()]) {
62+
const normalized = normalizeError(new AppError('INVALID_ARGS', 'refused', details));
63+
assert.equal(normalized.hint, defaultHintForCode('INVALID_ARGS'));
64+
}
65+
});
66+
67+
test('a sibling INVALID_ARGS refusal without a reason cannot activate a reason-driven consumer', () => {
68+
const unrelated = normalizeError(
69+
new AppError('INVALID_ARGS', 'clipboard requires a subcommand: read or write'),
70+
);
71+
assert.equal(unrelated.details?.reason, undefined);
72+
assert.equal('dispatched' in (unrelated.details ?? {}), false);
73+
});
74+
1475
test('normalizeError retains redacted nested command errors through repeated normalization', () => {
1576
const stderr = `Launch request denied\n${'Context line\n'.repeat(50)}Underlying reason: token=private-value device locked`;
1677
const expected = stderr.replace('private-value', '[REDACTED]');

‎packages/kernel/src/errors.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,57 @@ export function throwDaemonError(error: DaemonError): never {
251251
);
252252
}
253253

254+
/**
255+
* The `details.reason` values a refusal answers with when the caller must know *why* a request was
256+
* stopped rather than read the prose: what a caller does to recover is the reason's meaning, and it
257+
* is public surface. Every refusal that names a reason here states its `dispatched` disclosure too,
258+
* because a refusal that reached no device is exactly what makes a retry safe.
259+
*/
260+
export const PUBLISHED_ERROR_REASONS = {
261+
/**
262+
* A per-app setting was asked for while the request carries no app — the session binds none and
263+
* none was named for this request. Recovery: `open` the app (or name it for the request), then
264+
* retry. Both the Apple and Android owners answer with this one reason for every per-app setting,
265+
* because the recovery is the same whichever setting asked.
266+
*/
267+
sessionAppRequired: 'session_app_required',
268+
/**
269+
* A device-bound command was asked for with neither an active session nor an explicit device
270+
* selector, so there was no target to route to. Recovery: `open` a session or pass `--platform`
271+
* or another device selector, then retry. One reason covers every command that asks the daemon to
272+
* find a device for it; the command it asks for stays in the message.
273+
*/
274+
sessionOrDeviceSelectorRequired: 'session_or_device_selector_required',
275+
} as const;
276+
277+
export type PublishedErrorReason = (typeof PUBLISHED_ERROR_REASONS)[keyof typeof PUBLISHED_ERROR_REASONS];
278+
279+
/** The details of a refusal that stopped a request before anything could reach a device. */
280+
export type RefusalDetails<TReason extends PublishedErrorReason> = AppErrorDetails & {
281+
reason: TReason;
282+
dispatched: 'no';
283+
};
284+
285+
/** The details of a per-app setting refused for want of an app. */
286+
export function sessionAppRequiredDetails(): RefusalDetails<
287+
(typeof PUBLISHED_ERROR_REASONS)['sessionAppRequired']
288+
> {
289+
return {
290+
reason: PUBLISHED_ERROR_REASONS.sessionAppRequired,
291+
dispatched: 'no',
292+
};
293+
}
294+
295+
/** The details of a command refused for want of a target to route to. */
296+
export function sessionOrDeviceSelectorRequiredDetails(): RefusalDetails<
297+
(typeof PUBLISHED_ERROR_REASONS)['sessionOrDeviceSelectorRequired']
298+
> {
299+
return {
300+
reason: PUBLISHED_ERROR_REASONS.sessionOrDeviceSelectorRequired,
301+
dispatched: 'no',
302+
};
303+
}
304+
254305
/**
255306
* `details.reason` of a request its requester abandoned — an explicit cancel or
256307
* a client disconnect. One definition, so every layer that must let a

0 commit comments

Comments
 (0)