Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 16 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,35 +5,37 @@ one in a new window, without leaving the editor.

## Requirements

- VS Code 1.120 or newer, or an editor built on it that installs from Open VSX (VSCodium,
- VS Code 1.146 or newer, or an editor built on it that installs from Open VSX (VSCodium,
Cursor, ...).
- A Remote-SSH extension: Microsoft's `ms-vscode-remote.remote-ssh` in VS Code, or
`jeanp413.open-remote-ssh` elsewhere. When none is installed, Spinbox offers to install the one
your editor's marketplace carries.
- A Spinbox account, with an SSH key of this machine added to it. If none is, Spinbox says so and
offers to add one.

The extension carries the `spin` CLI it needs, for Linux and macOS on x64 and arm64: there is
nothing else to install.

## Spinbox's own connection

With `spin-stack.open-remote-ssh` installed and allowed VS Code's proposed API, Spinbox opens a
workspace as `vscode-remote://spin+<workspace>/...` instead of over Remote-SSH: the connection is
Spinbox's, so a workspace that does not open says why, in VS Code, with what to do. Its server
comes from your installation, never a download.
With **Spinbox Remote** (`spin-stack.spinbox-remote`) installed and allowed VS Code's proposed
API, Spinbox opens a workspace as `vscode-remote://spin+<workspace>/...` instead of over
Remote-SSH: the connection is Spinbox's, so a workspace that does not open says why, in VS Code,
with what to do. Its server comes from your installation, never a download.

VS Code, VSCodium and the other editors let a third-party extension use a proposed API only when
`argv.json` names it. Run **Preferences: Configure Runtime Arguments**, add this line inside the
object it opens, and restart the editor:
1. Install it with `spin vscode install`. The Visual Studio Marketplace does not carry an extension
that uses a proposed API.
2. VS Code lets a third-party extension use a proposed API only when `argv.json` names it. Run
**Preferences: Configure Runtime Arguments**, add this line inside the object it opens, and
restart VS Code:

```jsonc
"enable-proposed-api": ["spin-stack.open-remote-ssh"]
```
```jsonc
"enable-proposed-api": ["spin-stack.spinbox-remote"]
```

Spinbox checks for it on every open: until the resolver activates, workspaces open over Remote-SSH,
and Spinbox says once what is missing.

The extension carries the `spin` CLI it needs, for Linux and macOS on x64 and arm64: there is
nothing else to install.

## Getting started

1. Install **Spinbox** from the Extensions view.
Expand Down
5 changes: 1 addition & 4 deletions Taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,10 @@ tasks:
- pnpm test:cli

test:integration:
desc: test:cli, then the extension activated in a real VS Code, downloaded into .vscode-test/ - the one engines.vscode names, and versions.yaml's vscode for the resolver's detection. Under xvfb-run when it is installed, which CI's runner has; otherwise on the display there is.
desc: test:cli, then the extension activated in a real VS Code, downloaded into .vscode-test/. Under xvfb-run when it is installed, which CI's runner has; otherwise on the display there is.
vars:
XVFB:
sh: command -v xvfb-run || true
env:
VSCODE_GATED:
sh: versions version vscode
cmds:
- task: test:cli
- task: build
Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
},
"packageManager": "pnpm@11.27.1",
"engines": {
"vscode": "^1.120.0"
"vscode": "^1.146.0"
},
"categories": [
"Other"
Expand Down Expand Up @@ -217,7 +217,7 @@
"devDependencies": {
"@biomejs/biome": "2.6.3",
"@types/node": "22.20.5",
"@types/vscode": "1.120.0",
"@types/vscode": "1.146.0",
"@vscode/test-electron": "3.1.0",
"@vscode/vsce": "4.1.0",
"esbuild": "0.28.2",
Expand Down
10 changes: 5 additions & 5 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

26 changes: 13 additions & 13 deletions src/remote/resolver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,26 @@ import * as vscode from "vscode"
import { SPIN_RESOLVER } from "../status/authority"
import { ensureRemoteExtension } from "./extension"

// spin-stack/open-remote-ssh resolves vscode-remote://spin+<workspace> through the spin CLI, and
// shows what refuses the connection, which Remote-SSH leaves in its log. It runs on VS Code's
// proposed resolvers API, which an editor grants a third-party extension only when argv.json
// names it. So it is no extensionDependencies of this extension: a dependency that fails to
// activate keeps the extension that depends on it from activating, and Remote-SSH with it.
// Spinbox Remote resolves vscode-remote://spin+<workspace> through the spin CLI, and shows what
// refuses the connection, which Remote-SSH leaves in its log. It runs on VS Code's proposed
// resolvers API, which VS Code grants a third-party extension only when argv.json names it. So it
// is no extensionDependencies of this extension: a dependency that fails to activate keeps the
// extension that depends on it from activating, and Remote-SSH with it. The Marketplace refuses an
// extension that uses a proposed API, so `spin vscode install` installs it beside this one.

// The line argv.json needs for the resolver to run.
export const ENABLE_PROPOSED_API = `"enable-proposed-api": ["${SPIN_RESOLVER}"]`

// A build of the resolver that answers spin+ activates on it (its package.json).
const RESOLVES_SPIN = "onResolveRemoteAuthority:spin"

// Where Spinbox keeps the last reason it told the person, so each is told once.
export const TOLD_KEY = "spinbox.resolverHint"

const OPEN_ARGV = "Open argv.json"

// Why a workspace opens over Remote-SSH: no build of the resolver that answers spin+ is installed,
// or one is and VS Code did not let it activate.
// What installs Spinbox Remote: the Marketplace, which VS Code reads, cannot carry it.
export const INSTALL = "spin vscode install"

// Why a workspace opens over Remote-SSH: the resolver is not installed, or it is and VS Code did
// not let it activate.
export type Fallback = "missing" | "disabled"

export type Route = { spin: true } | { spin: false; because: Fallback }
Expand All @@ -29,8 +30,7 @@ export type Route = { spin: true } | { spin: false; because: Fallback }
// proposed API, its registerRemoteAuthorityResolver throws, and the activation rejects.
export async function route(): Promise<Route> {
const ext = vscode.extensions.getExtension(SPIN_RESOLVER)
const events: unknown = ext?.packageJSON?.activationEvents
if (ext === undefined || !Array.isArray(events) || !events.includes(RESOLVES_SPIN)) {
if (ext === undefined) {
return { spin: false, because: "missing" }
}
try {
Expand Down Expand Up @@ -65,7 +65,7 @@ function tellOnce(state: vscode.Memento, because: Fallback): void {
const message =
because === "disabled"
? `Spinbox opens workspaces over Remote-SSH: VS Code does not let ${SPIN_RESOLVER} use the proposed API it opens them with. To open them through Spinbox's own connection, which says why one does not open, ${enable}.`
: `Spinbox opens workspaces over Remote-SSH. To open them through Spinbox's own connection, which says why one does not open, install ${SPIN_RESOLVER}, ${enable}.`
: `Spinbox opens workspaces over Remote-SSH. To open them through Spinbox's own connection, which says why one does not open, install Spinbox Remote (${SPIN_RESOLVER}) by running \`${INSTALL}\` in a terminal, ${enable}.`
void Promise.resolve(vscode.window.showInformationMessage(message, OPEN_ARGV)).then((pick) =>
pick === OPEN_ARGV
? vscode.commands.executeCommand("workbench.action.configureRuntimeArguments")
Expand Down
6 changes: 3 additions & 3 deletions src/status/authority.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// The Spinbox workspace a window is connected to, read from its remote authority: Remote-SSH's
// ssh-remote+spin.<workspace>, or spin+<workspace>, which spin-stack.open-remote-ssh resolves.
// ssh-remote+spin.<workspace>, or spin+<workspace>, which Spinbox Remote resolves.
export interface SpinRemote {
// The SSH host spin code wrote into the SSH config: spin.<workspace>.
host: string
Expand All @@ -10,8 +10,8 @@ export interface SpinRemote {

const PREFIX = "ssh-remote+"

// The extension that resolves spin+<workspace> (src/remote/resolver.ts).
export const SPIN_RESOLVER = "spin-stack.open-remote-ssh"
// Spinbox Remote, the extension that resolves spin+<workspace> (src/remote/resolver.ts).
export const SPIN_RESOLVER = "spin-stack.spinbox-remote"

// The authority its src/spin/authority.ts resolves, a workspace by the same rule.
const SPIN_PREFIX = "spin+"
Expand Down
25 changes: 10 additions & 15 deletions test/integration/run.mjs
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
// Starts VS Code stable, downloaded into .vscode-test/, with this extension loaded and the suite
// dist-test/suite.js run in its extension host, three times:
// Starts VS Code stable, downloaded into .vscode-test/ at the version engines.vscode names, with
// this extension loaded and the suite dist-test/suite.js run in its extension host, three times:
//
// - at the version engines.vscode names, alone: the resolver is missing;
// - at VSCODE_GATED (versions.yaml's vscode, set by task test:integration) with the stand-in
// for spin-stack.open-remote-ssh in testdata/resolver/, as VS Code is installed: it withholds
// the proposed API, so the resolver is disabled;
// - alone: the resolver is missing;
// - with the stand-in for spin-stack.spinbox-remote in testdata/resolver/, as VS Code is
// installed: it withholds the proposed API, so the resolver is disabled;
// - the same with --enable-proposed-api for the stand-in, which is what argv.json's
// enable-proposed-api line gives: the resolver is active.
//
Expand All @@ -16,19 +15,15 @@ import { runTests } from "@vscode/test-electron"

const root = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
const { engines } = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"))
const gated = process.env.VSCODE_GATED
if (!gated) {
throw new Error("VSCODE_GATED names no VS Code version: run it as task test:integration")
}
const resolver = resolve(root, "test/integration/testdata/resolver")

for (const [route, version, extensions, flags] of [
["missing", engines.vscode.replace(/^\^/, ""), [root], []],
["disabled", gated, [root, resolver], []],
["spin", gated, [root, resolver], ["--enable-proposed-api", "spin-stack.open-remote-ssh"]],
for (const [route, extensions, flags] of [
["missing", [root], []],
["disabled", [root, resolver], []],
["spin", [root, resolver], ["--enable-proposed-api", "spin-stack.spinbox-remote"]],
]) {
await runTests({
version,
version: engines.vscode.replace(/^\^/, ""),
extensionDevelopmentPath: extensions,
extensionTestsPath: resolve(root, "dist-test/suite.js"),
extensionTestsEnv: { SPINBOX_WANT_ROUTE: route },
Expand Down
2 changes: 1 addition & 1 deletion test/integration/testdata/resolver/extension.cjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// What spin-stack.open-remote-ssh's activation does first that the proposed API decides: register
// What spin-stack.spinbox-remote's activation does first that the proposed API decides: register
// a remote authority resolver. VS Code throws here when the API is withheld.
const vscode = require("vscode")

Expand Down
8 changes: 4 additions & 4 deletions test/integration/testdata/resolver/package.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "open-remote-ssh",
"displayName": "A stand-in for spin-stack.open-remote-ssh",
"description": "Registers the spin resolver as spin-stack.open-remote-ssh does, so the suite checks Spinbox's detection of it against a real VS Code.",
"name": "spinbox-remote",
"displayName": "A stand-in for Spinbox Remote",
"description": "Registers the spin resolver as spin-stack.spinbox-remote does, so the suite checks Spinbox's detection of it against a real VS Code.",
"version": "0.0.0",
"publisher": "spin-stack",
"private": true,
"engines": {
"vscode": "^1.120.0"
"vscode": "^1.146.0"
},
"extensionKind": [
"ui"
Expand Down
78 changes: 33 additions & 45 deletions test/unit/resolver.test.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,9 @@
import { beforeEach, describe, expect, it, vi } from "vitest"

// The vscode API the modules reach: the installed extensions, each with its activation events and
// what its activation does, as a map the test controls.
// The vscode API the modules reach: the installed extensions, each with what its activation does,
// as a map the test controls.
const vscode = vi.hoisted(() => {
const installed = new Map<
string,
{ packageJSON: { activationEvents: string[] }; activate: () => Promise<unknown> }
>()
const installed = new Map<string, { activate: () => Promise<unknown> }>()
return {
installed,
env: { appName: "Visual Studio Code" },
Expand All @@ -31,31 +28,31 @@ vi.mock("vscode", () => vscode)

import type { Memento } from "vscode"
import { MICROSOFT_REMOTE_SSH } from "../../src/remote/extension"
import { ENABLE_PROPOSED_API, openThrough, route, TOLD_KEY } from "../../src/remote/resolver"
import {
ENABLE_PROPOSED_API,
INSTALL,
openThrough,
route,
TOLD_KEY,
} from "../../src/remote/resolver"
import { SPIN_RESOLVER } from "../../src/status/authority"

// The resolver, installed: one that answers spin+ unless events say otherwise, and whose
// activation rejects as it does when VS Code withholds the proposed API.
function installResolver(
opts: { events?: string[]; refused?: boolean } = {},
): ReturnType<typeof vi.fn> {
// The resolver, installed, whose activation rejects when refused, as it does when VS Code
// withholds the proposed API.
function installResolver(opts: { refused?: boolean } = {}): ReturnType<typeof vi.fn> {
const activate = vi.fn(async () => {
if (opts.refused === true) {
throw new Error("Extension 'spin-stack.open-remote-ssh' CANNOT use API proposal: resolvers.")
throw new Error("Extension 'spin-stack.spinbox-remote' CANNOT use API proposal: resolvers.")
}
})
vscode.installed.set(SPIN_RESOLVER, {
packageJSON: {
activationEvents: opts.events ?? [
"onResolveRemoteAuthority:ssh-remote",
"onResolveRemoteAuthority:spin",
],
},
activate,
})
vscode.installed.set(SPIN_RESOLVER, { activate })
return activate
}

function installRemoteSSH(): void {
vscode.installed.set(MICROSOFT_REMOTE_SSH, { activate: async () => {} })
}

function memento(): Memento & { values: Map<string, unknown> } {
const values = new Map<string, unknown>()
return {
Expand Down Expand Up @@ -87,13 +84,6 @@ describe("route", () => {
expect(await route()).toEqual({ spin: false, because: "missing" })
})

// A build of open-remote-ssh from before the resolver activates fine and answers no spin+.
it("falls back, without activating it, when the build installed answers no spin+", async () => {
const activate = installResolver({ events: ["onResolveRemoteAuthority:ssh-remote"] })
expect(await route()).toEqual({ spin: false, because: "missing" })
expect(activate).not.toHaveBeenCalled()
})

it("falls back when VS Code does not let the resolver activate", async () => {
installResolver({ refused: true })
expect(await route()).toEqual({ spin: false, because: "disabled" })
Expand All @@ -112,32 +102,33 @@ describe("openThrough", () => {

it("opens over Remote-SSH and says, with the exact argv.json line, what the resolver needs", async () => {
installResolver({ refused: true })
vscode.installed.set(MICROSOFT_REMOTE_SSH, {
packageJSON: { activationEvents: [] },
activate: async () => {},
})
installRemoteSSH()
vscode.window.showInformationMessage.mockResolvedValue(undefined)
expect(await openThrough(memento())).toBe(false)
expect(vscode.window.showInformationMessage).toHaveBeenCalledOnce()
const [message] = vscode.window.showInformationMessage.mock.calls[0] ?? []
expect(ENABLE_PROPOSED_API).toBe('"enable-proposed-api": ["spin-stack.open-remote-ssh"]')
expect(ENABLE_PROPOSED_API).toBe('"enable-proposed-api": ["spin-stack.spinbox-remote"]')
expect(message).toContain(ENABLE_PROPOSED_API)
expect(message).toContain("does not let")
})

it("says how to install the resolver when it is missing", async () => {
installRemoteSSH()
vscode.window.showInformationMessage.mockResolvedValue(undefined)
await openThrough(memento())
const [message] = vscode.window.showInformationMessage.mock.calls[0] ?? []
expect(INSTALL).toBe("spin vscode install")
expect(message).toContain(`${SPIN_RESOLVER}) by running \`spin vscode install\``)
expect(message).toContain(ENABLE_PROPOSED_API)
})

it("tells each reason once", async () => {
vscode.installed.set(MICROSOFT_REMOTE_SSH, {
packageJSON: { activationEvents: [] },
activate: async () => {},
})
installRemoteSSH()
vscode.window.showInformationMessage.mockResolvedValue(undefined)
const state = memento()
await openThrough(state)
await openThrough(state)
expect(vscode.window.showInformationMessage).toHaveBeenCalledOnce()
expect(vscode.window.showInformationMessage.mock.calls[0]?.[0]).toContain(
`install ${SPIN_RESOLVER}`,
)
expect(state.values.get(TOLD_KEY)).toBe("missing")

// Installed since, and held back by VS Code: a new reason, told once too.
Expand All @@ -149,10 +140,7 @@ describe("openThrough", () => {
})

it("opens argv.json when the person asks", async () => {
vscode.installed.set(MICROSOFT_REMOTE_SSH, {
packageJSON: { activationEvents: [] },
activate: async () => {},
})
installRemoteSSH()
vscode.window.showInformationMessage.mockImplementation(async (_m, ...items) => items[0])
await openThrough(memento())
await vi.waitFor(() =>
Expand Down
Loading
Loading