Services and adapters

Status: current. This page describes the services and adapters as they stand after the last phase of the refactor plan.

The problem this solves

The decisions lived in the routing. Until Phase 5, activate() in src/extension.ts ran from line 187 to 1294 and registered all 102 commands. Webview message handlers are long switch chains that decide inline: DashboardPanel.handleValidMessage covers 40 message types in 250 lines. Command files such as renameTag.ts and parking.ts hold the domain rules and the user-facing text in one function of 60 to 170 lines. The same rule is written in several places, and the copies disagree: which index entity makes an openSource line openable has three different answers across four hosts.

The fix is one split, applied everywhere. A service decides. An adapter asks and reports.

What a service is

A service owns one capability. It is a class with three properties:

• It takes its collaborators in its constructor: ports, other services, and an index reader.
• Its methods take plain arguments and return result objects. It never calls vscode.window.
• It can be unit-tested without the extension host.

The service catalog

Phase 4 also moved review and templates into services, and made quick find’s row actions and the assistant tools one table each. The assistant table is shared by the MCP server and the language-model tools, whose refusal strings had drifted apart.

The assistant tool table, ASSISTANT_TOOLS in src/ui/state/assistantTools.ts, names each of the four tools, reads its input, binds it to what it runs, and carries each surface’s refusal text and timing name side by side. AssistantTools (the language-model tools) and DeckardMcpServer both iterate it, and each only adapts a call to its transport. The language-model side alone keeps the deckard.assistantTools guard, the once-a-session confirmation, and the progress messages; the MCP server waits for the first scan and has no guard. The two writes are handed to the table as runners, since they need the editor. The table sits in ui/state rather than services because it answers through getQueryBlockSnapshot, which is still there.

Find’s row actions are one table, ROW_ACTIONS in src/ui/commands/quickFindActions.ts: for each action, whether it needs the row’s task, whether it leaves Find open, and what it does, through a RowActionHost that holds Find’s own opening and showing and the services the writes go to (PinService, the favorites and recent searches of the preferences, and the task functions every view writes with). STAYING_ACTIONS is read from it, and QuickFind.runAction only refuses a task that is gone and runs the entry.

The preferences are services too, one per capability over one PreferencesRepository, and since Phase 4 each command, view, and page takes only the ones it uses, picked from PreferenceServices in src/core/storage/preferences.ts. preferences.md lists who receives what.

What an adapter is

A command handler, a message handler, and a tree action are all adapters. Each does exactly three things, in order:

1. Gather input: the arguments, a QuickPick, or an InputBox. Return early on cancel.
2. Call one service method.
3. Present the result: a message, an Undo offer, or a reveal.

An adapter holds no domain decisions. If a handler needs an if about the notes, rather than about the reader’s answer, that if belongs in the service.

/**
 * Parks the chosen notes. Which notes can be parked, and why the others
 * cannot, is ParkingService's decision; this only asks and reports.
 */
export async function parkNotesCommand(services: Services, uris?: vscode.Uri[]): Promise<void> {
  const chosen = uris ?? (await pickNotes());
  if (!chosen?.length) {
    return;
  }

  const result = await services.parking.parkNotes(chosen.map(toPath));
  await reportParking(result);
}

Two existing files are the models. insertLink.ts is one pure builder and one thin adapter. taskSteps.ts has StepList, a class that models a QuickPick’s state so the prompt is only wiring. CaptureBox in captureBox.ts does the same for Capture, in place of the seven mutable lets askForCapture once held.

Result objects

A service method returns a discriminated union, for example { kind: 'refused', reason: 'already-parked', paths } or { kind: 'stale' }. Every outcome is then a value that a unit test can assert, and the adapter turns it into words.

None of the surveyed extensions does this. Foam returns or throws, Dendron returns undefined for cancellation, and GitLens and VS Code’s git extension throw typed errors. Deckard keeps result objects for refusals and borrows the wrapper those two use.

runCommand

Every command is registered through registerCommand(id, handler) in src/ui/commands/runCommand.ts, which registers the handler that runCommand(id, handler) wraps. The wrapper does two things:

