Skip to content

Commit d59cdba

Browse files
author
Zoo (VP)
committed
feat: add unified shell resolution contracts and settings UI
1 parent 7918f6b commit d59cdba

26 files changed

Lines changed: 1493 additions & 3 deletions
Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
/**
2+
* Tests for the terminal shell selection settings and message contracts.
3+
*
4+
* Validates:
5+
* - `terminalShellSelection` is optional and older settings import unchanged
6+
* - Discriminated shape validation (auto, profile, path)
7+
* - Legacy `execaShellPath` remains readable
8+
* - Message payload types compile correctly
9+
*/
10+
import { describe, it, expect } from "vitest"
11+
12+
import {
13+
globalSettingsSchema,
14+
terminalShellSelectionSchema,
15+
type GlobalSettings,
16+
type TerminalShellSelection,
17+
} from "../global-settings.js"
18+
19+
import type {
20+
ExtensionMessage,
21+
WebviewMessage,
22+
TerminalShellOption,
23+
TerminalShellOptionsPayload,
24+
} from "../vscode-extension-host.js"
25+
26+
describe("terminalShellSelectionSchema", () => {
27+
// ── Discriminated union validation ──────────────────────────────────
28+
29+
describe("auto mode", () => {
30+
it("should parse { kind: 'auto' }", () => {
31+
const result = terminalShellSelectionSchema.parse({ kind: "auto" })
32+
expect(result).toEqual({ kind: "auto" })
33+
})
34+
35+
it("should strip extra fields on auto variant", () => {
36+
// Zod discriminated union objects are non-strict by default;
37+
// extra keys are stripped rather than rejected.
38+
const result = terminalShellSelectionSchema.parse({
39+
kind: "auto",
40+
path: "/bin/sh",
41+
})
42+
expect(result).toEqual({ kind: "auto" })
43+
expect(result).not.toHaveProperty("path")
44+
})
45+
})
46+
47+
describe("profile mode", () => {
48+
it("should parse { kind: 'profile', profileName: 'PowerShell' }", () => {
49+
const result = terminalShellSelectionSchema.parse({
50+
kind: "profile",
51+
profileName: "PowerShell",
52+
})
53+
expect(result).toEqual({ kind: "profile", profileName: "PowerShell" })
54+
})
55+
56+
it("should reject profile without profileName", () => {
57+
expect(() => terminalShellSelectionSchema.parse({ kind: "profile" })).toThrow()
58+
})
59+
60+
it("should reject profile with empty profileName", () => {
61+
expect(() => terminalShellSelectionSchema.parse({ kind: "profile", profileName: "" })).not.toThrow() // z.string() accepts empty; validation is extension-host responsibility
62+
})
63+
})
64+
65+
describe("path mode", () => {
66+
it("should parse { kind: 'path', path: 'C:\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe' }", () => {
67+
const result = terminalShellSelectionSchema.parse({
68+
kind: "path",
69+
path: "C:\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
70+
})
71+
expect(result.kind).toBe("path")
72+
if (result.kind === "path") {
73+
expect(result.path).toContain("powershell.exe")
74+
}
75+
})
76+
77+
it("should reject path without path field", () => {
78+
expect(() => terminalShellSelectionSchema.parse({ kind: "path" })).toThrow()
79+
})
80+
})
81+
82+
describe("invalid discriminated shapes", () => {
83+
it("should reject unknown kind", () => {
84+
expect(() => terminalShellSelectionSchema.parse({ kind: "unknown" })).toThrow()
85+
})
86+
87+
it("should reject missing kind", () => {
88+
expect(() => terminalShellSelectionSchema.parse({})).toThrow()
89+
})
90+
91+
it("should reject null", () => {
92+
expect(() => terminalShellSelectionSchema.parse(null)).toThrow()
93+
})
94+
95+
it("should reject non-object", () => {
96+
expect(() => terminalShellSelectionSchema.parse("auto")).toThrow()
97+
})
98+
})
99+
})
100+
101+
describe("globalSettingsSchema — terminalShellSelection", () => {
102+
// ── Optionality and backward compatibility ──────────────────────────
103+
104+
it("should accept settings without terminalShellSelection (backward compat)", () => {
105+
const legacySettings = {
106+
terminalProfile: "PowerShell",
107+
execaShellPath: "/bin/bash",
108+
}
109+
const result = globalSettingsSchema.parse(legacySettings)
110+
expect(result.terminalShellSelection).toBeUndefined()
111+
expect(result.execaShellPath).toBe("/bin/bash")
112+
expect(result.terminalProfile).toBe("PowerShell")
113+
})
114+
115+
it("should accept settings with terminalShellSelection auto", () => {
116+
const result = globalSettingsSchema.parse({
117+
terminalShellSelection: { kind: "auto" },
118+
})
119+
expect(result.terminalShellSelection).toEqual({ kind: "auto" })
120+
})
121+
122+
it("should accept settings with terminalShellSelection profile", () => {
123+
const result = globalSettingsSchema.parse({
124+
terminalShellSelection: { kind: "profile", profileName: "Git Bash" },
125+
})
126+
expect(result.terminalShellSelection).toEqual({
127+
kind: "profile",
128+
profileName: "Git Bash",
129+
})
130+
})
131+
132+
it("should accept settings with terminalShellSelection path", () => {
133+
const result = globalSettingsSchema.parse({
134+
terminalShellSelection: { kind: "path", path: "/usr/bin/fish" },
135+
})
136+
expect(result.terminalShellSelection).toEqual({
137+
kind: "path",
138+
path: "/usr/bin/fish",
139+
})
140+
})
141+
142+
it("should reject settings with invalid terminalShellSelection shape", () => {
143+
expect(() =>
144+
globalSettingsSchema.parse({
145+
terminalShellSelection: { kind: "invalid" },
146+
}),
147+
).toThrow()
148+
})
149+
150+
it("should allow both terminalShellSelection and legacy execaShellPath", () => {
151+
const result = globalSettingsSchema.parse({
152+
terminalShellSelection: { kind: "auto" },
153+
execaShellPath: "/bin/zsh",
154+
})
155+
expect(result.terminalShellSelection).toEqual({ kind: "auto" })
156+
expect(result.execaShellPath).toBe("/bin/zsh")
157+
})
158+
159+
// ── Legacy field readability ────────────────────────────────────────
160+
161+
it("should keep execaShellPath readable when present", () => {
162+
const result = globalSettingsSchema.parse({
163+
execaShellPath: "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
164+
})
165+
expect(result.execaShellPath).toBe("C:\\Program Files\\PowerShell\\7\\pwsh.exe")
166+
})
167+
168+
it("should keep execaShellPath undefined when absent", () => {
169+
const result = globalSettingsSchema.parse({})
170+
expect(result.execaShellPath).toBeUndefined()
171+
})
172+
})
173+
174+
describe("message payload type compilation", () => {
175+
// ── Type-level compile checks (runtime no-ops) ──────────────────────
176+
// These tests verify that the message payload types are correctly
177+
// typed and can carry the expected data shapes.
178+
179+
it("TerminalShellOption should have all required fields", () => {
180+
const option: TerminalShellOption = {
181+
id: "auto",
182+
label: "Auto (follow default profile)",
183+
family: "powershell",
184+
source: "os-default",
185+
available: true,
186+
}
187+
expect(option.id).toBe("auto")
188+
expect(option.label).toBe("Auto (follow default profile)")
189+
expect(option.family).toBe("powershell")
190+
expect(option.source).toBe("os-default")
191+
expect(option.available).toBe(true)
192+
})
193+
194+
it("TerminalShellOption family should accept all valid families", () => {
195+
const families: TerminalShellOption["family"][] = ["powershell", "cmd", "posix", "fish", "wsl"]
196+
families.forEach((family) => {
197+
const option: TerminalShellOption = {
198+
id: `test-${family}`,
199+
label: family,
200+
family,
201+
source: "test",
202+
available: true,
203+
}
204+
expect(option.family).toBe(family)
205+
})
206+
})
207+
208+
it("TerminalShellOptionsPayload should carry options and effectiveShell", () => {
209+
const payload: TerminalShellOptionsPayload = {
210+
options: [
211+
{
212+
id: "auto",
213+
label: "Auto",
214+
family: "powershell",
215+
source: "os-default",
216+
available: true,
217+
},
218+
{
219+
id: "profile:PowerShell",
220+
label: "PowerShell",
221+
family: "powershell",
222+
source: "vscode-default",
223+
available: true,
224+
},
225+
],
226+
effectiveShell: {
227+
label: "PowerShell 7 (pwsh.exe)",
228+
family: "powershell",
229+
source: "vscode-default",
230+
},
231+
}
232+
expect(payload.options).toHaveLength(2)
233+
expect(payload.effectiveShell?.family).toBe("powershell")
234+
})
235+
236+
it("TerminalShellOptionsPayload should allow error without effectiveShell", () => {
237+
const payload: TerminalShellOptionsPayload = {
238+
options: [],
239+
error: "SHELL/terminalShellOptions/001: profile discovery failed",
240+
}
241+
expect(payload.options).toHaveLength(0)
242+
expect(payload.error).toBeDefined()
243+
})
244+
245+
it("WebviewMessage should carry terminalShellSelection for setTerminalShellSelection", () => {
246+
const msg: WebviewMessage = {
247+
type: "setTerminalShellSelection",
248+
terminalShellSelection: { kind: "profile", profileName: "PowerShell" },
249+
}
250+
expect(msg.type).toBe("setTerminalShellSelection")
251+
expect(msg.terminalShellSelection?.kind).toBe("profile")
252+
})
253+
254+
it("WebviewMessage should carry requestTerminalShellOptions without payload", () => {
255+
const msg: WebviewMessage = {
256+
type: "requestTerminalShellOptions",
257+
}
258+
expect(msg.type).toBe("requestTerminalShellOptions")
259+
expect(msg.terminalShellSelection).toBeUndefined()
260+
})
261+
262+
it("ExtensionMessage should carry terminalShellOptions response", () => {
263+
const msg: ExtensionMessage = {
264+
type: "terminalShellOptions",
265+
terminalShellOptions: {
266+
options: [
267+
{
268+
id: "auto",
269+
label: "Auto",
270+
family: "posix",
271+
source: "os-default",
272+
available: true,
273+
},
274+
],
275+
effectiveShell: {
276+
label: "/bin/bash",
277+
family: "posix",
278+
source: "os-default",
279+
},
280+
},
281+
}
282+
expect(msg.type).toBe("terminalShellOptions")
283+
expect(msg.terminalShellOptions?.options).toHaveLength(1)
284+
})
285+
286+
it("TerminalShellSelection type should narrow correctly", () => {
287+
const pathSelection: TerminalShellSelection = { kind: "path", path: "/bin/zsh" }
288+
if (pathSelection.kind === "path") {
289+
// TypeScript narrows to the path variant
290+
expect(pathSelection.path).toBe("/bin/zsh")
291+
}
292+
293+
const profileSelection: TerminalShellSelection = {
294+
kind: "profile",
295+
profileName: "PowerShell",
296+
}
297+
if (profileSelection.kind === "profile") {
298+
expect(profileSelection.profileName).toBe("PowerShell")
299+
}
300+
301+
const autoSelection: TerminalShellSelection = { kind: "auto" }
302+
if (autoSelection.kind === "auto") {
303+
expect(autoSelection.kind).toBe("auto")
304+
}
305+
})
306+
307+
it("GlobalSettings should include terminalShellSelection as optional", () => {
308+
const settings: GlobalSettings = {}
309+
expect(settings.terminalShellSelection).toBeUndefined()
310+
311+
const settingsWithSelection: GlobalSettings = {
312+
terminalShellSelection: { kind: "auto" },
313+
}
314+
expect(settingsWithSelection.terminalShellSelection).toEqual({ kind: "auto" })
315+
})
316+
})

