dsh-plugin-inspector 0.1.0

package/lib/inspect.js

@@ -0,0 +1,168 @@
+/**
+ * Orchestration: decode the package once, run the three tiers over the decoded
+ * form, apply the Tier C downgrade, and assemble the report.
+ *
+ * This module is the only place that reads the package and the only place that
+ * decides confidence. Nothing here — and nothing it calls — imports, requires,
+ * spawns, or evaluates anything from the analysed package. The only `Function`
+ * constructed anywhere in this tool is the parse-only compile in
+ * `cordis-yaml.ts`, and its result is discarded without being called.
+ * @module dsh-plugin-inspector/inspect
+ */
+import { EXPRESSION_CLASSES, PatchParseError, parsePatchDocument, } from "./cordis-yaml.js";
+import { isCordisConfigFile, isModelVisibleText, isSourceFile, normalizePackagePath } from "./files.js";
+import { HARNESS_REFERENCE } from "./knowledge.js";
+import { parseManifest } from "./manifest.js";
+import { SEVERITY_RANK, compareFindings, summarize, } from "./model.js";
+import { loadSource } from "./source.js";
+import { runTierA } from "./checks/tier-a.js";
+import { runTierB } from "./checks/tier-b.js";
+import { NON_DEGRADING_CHECKS, runTierC } from "./checks/tier-c.js";
+/** This tool's own version, reported in the JSON document. */
+export const TOOL_VERSION = '0.1.0';
+/** This tool's package name, reported in the JSON document. */
+export const TOOL_NAME = 'dsh-plugin-inspector';
+/**
+ * Locate the one Cordis patch layer that actually mounts.
+ *
+ * `dsh.bundle.patch` is the whole of it. The launcher reads that key and no
+ * other (`packages/boot/app-boot/src/profile.ts`), so a file named
+ * `cordis.patch.yml` sitting anywhere else in the package is a document, an
+ * example, or a test fixture — not a layer. Treating those as mounted is how a
+ * tool comes to report `[critical] disables the core row "approval"` about a
+ * package that mounts nothing at all.
+ * @param source - the decoded package.
+ * @param declaredPatch - the `dsh.bundle.patch` value, already normalised.
+ * @returns the mounted layer's path, and every other cordis YAML file.
+ */
+function patchFiles(source, declaredPatch) {
+    const candidates = [...source.files.keys()].filter(isCordisConfigFile).sort();
+    const mounted = declaredPatch !== null && source.files.has(declaredPatch) ? declaredPatch : null;
+    return { mounted, others: candidates.filter(path => path !== mounted) };
+}
+/**
+ * Tally the `!!js` inventory by what each expression reaches. The inventory is
+ * a fact — a constant or a service read in a config value is what the shipped
+ * bundles are made of — and only the classes with reach become findings.
+ * @param patches - the parsed patch layers.
+ * @returns one count per classification.
+ */
+function tallyExpressions(patches) {
+    const tally = Object.fromEntries(EXPRESSION_CLASSES.map(name => [name, 0]));
+    for (const patch of patches) {
+        for (const site of patch.expressions)
+            tally[site.classification] += 1;
+    }
+    return tally;
+}
+/**
+ * Lower a Tier B confidence when Tier C fired. A Tier B positive stays true —
+ * the tool saw what it saw — but it is no longer a `high`-confidence reading of
+ * the package as a whole.
+ * @param confidence - the check's own confidence.
+ * @param degraded - whether any Tier C check fired.
+ * @returns the effective confidence.
+ */
+function downgrade(confidence, degraded) {
+    if (!degraded || confidence !== 'high')
+        return confidence;
+    return 'moderate';
+}
+/**
+ * Inspect a plugin package.
+ * @param target - a plugin directory, or a `.tgz` / `.tar.gz` npm tarball.
+ * @returns the complete report.
+ * @throws SourceError or ManifestError when the target cannot be analysed at all.
+ */
+export async function inspect(target) {
+    const source = await loadSource(target);
+    const manifest = parseManifest(source.files.get('package.json') ?? '');
+    const declared = manifest.dsh.bundle?.patch;
+    const mountsAsBundle = declared !== undefined;
+    const declaredPatch = declared === undefined ? null : normalizePackagePath(declared);
+    const { mounted, others } = patchFiles(source, declaredPatch);
+    const patches = [];
+    const patchFailures = [];
+    if (mounted !== null) {
+        const text = source.files.get(mounted) ?? '';
+        try {
+            patches.push(parsePatchDocument(mounted, text));
+        }
+        catch (error) {
+            if (!(error instanceof PatchParseError))
+                throw error;
+            patchFailures.push({ file: mounted, error });
+        }
+    }
+    const sourceFiles = [...source.files.keys()].filter(isSourceFile).sort();
+    const modelVisibleFiles = [...source.files.keys()].filter(isModelVisibleText).sort();
+    const input = {
+        source,
+        manifest,
+        mountsAsBundle,
+        patches,
+        patchFailures,
+        unmountedPatchFiles: others,
+        sourceFiles,
+        modelVisibleFiles,
+    };
+    const tierC = runTierC(input);
+    const unreadable = tierC.filter(finding => !NON_DEGRADING_CHECKS.has(finding.checkId));
+    const degraded = unreadable.length > 0;
+    const raw = [
+        ...runTierA(input),
+        ...runTierB(input).map(finding => ({ ...finding, confidence: downgrade(finding.confidence, degraded) })),
+        ...tierC,
+    ];
+    const findings = [...raw].sort(compareFindings);
+    const facts = {
+        packageName: manifest.name,
+        packageVersion: manifest.version,
+        license: manifest.license,
+        mountsAsBundle,
+        bundlePatchPath: declared ?? null,
+        shipsClientBundle: manifest.dsh.client !== undefined && manifest.exportPaths.includes('./client'),
+        profileBundles: manifest.dsh.profile?.bundles ?? [],
+        binNames: manifest.binNames,
+        insertedRows: patches.flatMap(patch => patch.inserts.map(row => ({
+            id: row.id ?? '(unnamed)',
+            ...row.name === null ? {} : { name: row.name },
+        }))),
+        targetedRows: [...new Set(patches.flatMap(patch => patch.overrides.map(override => override.id)))].sort(),
+        jsExpressions: tallyExpressions(patches),
+        unmountedPatchFiles: others,
+        dependencies: Object.keys(manifest.dependencies).sort(),
+        peerDependencies: Object.keys(manifest.peerDependencies).sort(),
+        modelVisibleFiles,
+        filesRead: source.files.size,
+        bytesRead: source.bytesRead,
+        sourceFilesParsed: sourceFiles.length,
+        publishBasis: source.publishBasis,
+        unpublishedFiles: source.unpublishedFiles,
+    };
+    return {
+        schemaVersion: 1,
+        tool: { name: TOOL_NAME, version: TOOL_VERSION, harnessReference: HARNESS_REFERENCE },
+        target: { kind: source.kind, path: source.path },
+        facts,
+        analysis: {
+            integrity: degraded ? 'degraded' : 'complete',
+            negativesReliable: !degraded,
+            degradedBy: [...new Set(unreadable.map(finding => finding.checkId))].sort(),
+            filesSkipped: source.skipped,
+        },
+        summary: summarize(findings),
+        findings,
+    };
+}
+/**
+ * Whether a report should fail a CI gate.
+ * @param report - the report.
+ * @param threshold - the lowest severity that fails, or `none` to never fail.
+ * @returns true when at least one finding is at or above the threshold.
+ */
+export function exceedsThreshold(report, threshold) {
+    if (threshold === 'none')
+        return false;
+    return report.findings.some(finding => SEVERITY_RANK[finding.severity] >= SEVERITY_RANK[threshold]);
+}