• A vscode.CancellationError is the reader backing out. It is swallowed, and the command returns undefined.
• Any other exception is written to Deckard’s log as The command <id> failed: <message>, through reportError, and thrown on unchanged.

It shows no message of its own. The plan called for one generic message, but a command that words a failure already says so itself, and an exception a command lets through has always been reported by VS Code’s own notification, or by a rejected executeCommand when code ran it. A generic message would be a second message, or a new one, so the wrapper only logs and lets VS Code report as it always has: whatever a command showed before, it shows now, and nothing more. A handler’s result passes through as it was: a value at once, a promise as a promise that settles the same way. run-command.test.ts holds the three outcomes.

Composition

extension.ts is the composition root, and activate() is four lines:

1. createServices(context) in src/composition/services.ts builds every port implementation, store, service, index, provider, view, page host, and status bar once, into one typed Services object, and hands every disposable to context.subscriptions.
2. runFeatures(features, context, services) runs each feature’s register(context, services), in the order of src/composition/features.ts.
3. startServices(services) starts what reads the notes: Home on startup when the setting asks, the status bar’s first draw, and the first index, which prunes the preferences once it is read.
4. It returns DeckardExports, the Markdown preview’s extendMarkdownIt.

createServices builds in the order activation always did, because VS Code can see it: which provider registers first, which listener hears an index update first, and which context key is set first all follow from it. Only the command registrations that sat between those steps moved out, to the features. Within one synchronous activation VS Code cannot tell when a command was registered, and its registry is keyed by id.

Services holds what a feature, the startup steps, or the exports reach, grouped where that reads naturally: preferences (the repository, one service per capability, the snapshots, and Move to…’s pair), writes (tasks, tags, parking, rollover, reviews, templates, and Add Task), links, pages (one host per page), views (the sidebar views, the two trees, and the task status bar), and pageCommands, the two functions page modules export that commands call, since a command may not import a page host’s module. What only lives to be disposed, such as a completion provider or a context key, is owned by context.subscriptions alone.

A feature is a (context, services) => void | Promise<void> in src/ui/commands/<feature>/register.ts, one per capability. There are twenty: nineteen ordered by where each one’s first command was registered in activate() before Phase 5, and the Hubs view, added after, last:

runFeatures runs each feature synchronously, in its own try. One that throws, or whose promise rejects, is written to the log as Deckard could not register <feature>, and the rest still register. The plan named Promise.allSettled; a loop does the same for features that are all synchronous, and keeps activate() synchronous, so every command exists and the exports are returned by the time VS Code counts Deckard active. This is Foam’s pattern; Markdown All in One and the git extension do the same.

The ten commands that only turn one setting on and off are rows of SETTING_TOGGLES in src/ui/commands/toggles/settingToggles.ts: an enable and a disable command, the setting, its two values, and the target it is written to, where-set, outline, or zen. setting-toggles.test.ts runs under test:unit.

There is no dependency-injection container and no static locator. GitLens’s Container.instance and Dendron’s ExtensionProvider both carry comments working around a static locator. Decorator containers such as tsyringe and inversify need reflect-metadata and emitDecoratorMetadata, which esbuild does not support without a Babel shim. A plain object built once is enough, and it is what lets services run under the fast test tier.

Everything still registers in activate(). Since VS Code 1.74, contributed commands need no onCommand events, and the index already builds in the background.

activeServices, the ExtensionServices interface, and deactivate() are gone; context.subscriptions releases everything. VS Code runs an extension’s deactivate(), then disposes its subscriptions in the order they were pushed. The old deactivate() disposed 27 services first, in an order of its own, while the log was open, and two of those disposals redraw something: a search page that is the active search releases it, which redraws Related Notes, and Related Notes going hides itself from the active calendar, which redraws the Calendar page. So createServices pushes a DisposalOrder first and hands it those 27 in that order, which keeps the moment and the order, and each is now disposed once rather than twice.

Replacing hidden state

Module-level lets stood in for injection, and pure functions read them. Four test suites reset them in teardown, and one forgotten reset leaked into unrelated suites. Each now has an owner, and a suite builds its own.

The WeakMap caches keyed by a WorkspaceIndex snapshot stay. They memoize per snapshot, so they cannot outlive the data they describe.