‎packages/types/src/global-settings.ts‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,25 @@ export const MAX_CHECKPOINT_TIMEOUT_SECONDS = 60
9797
*/
9898
export const DEFAULT_CHECKPOINT_TIMEOUT_SECONDS = 15
9999

100+
/**
101+
* TerminalShellSelection
102+
*
103+
* Discriminated union for the user-selected inline-terminal shell resolution
104+
* mode. Absence of the field (undefined) means Auto mode.
105+
*
106+
* - `auto`: follow trusted VS Code default/global profile, then OS default,
107+
* then safe platform fallback.
108+
* - `profile`: use a named trusted VS Code terminal profile.
109+
* - `path`: use an explicit executable path validated by the extension host.
110+
*/
111+
export const terminalShellSelectionSchema = z.discriminatedUnion("kind", [
112+
z.object({ kind: z.literal("auto") }),
113+
z.object({ kind: z.literal("profile"), profileName: z.string() }),
114+
z.object({ kind: z.literal("path"), path: z.string() }),
115+
])
116+
117+
export type TerminalShellSelection = z.infer<typeof terminalShellSelectionSchema>
118+
100119
/**
101120
* GlobalSettings
102121
*/
@@ -206,7 +225,24 @@ export const globalSettingsSchema = z.object({
206225
terminalZshP10k: z.boolean().optional(),
207226
terminalZdotdir: z.boolean().optional(),
208227
terminalProfile: z.string().optional(),
228+
/**
229+
* @deprecated Use `terminalShellSelection` instead. Retained for migration
230+
* from pre-unified settings; treated as a `legacyOverride` when
231+
* `terminalShellSelection` is absent.
232+
*/
209233
execaShellPath: z.string().optional(),
234+
/**
235+
* User-selected inline-terminal shell resolution mode.
236+
*
237+
* - `auto`: follow trusted VS Code default/global profile, then OS default,
238+
* then safe platform fallback (default when absent).
239+
* - `profile`: use a named trusted VS Code terminal profile.
240+
* - `path`: use an explicit executable path validated by the extension host.
241+
*
242+
* Absence of this field means Auto mode, preserving backward compatibility
243+
* with settings persisted before the unified shell resolution feature.
244+
*/
245+
terminalShellSelection: terminalShellSelectionSchema.optional(),
210246

211247
diagnosticsEnabled: z.boolean().optional(),
212248
autoCloseZooOpenedFiles: z.boolean().optional(),

‎packages/types/src/terminal.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ export const commandExecutionStatusSchema = z.discriminatedUnion("status", [
2424
z.object({
2525
executionId: z.string(),
2626
status: z.literal("fallback"),
27+
reasonCode: z.string().optional(),
2728
}),
2829
z.object({
2930
executionId: z.string(),
@@ -33,6 +34,16 @@ export const commandExecutionStatusSchema = z.discriminatedUnion("status", [
3334
executionId: z.string(),
3435
status: z.literal("error"),
3536
message: z.string().optional(),
37+
code: z.string().optional(),
38+
}),
39+
z.object({
40+
executionId: z.string(),
41+
status: z.literal("queued"),
42+
}),
43+
z.object({
44+
executionId: z.string(),
45+
status: z.literal("recovering"),
46+
errorCode: z.string().optional(),
3647
}),
3748
])
3849

0 commit comments

Comments
 (0)