ChatGPTClaudeGrok / X / CursorGemini

DSH plugin code organization: apply, layers, and packages

Plugin DevelopmentPublished 2026-11-17Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessplugin developmentcode organizationtestability
A 400-line apply makes every edit risky. Three tests for assembly-only apply, three dependency layers, a ctx boundary, and when to ship a package.

Every plugin starts tidy and ends with an apply that reads like a stew. Registration, parsing, formatting, and retries land in one function, and after that every change means re-reading the whole thing. There is no single correct layout for a DSH plugin, but there is one hard line: assembly stays assembly, computation stays computation.

Three tests for a DSH plugin assembly-only apply

Business branching inside apply is the signal to split. (source)

Check three properties; failing any one means it is time to move code:

  1. Registration only -- register tools, record disposables, subscribe to events. No input parsing, no computing results.
  2. No domain if/for -- the moment apply branches on business conditions, logic has leaked in.
  3. Failure only at registration -- an apply that throws should mean "cannot register", never "one record failed to process".

Meet all three and apply tends to run a few dozen lines: a handful of ctx.tools.register, a few ctx.effect, a couple of ctx.on. A reader sees what the plugin offers at a glance.

DSH plugin first cut: split along dependencies

Decide who depends on whom before deciding how big files should be. (source)

Most plugins have three layers: assembly (touches ctx), domain (pure logic), and adapter (talks to the outside -- files, network, storage).

The dependency arrow points one way. Assembly depends on domain and adapter; domain never reaches back. Cutting along that arrow yields three kinds of files, rather than a scatter of "one file per tool" and "one file per event".

The payoff is testability. Domain never touches ctx and can be tested directly; adapters accept fake implementations; assembly only loads when you actually verify registrations.

Where DSH plugin ctx may travel

ctx is a registration entry, not a global container. (source)

The most common smell is threading ctx into business functions. The direct consequence: the module cannot exist without the framework, every unit test needs a fake ctx, and the test ends up exercising the framework instead of your logic.

Do this instead -- pull what you need out in the assembly layer and pass it down:

  1. Registering capability -- call in assembly; the business layer only describes what to register.
  2. Reading config -- read in assembly and pass the value as an argument.
  3. Callbacks -- expose a pure function from the business layer and wrap it as a handler in assembly.

Once that boundary holds, business signatures contain neither ctx nor framework types.

Extract DSH plugin pure functions

Code is testable only if it runs without the harness. (source)

The test is concrete: can the function be called from node -e? If yes, it is pure. If not, it depends on the runtime.

Three candidates are worth extracting: argument normalization, result shaping, and error classification. All three are called repeatedly, all three are easy to get subtly wrong, and all three can be covered with table-driven cases once separated.

Two cautions. Do not smuggle IO into a pure function -- reading files and sending requests are not pure. And do not chase purity by exploding the context into a dozen parameters; a plain object is fine.

When a second DSH plugin is justified

Packaging is a release decision, not a tidiness decision. (source)

Three questions settle it:

  1. Must it be enabled or unloaded independently? Then mount a child with ctx.plugin, each with its own Fiber.
  2. Must a third party depend on it? Then publish a separate package exposing a service for injection.
  3. Do you merely want shorter files? Then split modules and leave lifecycle and package boundaries untouched.

Questions 2 and 3 are the ones people confuse. A package carries version numbers, a release process, and dependency declarations -- three costs that internal-only code should not pay.

A DSH plugin directory layout that scales

Four files cover most small and medium plugins. (source)

A reasonable starting point:

  1. src/index.ts -- exports name, inject, and apply; assembly only.
  2. src/domain.ts -- pure functions: normalization, validation, shaping, error classification.
  3. src/adapter.ts -- outside world: file reads, seam calls, exposed as plain functions.
  4. src/types.ts -- public types and declaration merging, no implementation.

Grow by splitting adapter.ts into several files, and keep one assembly entry forever. A newcomer reads index.ts, learns what the plugin offers, and only then follows the trail downward.

Verification: test without booting the harness

Everything outside the assembly layer should run in an empty process. (source)

  1. Import domain.ts directly and assert outputs for several inputs, with no framework import in sight.
  2. Inject a fake into adapter.ts and assert the expected shape on failure and timeout.
  3. Call apply with a minimal fake ctx and assert the expected number of capabilities register, with no side effects.
  4. Mount a child through ctx.plugin and assert parent and child unload in the expected order.
  5. Break one branch in domain.ts and assert the failure points at a specific function instead of a wall of red.

Needing a ctx in step 1 means business logic is still glued to the framework. An unfocused failure in step 5 means the test granularity is too coarse.

For deeper guidance on packaging and dependency placement, read capabilities in three packages; for test organization without a live model, see testing plugins.

One line to close: apply assembles and nothing else, files follow the dependency direction, ctx never leaves the assembly layer, pure functions get their own file, and you split a child plugin for lifecycle while you split a package only when someone else must depend on it.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

How many lines can a DSH plugin apply have before splitting?

For a DSH plugin apply, count responsibilities, not lines. A DSH apply should only assemble: register tools, register resources, wire events. The moment parsing, computing, or formatting appears, it belongs elsewhere. The tell is business branching inside apply, not a specific line number.

Should DSH plugin ctx be passed into every module I split?

Pass DSH plugin ctx only where a capability gets registered. In DSH, ctx is a registration entry point, not a global container; handing it to a pure module couples that module to the framework and makes it hard to test. Keep ctx in the assembly layer and pass data and callbacks downward.

DSH plugin child via ctx.plugin, or another source file?

DSH plugin ctx.plugin gives a child its own Fiber and lifecycle; a separate file is only code. Use it when that part must be enabled or unloaded on its own. If you just want shorter files, split modules and leave the lifecycle alone.

When should a DSH plugin part become its own package?

When another DSH plugin needs to depend on it independently. DSH installs plugins as packages, so capability meant for third-party injection belongs in its own service package. Code reused only inside one plugin pays packaging cost for nothing.

Related Terms

apply
apply is the synchronous entry point of a DSH plugin; it mounts capabilities onto the context and, ideally, only registers and wires, never computes business logic.— DeepSeek Harness Docs - Your First Plugin
ctx.plugin
ctx.plugin is the API that mounts a child plugin with its own Fiber and lifecycle; when the parent unloads, children are unloaded recursively.— DeepSeek Harness Docs - Plugins and Lifecycle
Fiber
A Fiber is the lifecycle scope of one plugin instance; the assembly layer and each child plugin own separate Fibers whose registrations are cleared on unload.— DeepSeek Harness Docs - Plugins and Lifecycle
assembly layer
The assembly layer is the only part of a plugin that touches ctx; it registers capabilities, records disposables, and hands data and callbacks to business modules.— DeepSeek Harness Docs - Plugins and Lifecycle

Sources