package/lib/knowledge.js

@@ -0,0 +1,321 @@
+/**
+ * Ground truth read out of the DeepSeek Harness checkout: the core row
+ * inventory, the capability seam keys, the waterfall event set, and the
+ * capabilities the harness's own sandbox denies untrusted code.
+ *
+ * Every table here cites the harness file it was transcribed from. These are
+ * facts about a specific harness version, not opinions — when the harness
+ * changes, these tables are what needs updating, and keeping them in one
+ * module is what makes that a single reviewable diff.
+ * @module dsh-plugin-inspector/knowledge
+ */
+/**
+ * Harness version these tables were transcribed from — the version string in
+ * the checkout's own `packages/bundle/*/package.json`.
+ */
+export const HARNESS_REFERENCE = '0.1.0-rc.5';
+/**
+ * The three profile bundles the harness ships, mapped to what each one is.
+ * A package that *is* one of these composes the core rows rather than modifying
+ * somebody else's: `@deepseek-ai/dsh-web-app` disabling two dozen rows the base
+ * layer inserted is the definition of a bundle, not an attack on one.
+ * Transcribed from `packages/bundle/{base,headless,web-app}/package.json`.
+ */
+export const HARNESS_BUNDLE_PACKAGES = new Map([
+    ['@deepseek-ai/dsh-base', 'base'],
+    ['@deepseek-ai/dsh-headless', 'headless'],
+    ['@deepseek-ai/dsh-web-app', 'web-app'],
+]);
+/**
+ * Every row the shipped bundles define, mapped from row id to the module that
+ * implements it and the bundles that insert it. Transcribed from
+ * `packages/bundle/{base,headless,web-app}/cordis.patch.yml`.
+ *
+ * A patch row whose `id` is a key here is modifying core behavior rather than
+ * contributing its own. The name half matters because `applyEntryPatches`
+ * treats `name` on a non-insert patch as an assertion guard: on mismatch it
+ * warns and skips the whole patch, so a patch naming the wrong module silently
+ * does nothing at all. The bundle half matters because the three layers are not
+ * one profile: a `ui-*` row exists only where the web bundle is mounted, so a
+ * headless profile never had it to lose.
+ */
+export const CORE_ROWS = new Map([
+    ['agent', { module: '@deepseek-ai/dsh-agent', bundles: ['base'] }],
+    ['agent-default-model', { module: '@deepseek-ai/dsh-agent-default-model', bundles: ['base'] }],
+    ['agent-instructions', { module: '@deepseek-ai/dsh-agent-instructions', bundles: ['base'] }],
+    ['agent-loop', { module: '@deepseek-ai/dsh-agent-loop', bundles: ['base'] }],
+    ['agent-presets', { module: '@deepseek-ai/dsh-agent-presets', bundles: ['web-app'] }],
+    ['api-gateway', { module: '@deepseek-ai/dsh-host-apiproxy', bundles: ['web-app'] }],
+    ['api-remotes', { module: '@deepseek-ai/dsh-api-remotes', bundles: ['web-app'] }],
+    ['approval', { module: '@deepseek-ai/dsh-user-approval', bundles: ['base'] }],
+    ['attachment-local', { module: '@deepseek-ai/dsh-attachment-local', bundles: ['base'] }],
+    ['bash-sandbox', { module: '@deepseek-ai/dsh-bash-sandbox', bundles: ['base'] }],
+    ['client-hmr', { module: '@deepseek-ai/dsh-client-hmr', bundles: ['web-app'] }],
+    ['client-runtime', { module: '@deepseek-ai/dsh-client-runtime', bundles: ['web-app'] }],
+    ['code-runtime', { module: '@deepseek-ai/dsh-code-runtime-worker-thread', bundles: ['headless', 'web-app'] }],
+    ['command-compact', { module: '@deepseek-ai/dsh-command-compact', bundles: ['base'] }],
+    ['command-feedback', { module: '@deepseek-ai/dsh-command-feedback', bundles: ['base'] }],
+    ['command-goal', { module: '@deepseek-ai/dsh-command-goal', bundles: ['base'] }],
+    ['commands', { module: '@deepseek-ai/dsh-commands', bundles: ['base'] }],
+    ['compaction-basic', { module: '@deepseek-ai/dsh-compaction-basic', bundles: ['base'] }],
+    ['connection', { module: '@deepseek-ai/dsh-client-connection', bundles: ['web-app'] }],
+    ['cordis-client-runner', { module: '@deepseek-ai/dsh-cordis-client-runner', bundles: ['web-app'] }],
+    ['cordis-host-runner', { module: '@deepseek-ai/dsh-cordis-host-runner', bundles: ['web-app'] }],
+    ['credentials', { module: '@deepseek-ai/dsh-credentials-local', bundles: ['base'] }],
+    ['directory-picker', { module: '@deepseek-ai/dsh-host-directory-picker-auto', bundles: ['web-app'] }],
+    ['fs-observation-policy', { module: '@deepseek-ai/dsh-fs-observation-policy', bundles: ['base'] }],
+    ['fs-sandbox', { module: '@deepseek-ai/dsh-fs-sandbox', bundles: ['base'] }],
+    ['goal', { module: '@deepseek-ai/dsh-goal', bundles: ['base'] }],
+    ['goal-round-driver', { module: '@deepseek-ai/dsh-goal-round-driver', bundles: ['base'] }],
+    ['headless-runner', { module: '@deepseek-ai/dsh-headless', bundles: ['headless'] }],
+    ['headless-startup', { module: '@deepseek-ai/dsh-headless/startup', bundles: ['headless'] }],
+    ['hmr', { module: '@deepseek-ai/cordis-plugin-hmr', bundles: ['base'] }],
+    ['jobs', { module: '@deepseek-ai/dsh-jobs-local', bundles: ['base'] }],
+    ['llm', { module: '@deepseek-ai/dsh-llm', bundles: ['base'] }],
+    ['llm-deepseek', { module: '@deepseek-ai/dsh-llm-deepseek', bundles: ['base'] }],
+    ['llm-pi-ai', { module: '@deepseek-ai/dsh-llm-pi-ai', bundles: ['base'] }],
+    ['llm-retry', { module: '@deepseek-ai/dsh-llm-retry', bundles: ['base'] }],
+    ['locale', { module: '@deepseek-ai/dsh-client-locale', bundles: ['web-app'] }],
+    ['message-feedback', { module: '@deepseek-ai/dsh-message-feedback', bundles: ['web-app'] }],
+    ['modules', { module: '@deepseek-ai/dsh-client-modules', bundles: ['web-app'] }],
+    ['permission', { module: '@deepseek-ai/dsh-permission-presets', bundles: ['base'] }],
+    ['plan-mode', { module: '@deepseek-ai/dsh-plan-mode', bundles: ['base'] }],
+    ['plugin-inventory', { module: '@deepseek-ai/dsh-host-plugin-inventory', bundles: ['web-app'] }],
+    ['pwsh-sandbox', { module: '@deepseek-ai/dsh-pwsh-sandbox', bundles: ['base'] }],
+    ['repeat-tool-reminder', { module: '@deepseek-ai/dsh-repeat-tool-reminder', bundles: ['base'] }],
+    ['sandbox', { module: '@deepseek-ai/dsh-sandbox-local', bundles: ['base'] }],
+    ['sandbox-policy', { module: '@deepseek-ai/dsh-sandbox-policy', bundles: ['base'] }],
+    ['session', { module: '@deepseek-ai/dsh-session', bundles: ['base'] }],
+    ['session-checkpoint-policy', { module: '@deepseek-ai/dsh-session-checkpoint-policy', bundles: ['base'] }],
+    ['session-log-download', { module: '@deepseek-ai/dsh-session-log-export', bundles: ['web-app'] }],
+    ['session-persistence-jsonl', { module: '@deepseek-ai/dsh-session-persistence-jsonl', bundles: ['base'] }],
+    ['session-projection', { module: '@deepseek-ai/dsh-session-projection', bundles: ['base'] }],
+    ['session-projection-cache', { module: '@deepseek-ai/dsh-session-projection-cache', bundles: ['web-app'] }],
+    ['session-query-sqlite', { module: '@deepseek-ai/dsh-session-query-sqlite', bundles: ['base'] }],
+    ['session-stats', { module: '@deepseek-ai/dsh-session-stats', bundles: ['web-app'] }],
+    ['session-telemetry-otel', { module: '@deepseek-ai/dsh-session-telemetry-otel', bundles: ['base'] }],
+    ['session-title', { module: '@deepseek-ai/dsh-session-title', bundles: ['base'] }],
+    ['session-title-llm', { module: '@deepseek-ai/dsh-session-title-first-prompt-llm', bundles: ['base'] }],
+    ['settings', { module: '@deepseek-ai/dsh-settings-file', bundles: ['base'] }],
+    ['shell-env', { module: '@deepseek-ai/dsh-shell-env', bundles: ['base'] }],
+    ['skill', { module: '@deepseek-ai/dsh-skill', bundles: ['base'] }],
+    ['skill-badge', { module: '@deepseek-ai/dsh-skill-badge', bundles: ['base'] }],
+    ['skill-filesystem', { module: '@deepseek-ai/dsh-skill-filesystem', bundles: ['base'] }],
+    ['spill-local', { module: '@deepseek-ai/dsh-spill-local', bundles: ['base'] }],
+    ['spill-policy', { module: '@deepseek-ai/dsh-spill-policy', bundles: ['base'] }],
+    ['storage', { module: '@deepseek-ai/dsh-storage', bundles: ['web-app'] }],
+    ['storage-domain', { module: '@deepseek-ai/dsh-storage-domain', bundles: ['web-app'] }],
+    ['storage-json', { module: '@deepseek-ai/dsh-storage-json', bundles: ['web-app'] }],
+    ['subagent', { module: '@deepseek-ai/dsh-subagent', bundles: ['base'] }],
+    ['subagent-fork-in-process', { module: '@deepseek-ai/dsh-subagent-fork-in-process', bundles: ['base'] }],
+    ['subagent-spawn-in-process', { module: '@deepseek-ai/dsh-subagent-spawn-in-process', bundles: ['base'] }],
+    ['subprocess', { module: '@deepseek-ai/dsh-subprocess-local', bundles: ['base'] }],
+    ['system-prompt', { module: '@deepseek-ai/dsh-system-prompt', bundles: ['base'] }],
+    ['timeout-policy', { module: '@deepseek-ai/dsh-tool-call-timeout-policy', bundles: ['base'] }],
+    ['timer', { module: '@deepseek-ai/cordis-plugin-timer', bundles: ['base'] }],
+    ['token-meter', { module: '@deepseek-ai/dsh-token-meter', bundles: ['base'] }],
+    ['tool-bash', { module: '@deepseek-ai/dsh-tool-bash', bundles: ['base'] }],
+    ['tool-fs', { module: '@deepseek-ai/dsh-tool-fs', bundles: ['base'] }],
+    ['tool-fs-search', { module: '@deepseek-ai/dsh-tool-fs-search', bundles: ['base'] }],
+    ['tool-goal', { module: '@deepseek-ai/dsh-tool-goal', bundles: ['base'] }],
+    ['tool-jobs', { module: '@deepseek-ai/dsh-tool-jobs', bundles: ['base'] }],
+    ['tool-pwsh', { module: '@deepseek-ai/dsh-tool-pwsh', bundles: ['base'] }],
+    ['tool-ralph', { module: '@deepseek-ai/dsh-tool-ralph', bundles: ['base'] }],
+    ['tool-result-pruner', { module: '@deepseek-ai/dsh-compaction-tool-result-pruner', bundles: ['base'] }],
+    ['tool-skill', { module: '@deepseek-ai/dsh-tool-skill', bundles: ['base'] }],
+    ['tool-str-replace-editor', { module: '@deepseek-ai/dsh-tool-str-replace-editor', bundles: ['base'] }],
+    ['tool-subagent', { module: '@deepseek-ai/dsh-tool-subagent', bundles: ['base'] }],
+    ['tool-subagent-control', { module: '@deepseek-ai/dsh-tool-subagent-control', bundles: ['base'] }],
+    ['tool-subagent-fork', { module: '@deepseek-ai/dsh-tool-subagent', bundles: ['base'] }],
+    ['tool-subagent-list-agents', { module: '@deepseek-ai/dsh-tool-subagent-control/list-agents', bundles: ['base'] }],
+    ['tool-subagent-report', { module: '@deepseek-ai/dsh-tool-subagent-report', bundles: ['base'] }],
+    ['tool-todo', { module: '@deepseek-ai/dsh-tool-todo', bundles: ['base'] }],
+    ['tool-web', { module: '@deepseek-ai/dsh-tool-web', bundles: ['base'] }],
+    ['tool-workflow', { module: '@deepseek-ai/dsh-tool-workflow', bundles: ['base'] }],
+    ['tools', { module: '@deepseek-ai/dsh-tools', bundles: ['base'] }],
+    ['typert', { module: '@deepseek-ai/dsh-typert-registry', bundles: ['base'] }],
+    ['typert-gateway', { module: '@deepseek-ai/dsh-api-gateway', bundles: ['base'] }],
+    ['typert-loader', { module: '@deepseek-ai/dsh-typert-loader', bundles: ['base'] }],
+    ['ui-agent-preset', { module: '@deepseek-ai/dsh-client-ui-agent-preset', bundles: ['web-app'] }],
+    ['ui-commands', { module: '@deepseek-ai/dsh-client-ui-commands', bundles: ['web-app'] }],
+    ['ui-conversation', { module: '@deepseek-ai/dsh-client-ui-conversation', bundles: ['web-app'] }],
+    ['ui-cordis', { module: '@deepseek-ai/dsh-client-ui-cordis', bundles: ['web-app'] }],
+    ['ui-deliverables', { module: '@deepseek-ai/dsh-client-ui-deliverables', bundles: ['web-app'] }],
+    ['ui-goal', { module: '@deepseek-ai/dsh-client-ui-goal', bundles: ['web-app'] }],
+    ['ui-input-trigger', { module: '@deepseek-ai/dsh-client-ui-input-trigger', bundles: ['web-app'] }],
+    ['ui-jobs', { module: '@deepseek-ai/dsh-client-ui-jobs', bundles: ['web-app'] }],
+    ['ui-layout', { module: '@deepseek-ai/dsh-client-ui-layout', bundles: ['web-app'] }],
+    ['ui-message-feedback', { module: '@deepseek-ai/dsh-client-ui-message-feedback', bundles: ['web-app'] }],
+    ['ui-model-selection', { module: '@deepseek-ai/dsh-client-ui-model-selection', bundles: ['web-app'] }],
+    ['ui-permission', { module: '@deepseek-ai/dsh-client-ui-permission-presets', bundles: ['web-app'] }],
+    ['ui-plan', { module: '@deepseek-ai/dsh-client-ui-plan', bundles: ['web-app'] }],
+    ['ui-settings', { module: '@deepseek-ai/dsh-client-ui-settings', bundles: ['web-app'] }],
+    ['ui-settings-general', { module: '@deepseek-ai/dsh-client-ui-settings-general', bundles: ['web-app'] }],
+    ['ui-settings-models', { module: '@deepseek-ai/dsh-client-ui-settings-models', bundles: ['web-app'] }],
+    ['ui-settings-plugin-inventory', { module: '@deepseek-ai/dsh-client-ui-settings-plugin-inventory', bundles: ['web-app'] }],
+    ['ui-settings-plugins', { module: '@deepseek-ai/dsh-client-ui-settings-plugins', bundles: ['web-app'] }],
+    ['ui-sidebar', { module: '@deepseek-ai/dsh-client-ui-sidebar', bundles: ['web-app'] }],
+    ['ui-skill', { module: '@deepseek-ai/dsh-client-ui-skill', bundles: ['web-app'] }],
+    ['ui-subagent', { module: '@deepseek-ai/dsh-client-ui-subagent', bundles: ['web-app'] }],
+    ['ui-theme', { module: '@deepseek-ai/dsh-client-ui-theme', bundles: ['web-app'] }],
+    ['ui-tool', { module: '@deepseek-ai/dsh-client-ui-tool', bundles: ['web-app'] }],
+    ['ui-trajectory', { module: '@deepseek-ai/dsh-client-ui-trajectory', bundles: ['web-app'] }],
+    ['ui-user-questions', { module: '@deepseek-ai/dsh-client-ui-user-questions', bundles: ['web-app'] }],
+    ['ui-workflow-run', { module: '@deepseek-ai/dsh-client-ui-workflow-run', bundles: ['web-app'] }],
+    ['ui-workspace', { module: '@deepseek-ai/dsh-client-ui-workspace', bundles: ['web-app'] }],
+    ['user-questions', { module: '@deepseek-ai/dsh-user-questions', bundles: ['base'] }],
+    ['web', { module: '@deepseek-ai/dsh-web', bundles: ['base'] }],
+    ['web-runtime', { module: '@deepseek-ai/dsh-web-app', bundles: ['web-app'] }],
+    ['web-search-deepseek', { module: '@deepseek-ai/dsh-web-search-deepseek', bundles: ['base'] }],
+    ['web-startup', { module: '@deepseek-ai/dsh-web-app/startup', bundles: ['web-app'] }],
+    ['webserver', { module: '@deepseek-ai/dsh-host-webserver', bundles: ['web-app'] }],
+    ['workflow-worker-thread', { module: '@deepseek-ai/dsh-workflow-worker-thread', bundles: ['base'] }],
+    ['workspace', { module: '@deepseek-ai/dsh-workspace', bundles: ['web-app'] }],
+]);
+/** Row ids the shipped bundles define. */
+export const CORE_ROW_IDS = new Set(CORE_ROWS.keys());
+/**
+ * The core rows whose whole purpose is to constrain what the agent may do.
+ * Disabling or reconfiguring one of these from a third-party patch layer is
+ * the highest-value finding this tool produces, and it is plain YAML.
+ *
+ * Each entry names what stops holding when the row stops running.
+ */
+export const SECURITY_ROW_IDS = new Map([
+    ['approval', 'user approval prompts for tool calls'],
+    ['permission', 'the permission preset that decides which tools may run unattended'],
+    ['sandbox', 'the sandbox service'],
+    ['sandbox-policy', 'the policy that decides what the sandbox permits'],
+    ['bash-sandbox', 'sandboxing of bash tool invocations'],
+    ['pwsh-sandbox', 'sandboxing of PowerShell tool invocations'],
+    ['fs-sandbox', 'filesystem access confinement'],
+    ['fs-observation-policy', 'the read-before-write policy on file edits'],
+    ['subprocess', 'the mediated subprocess service tools are supposed to go through'],
+    ['credentials', 'credential storage'],
+    ['timeout-policy', 'tool execution timeouts'],
+    ['spill-policy', 'the policy bounding oversized tool output'],
+    ['session-persistence-jsonl', 'the session log, which is the audit record'],
+    ['session-telemetry-otel', 'telemetry export'],
+    ['session-checkpoint-policy', 'session checkpointing'],
+    ['tools', 'the tool registry itself'],
+    ['agent-loop', 'the agent loop itself'],
+]);
+/**
+ * Capability seam keys from
+ * `packages/extensions/tool-cordis/src/api-catalog.ts` (`SERVICE_API[].key`).
+ * A plugin calling `ctx.provide(key, …)` or `ctx.set(key, …)` on one of these
+ * replaces a core service for every consumer in its scope.
+ */
+export const SEAM_KEYS = new Set([
+    'agentDefaultModel', 'agentLoop', 'agentPresets', 'agents', 'apiProxy', 'approval',
+    'attachments', 'clientModules', 'codeRuntime', 'commands', 'compaction', 'credentials',
+    'directoryPicker', 'e2b', 'fs', 'goals', 'invariants', 'jobs', 'llm', 'lsp',
+    'messageFeedback', 'permissionPresets', 'planMode', 'sandbox', 'sandboxPolicy',
+    'sessionPersistence', 'sessionProjectionCache', 'sessionProjections', 'sessionQuery',
+    'sessionReferenceResolver', 'sessions', 'sessionTelemetry', 'sessionTitle', 'settings',
+    'shell', 'shellEnv', 'skills', 'spillStore', 'storage', 'storageDomain', 'subagents',
+    'subprocess', 'systemPrompt', 'terminals', 'timer', 'tokenMeter', 'toolResultPruner',
+    'tools', 'typert', 'typertGateway', 'userQuestions', 'web', 'webServer', 'workflowEngine',
+    'workspaceRegistry',
+]);
+/** The subset of {@link SEAM_KEYS} whose replacement removes a constraint. */
+export const SECURITY_SEAM_KEYS = new Set([
+    'approval', 'sandbox', 'sandboxPolicy', 'permissionPresets', 'credentials', 'subprocess',
+    'shell', 'fs', 'tools', 'agentLoop', 'sessionPersistence', 'sessionTelemetry', 'invariants',
+]);
+/**
+ * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
+ * these receives a trailing `next` and MUST call it to delegate; returning
+ * without calling it short-circuits the chain including the built-in behavior.
+ *
+ * Note there is no `fs/read-intent` — the intent family is write and edit only.
+ */
+export const WATERFALL_EVENTS = new Set([
+    'agent/pre-step', 'agent/request', 'agent/request-error', 'approval/request',
+    'fs/edit-intent', 'fs/write-intent', 'llm/stream', 'session-telemetry/record',
+    'system-prompt/assemble', 'tools/code-dispatch-log', 'tools/execute',
+    'tools/post-execute', 'tools/pre-execute',
+]);
+/** Waterfall events whose short-circuit removes a decision the user would otherwise make. */
+export const DECISION_EVENTS = new Set([
+    'approval/request', 'tools/pre-execute', 'tools/execute', 'fs/write-intent', 'fs/edit-intent',
+]);
+/**
+ * Globals the dynamic-package sandbox (`cordis-host-runner/src/sandbox.ts`)
+ * traps and redirects to a `ctx` service, plus `process`, which it leaves
+ * `undefined`. An installed bundle layer is a plain ESM import and gets none of
+ * these restrictions — which is exactly why using one is worth reporting.
+ */
+export const SANDBOX_DENIED_GLOBALS = new Map([
+    ['require', "redirected to ctx services (inject: ['fs'] / ['web'] / ['bash'])"],
+    ['fetch', "redirected to the cordis web service (inject: ['web'])"],
+    ['setTimeout', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['setInterval', "redirected to the cordis timer service (inject: ['timer'])"],
+    ['setImmediate', "redirected to the cordis timer service (inject: ['timer'])"],
+]);
+/**
+ * Node builtins that start or evaluate code off the mediated path. A mounted
+ * layer importing one of these is doing what `ctx.subprocess` and `ctx.sandbox`
+ * exist to mediate, from a position where nothing mediates it.
+ */
+export const UNMEDIATED_PROCESS_MODULES = new Map([
+    ['child_process', 'spawns processes without ctx.subprocess or ctx.sandbox'],
+    ['worker_threads', 'runs code in a thread the harness does not supervise'],
+    ['vm', 'evaluates code outside every harness seam'],
+]);
+/**
+ * Modules and globals that move bytes off the machine. The harness's own
+ * dynamic-package sandbox traps `fetch` and redirects it to the `ctx.web`
+ * service; a mounted layer gets no such redirect.
+ */
+export const NETWORK_MODULES = new Set([
+    'http', 'https', 'http2', 'net', 'tls', 'dgram',
+    'undici', 'axios', 'node-fetch', 'got', 'superagent', 'ws', 'request',
+]);
+/**
+ * Filesystem modules that bypass `ctx.fs`. Reads and writes through these are
+ * invisible to `fs/write-intent`, `fs/edit-intent`, `fs/observed`, and the
+ * `fs-sandbox` row, so no policy sees them.
+ */
+export const UNMEDIATED_FS_MODULES = new Set(['fs', 'fs/promises']);
+/** The npm package that turns a Cordis row into an MCP server connection. */
+export const MCP_CLIENT_PACKAGE = '@deepseek-ai/dsh-mcp-client';
+/** The row id that owns filesystem skill discovery, and whose config selects the roots. */
+export const SKILL_FILESYSTEM_ROW = 'skill-filesystem';
+/** `skill-filesystem` config keys that point discovery at a new directory. */
+export const SKILL_ROOT_CONFIG_KEYS = ['customSkillDirs', 'bundledSkillDir'];
+/**
+ * `package.json` script names npm and pnpm run around installation. A plugin
+ * only needs one of these to run code before the user has read a line of it.
+ */
+export const INSTALL_LIFECYCLE_SCRIPTS = [
+    'preinstall', 'install', 'postinstall', 'prepare', 'prepublish', 'preprepare', 'postprepare',
+];
+/** Entry fields the loader never interpolates: a `!!js` node here is inert data. */
+export const STATIC_ENTRY_FIELDS = [
+    'id', 'name', 'group', 'inject', 'intercept', 'isolate',
+];
+/**
+ * Calls a `!!js` expression may make that reach nothing the harness does not
+ * already hand it.
+ *
+ * `dsh-app-boot` does `ctx.provide('dshHomePath', dshHomePath)` before mounting
+ * any entry (`packages/boot/app-boot/src/index.ts`), and the loader evaluates
+ * every expression under `with (ctx)`, so `dshHomePath(...)` is in scope by
+ * design and documented as such in that package's README. The two `process`
+ * reads are the ones the shipped bundles use.
+ */
+export const HARNESS_INERT_CALLS = new Set([
+    'dshHomePath', 'process.cwd', 'process.uptime',
+]);
+/**
+ * The entry fields that decide which services a row sees, and which of them it
+ * substitutes for its subtree.
+ *
+ * `isolate` is the sharpest: `vendor/loader/src/config/isolate.ts` re-maps a
+ * named service to a fresh symbol realm, so every descendant that injects that
+ * name gets the row's realm instead of the profile's. Setting it on a security
+ * service is a Tier A declaration with the same reach as replacing the service
+ * in code, and it is plain YAML.
+ */
+export const SERVICE_REMAPPING_FIELDS = ['isolate', 'intercept'];

package/lib/manifest.js

@@ -0,0 +1,143 @@
+/**
+ * Reading `package.json` from an untrusted package.
+ *
+ * This is a file boundary with a hostile author on the other side, so nothing
+ * here trusts the parse type. Every field is narrowed before use and a field
+ * of the wrong shape is treated as absent rather than throwing — a plugin that
+ * ships `"scripts": "postinstall"` should still be analysed for everything
+ * else, and "this manifest is malformed" is itself worth reporting.
+ * @module dsh-plugin-inspector/manifest
+ */
+/** Thrown when `package.json` is not JSON at all. */
+export class ManifestError extends Error {
+}
+/**
+ * Whether a value is a plain object, which is the only shape any of the fields
+ * this module reads is allowed to have.
+ * @param value - the parsed value.
+ * @returns true for a non-null, non-array object.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read a `Record<string, string>` field, dropping entries of the wrong type.
+ * @param source - the parsed manifest object.
+ * @param field - the field name.
+ * @param defects - sink for shape complaints.
+ * @returns the field's string-valued entries.
+ */
+function stringMap(source, field, defects) {
+    const value = source[field];
+    if (value === undefined)
+        return {};
+    if (!isRecord(value)) {
+        defects.push(`"${field}" is not an object`);
+        return {};
+    }
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === 'string')
+            result[key] = entry;
+    }
+    return result;
+}
+/**
+ * Read the `dsh` section, narrowing each nested field independently so one
+ * malformed subfield does not discard the rest.
+ * @param value - the raw `dsh` value.
+ * @param defects - sink for shape complaints.
+ * @returns the narrowed section.
+ */
+function readDshSection(value, defects) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value)) {
+        defects.push('"dsh" is not an object');
+        return {};
+    }
+    const section = {};
+    const bundle = value.bundle;
+    if (isRecord(bundle)) {
+        section.bundle = typeof bundle.patch === 'string' ? { patch: bundle.patch } : {};
+    }
+    else if (bundle !== undefined) {
+        defects.push('"dsh.bundle" is not an object');
+    }
+    const profile = value.profile;
+    if (isRecord(profile) && Array.isArray(profile.bundles)) {
+        section.profile = { bundles: profile.bundles.filter((entry) => typeof entry === 'string') };
+    }
+    const client = value.client;
+    if (isRecord(client)) {
+        section.client = client;
+    }
+    else if (client !== undefined) {
+        defects.push('"dsh.client" is not an object');
+    }
+    return section;
+}
+/**
+ * Read the command names `bin` installs. npm accepts both the string form,
+ * which names one command after the package, and the object form.
+ * @param parsed - the parsed manifest object.
+ * @returns the command names, in declaration order.
+ */
+function readBinNames(parsed) {
+    const bin = parsed.bin;
+    if (typeof bin === 'string')
+        return [typeof parsed.name === 'string' ? parsed.name : '<unnamed>'];
+    if (!isRecord(bin))
+        return [];
+    return Object.keys(bin);
+}
+/**
+ * Parse an untrusted `package.json`.
+ * @param text - the file's UTF-8 content.
+ * @returns the narrowed manifest, including any shape defects found.
+ * @throws ManifestError when the text is not a JSON object.
+ */
+export function parseManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ManifestError(`package.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed))
+        throw new ManifestError('package.json must hold a JSON object');
+    const defects = [];
+    const files = parsed.files;
+    const exportsValue = parsed.exports;
+    return {
+        name: typeof parsed.name === 'string' ? parsed.name : '<unnamed>',
+        version: typeof parsed.version === 'string' ? parsed.version : '<unversioned>',
+        license: typeof parsed.license === 'string' ? parsed.license : null,
+        scripts: stringMap(parsed, 'scripts', defects),
+        dependencies: stringMap(parsed, 'dependencies', defects),
+        peerDependencies: stringMap(parsed, 'peerDependencies', defects),
+        optionalDependencies: stringMap(parsed, 'optionalDependencies', defects),
+        devDependencies: stringMap(parsed, 'devDependencies', defects),
+        files: Array.isArray(files) ? files.filter((entry) => typeof entry === 'string') : null,
+        binNames: readBinNames(parsed),
+        exportPaths: isRecord(exportsValue) ? Object.keys(exportsValue) : [],
+        dsh: readDshSection(parsed.dsh, defects),
+        defects,
+    };
+}
+/**
+ * Every package name the manifest admits the package may load at runtime:
+ * its own name, its dependencies, and its peer dependencies. Used to decide
+ * whether an inserted Cordis row names a module the manifest accounts for.
+ * @param manifest - the parsed manifest.
+ * @returns the declared package names.
+ */
+export function declaredPackages(manifest) {
+    return new Set([
+        manifest.name,
+        ...Object.keys(manifest.dependencies),
+        ...Object.keys(manifest.peerDependencies),
+        ...Object.keys(manifest.optionalDependencies),
+    ]);
+}