Preface

DSH’s plugin model emphasizes “everything is a plugin.” The community directory is an independent site with no official affiliation to DeepSeek / Huafan and should not be interpreted as an official app store.

For DSH plugin authors, maintainers, and toolchain builders, the most specific concerns before installation usually are: does this local plugin declare package.json and dsh.bundle.patch? Are DSH, Cordis, and Node version ranges compatible? Are runtime dependencies declared? Will the patch cause duplicate IDs, path inclusion issues, or unevaluated !!js expressions?

dsh-plugin-observatory provides a read-only checkpoint for these issues: performing a static audit before installation, and then observing the bounded Loader lifecycle after activation.

What is this

dsh-plugin-observatory is maintained by CMSKL and is licensed under MIT. The current first stable release is 0.1.0.

It provides two read-only tools:

  • plugin_audit: Checks the package.json and declared dsh.bundle.patch of a local plugin package.
  • plugin_observe: Projects current non-group Loader entries and displays the bounded root-Fiber transitions observed since the plugin was activated.

The core problem it solves is: before the plugin enters the DSH profile, it first provides a deterministic, machine-readable compatibility signal; after activation, it also retains a limited observation entry instead of making the plugin state completely invisible.

Core Features

plugin_audit: Static Compatibility Audit

plugin_audit checks the package.json and declared dsh.bundle.patch of a local package.

It covers the following checks:

  1. Manifest integrity
  2. DSH, Cordis, and Node version ranges
  3. Runtime dependency declaration
  4. Install lifecycle scripts
  5. Patch lines
  6. Duplicate IDs
  7. Path inclusion relations
  8. Unevaluated !!js expressions

The audit result returns a deterministic, machine-readable report. The conclusion can be:

  • compatible
  • needs-review
  • incompatible

plugin_audit only reads package metadata and declared patches. It does not import the target JavaScript nor evaluate patch expressions. Therefore, it is suitable as a signal before installation rather than a full runtime test of the target plugin.

plugin_observe: Bounded Loader Lifecycle Observation

plugin_observe projects current non-group Loader entries and displays the bounded root-Fiber transitions observed since the plugin was activated.

It is process-local and bounded. It is used to view the Loader state and retained transitions in the current process, not as a second authoritative source of the Loader’s current state.

PluginObservatoryService

PluginObservatoryService.audit exposes the same static audit to trusted plugins.

snapshot returns a detached immediate lifecycle report.

assertObservedTransition supports invariant companion.

Read and Parse Boundaries

Package and patch reading is byte-bounded, requiring valid UTF-8, resolving symlinks, and staying under the allowed list root.

The parsed patch graph is also constrained by maximum nesting depth and object/array access limits. Circular YAML aliases will generate an incompatible report instead of entering a recursive exhaustion path.

Reports do not include timestamps and findings are sorted in a deterministic order.

Installation and Enabling

Installing without a specified version resolves only to the stable release:

dsh plugin --profile demo add dsh-plugin-observatory

If you want to pin to the first stable release:

dsh plugin --profile demo add dsh-plugin-observatory@0.1.0

After installation, you can view the combined configuration:

dsh --profile demo --dump-config

To remove:

dsh plugin --profile demo remove dsh-plugin-observatory

In terms of versioning strategy, 0.1.0 is the first stable release and is published as the npm latest dist-tag. Future release candidates are kept in next. Installing without a specified version resolves only to the stable release.

Typical Usage

First, install:

dsh plugin --profile demo add dsh-plugin-observatory@0.1.0

Then, ask the model to audit a local plugin package:

Use plugin_audit on the local package at /path/to/my-plugin. Return the verdict, issues, and inserted bundle entries.

This step will return the audit conclusion, issue items, and inserted bundle entries.

If you want to view the Loader state in the current runtime:

Use plugin_observe and list the non-group Loader entries and their retained transitions.

Check the combined configuration:

dsh --profile demo --dump-config

Remove the plugin:

dsh plugin --profile demo remove dsh-plugin-observatory

Configuration and Limits

The default configuration includes the following items:

  • allowedRoots: Package directories must resolve under the allowed list root.
  • maxManifestBytes: Default 262144, max acceptable value 32 MiB.
  • maxPatchBytes: Default 1048576, max acceptable value 32 MiB.
  • maxPatchDepth: Default 64, max acceptable value 256.
  • maxPatchNodes: Default 10000, max acceptable value 100000.
  • maxObservedEntries: Default 256, historical limit for retained Loader entries.
  • maxTransitionsPerEntry: Default 64, limit for recent transitions retained per Loader entry.

The goal of these limits is to keep the audit and observation process predictable: reading has boundaries, parsing has depth and node limits, and observation entries and transitions also have retention limits.

Environment and Release

The engines requirement in package.json:

node ^22.19.0 || >=24.0.0

The required compatibility matrix runs on DSH 0.1.0-rc.6 with Node 22.19.0 and Node 24.

The DSH and Cordis packages at runtime are peer dependencies. Development uses published versions rather than official Harness repository workspace links.

Installing from a Git checkout requires pnpm build authorization because the source package uses prepare to compile TypeScript. The npm package and attached GitHub Release tarball contain pre-built lib/ files.

Use Cases and Notes

Suitable for the following users:

  • DSH plugin authors
  • DSH plugin maintainers
  • People building DSH toolchains
  • Developers who need to check local plugin declarations before installing to a profile

Note the following:

  1. plugin_audit is a static check; it only reads declared package metadata and patches, does not import target JavaScript, and does not evaluate patch expressions.
  2. plugin_observe is a bounded, process-local observation, not an authoritative source of the Loader’s current state.
  3. Plugins run with the current dsh process permissions; you should check the source code, dependencies, and MIT license before installation.
  4. Reports deterministically sort findings without timestamps, making them suitable as comparable machine-readable output.

Conclusion

dsh-plugin-observatory puts two things in one DSH plugin: providing a static compatibility conclusion before installation and retaining a bounded Loader lifecycle observation after activation. For those who need to determine if a plugin is declared correctly before a profile starts and also want to view current non-group Loader entries, this is a relatively direct entry point.

GitHub Repository: https://github.com/CMSKL/dsh-plugin-observatory