Observations from the first of three screen-capture sessions in which a developer used Jasper for the first time and narrated as he went. This issue covers the initial setup / connection configuration experience. Timestamps refer to video 1.
Context
The goal was simple and should be a first-class use case: run Jasper in VS Code on a Mac workstation and connect to a stone running on a remote Linux host. He never got there in this session — he had to stop and go do out-of-band setup work that the extension never told him about.
Problems and stumbling blocks
1. Running Jasper over VS Code Remote-SSH behaves differently, with no explanation (0:27–1:03)
He first tried running Jasper in a VS Code window connected over Remote-SSH to the Linux host, and saw "definitely different behavior" from a local window. His conclusion: "it looks like I was attempting a use case that we haven't anticipated yet… in future versions, we may want Jasper to be able to handle the situation where it's running in an SSH session on a Linux box."
(Video 3 revealed the real cause — extension install over Remote-SSH is just slow and silent. Tracked separately.) The takeaway that still stands: nothing in the UI told him what was going on, so he reasonably concluded the scenario was unsupported.
2. Leftover configuration from a prior attempt is unreadable and un-resettable (1:11–3:43)
He was not starting clean, and spent roughly two and a half minutes trying to work out what an existing configuration pointed at: "This configuration was left over from a prior attempt to use Jasper, and I honestly don't recall…" … "this is pointing to a stone that I don't remember where it is located" … "I wonder if this was like a sample or something that was downloaded before."
3. Configuration field labels don't say what they mean (1:48–2:54)
Reading a path field: "that's just the path where the configuration is stored, I believe." It wasn't. Later, reading the extent field — .../gemstone/DB1/data extent — he had to go check the filesystem to work out whether this described a stone running locally on his own machine.
4. The new-configuration flow led him down the wrong path entirely (3:43–5:19)
Wanting to reach a remote stone, the affordance he found was new database configuration — a local-stone wizard. He worked through version, extent, and stone name, then reached the host field, realized this wasn't going to work, went to the documentation, and discovered prerequisites: identify the NetLDI configuration on the remote host, then make local changes on the Mac. He pressed Escape and abandoned the flow: "before I complete these steps, in fact, I think I'll just escape."
Two distinct failures here:
Suggested enhancements
- Surface the remote-connection prerequisites as an inline checklist rather than a separate document.
- Detect and report a missing/mismatched local services entry with an actionable message instead of a connection failure.
- Provide a way to inspect and reset accumulated configuration state.
Observations from the first of three screen-capture sessions in which a developer used Jasper for the first time and narrated as he went. This issue covers the initial setup / connection configuration experience. Timestamps refer to video 1.
Context
The goal was simple and should be a first-class use case: run Jasper in VS Code on a Mac workstation and connect to a stone running on a remote Linux host. He never got there in this session — he had to stop and go do out-of-band setup work that the extension never told him about.
Problems and stumbling blocks
1. Running Jasper over VS Code Remote-SSH behaves differently, with no explanation (0:27–1:03)
He first tried running Jasper in a VS Code window connected over Remote-SSH to the Linux host, and saw "definitely different behavior" from a local window. His conclusion: "it looks like I was attempting a use case that we haven't anticipated yet… in future versions, we may want Jasper to be able to handle the situation where it's running in an SSH session on a Linux box."
(Video 3 revealed the real cause — extension install over Remote-SSH is just slow and silent. Tracked separately.) The takeaway that still stands: nothing in the UI told him what was going on, so he reasonably concluded the scenario was unsupported.
2. Leftover configuration from a prior attempt is unreadable and un-resettable (1:11–3:43)
He was not starting clean, and spent roughly two and a half minutes trying to work out what an existing configuration pointed at: "This configuration was left over from a prior attempt to use Jasper, and I honestly don't recall…" … "this is pointing to a stone that I don't remember where it is located" … "I wonder if this was like a sample or something that was downloaded before."
3. Configuration field labels don't say what they mean (1:48–2:54)
Reading a path field: "that's just the path where the configuration is stored, I believe." It wasn't. Later, reading the extent field —
.../gemstone/DB1/data extent— he had to go check the filesystem to work out whether this described a stone running locally on his own machine.4. The new-configuration flow led him down the wrong path entirely (3:43–5:19)
Wanting to reach a remote stone, the affordance he found was new database configuration — a local-stone wizard. He worked through version, extent, and stone name, then reached the host field, realized this wasn't going to work, went to the documentation, and discovered prerequisites: identify the NetLDI configuration on the remote host, then make local changes on the Mac. He pressed Escape and abandoned the flow: "before I complete these steps, in fact, I think I'll just escape."
Two distinct failures here:
Wrong entry point. "Create a database configuration" and "connect to an existing remote stone" are different tasks, and the UI offered him the former when he wanted the latter.
Undeclared prerequisites. The out-of-band steps (remote NetLDI, local
/etc/services) live only in prose documentation, discovered by accident partway through a wizard.Separate "define a local stone" from "connect to an existing remote stone" as distinct, clearly labeled entry points.
State prerequisites up front in the remote-connection flow — ideally detect the missing local pieces and link straight to the relevant documentation section.
Suggested enhancements