dsh-xray 0.0.1 → 0.1.0

package/bin/xray.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+// dsh-xray CLI. Static analysis works even when dsh cannot boot;
+// commands needing the composed tree degrade with a clear notice.
+
+const { collectStatic } = require('../lib/collect/static.js');
+const { collectDump } = require('../lib/collect/dump.js');
+const model = require('../lib/model.js');
+
+function parseArgs(argv) {
+  const args = { _: [], profile: 'web', json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--profile' || a === '-p') args.profile = argv[++i];
+    else if (a === '--json') args.json = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function tryDump(profile) {
+  try {
+    return { dump: collectDump(profile), error: null };
+  } catch (err) {
+    return { dump: null, error: `dump-config unavailable (${err.message.split('\n')[0]}); static-only mode` };
+  }
+}
+
+const pad = (s, n) => String(s ?? '').padEnd(n);
+
+function cmdAttribute(args) {
+  const data = collectStatic(args.profile);
+  const result = model.attribute(data);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  console.log(`# ${result.rows.length} rows in profile "${args.profile}"\n`);
+  for (const row of result.rows) {
+    const flags = row.disabled ? ' [disabled]' : '';
+    const over = row.overrides.length
+      ? `  ← patched by ${row.overrides.map((o) => o.layer).join(', ')}`
+      : '';
+    console.log(`${pad(row.id, 28)} ${pad(row.origin?.layer, 32)}${over}${flags}`);
+  }
+  if (result.orphans.length) {
+    console.log(`\n! ${result.orphans.length} orphan override(s) targeting nonexistent rows (silently skipped by dsh):`);
+    for (const o of result.orphans) console.log(`  ${o.id}  in ${o.file}`);
+  }
+  for (const w of result.warnings) console.log(`! ${w}`);
+}
+
+function cmdConflicts(args) {
+  const data = collectStatic(args.profile);
+  const result = model.conflicts(data);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  if (!result.length) return console.log('no contested rows: every field has a single writer');
+  for (const c of result) {
+    console.log(`${c.id}`);
+    for (const f of c.fields) {
+      console.log(`  .${f.field}: ${f.writers.map((w) => w.layer).join(' → ')}  (winner: ${f.winner})`);
+    }
+  }
+}
+
+function cmdDiff(args) {
+  const data = collectStatic(args.profile);
+  const { dump, error } = tryDump(args.profile);
+  if (error) { console.error(`! ${error}`); process.exitCode = 1; return; }
+  const result = model.diff(data, dump);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  const section = (title, items, fmt) => {
+    if (!items.length) return;
+    console.log(`\n${title} (${items.length})`);
+    for (const it of items) console.log(`  ${fmt(it)}`);
+  };
+  section('declared but not in boot tree', result.missingFromActual, (r) => `${r.id} (${r.name})`);
+  section('in boot tree but undeclared', result.missingFromDeclared, (r) => `${r.id} (${r.name}) — dump says: ${r.provenance}`);
+  section('disabled-state mismatch', result.disabledMismatch, (r) => `${r.id}: declared=${r.declared} actual=${r.actual}`);
+  section('orphan overrides (silently skipped)', result.orphanOverrides, (r) => `${r.id} in ${r.file}`);
+  section('installed but inactive packages', result.inactivePackages, (r) => `${r.name}@${r.version}`);
+  const total = result.missingFromActual.length + result.missingFromDeclared.length
+    + result.disabledMismatch.length + result.orphanOverrides.length + result.inactivePackages.length;
+  if (total === 0) console.log('declared and actual trees agree');
+  else process.exitCode = 1;
+}
+
+function cmdSnapshot(args) {
+  const data = collectStatic(args.profile);
+  const { dump } = tryDump(args.profile);
+  console.log(JSON.stringify(model.snapshot(data, dump), null, 2));
+}
+
+const commands = {
+  attribute: cmdAttribute,
+  conflicts: cmdConflicts,
+  diff: cmdDiff,
+  snapshot: cmdSnapshot,
+};
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = commands[args._[0]];
+if (!cmd) {
+  console.log(`dsh-xray — X-ray for your DeepSeek Harness
+
+Usage: dsh-xray <command> [--profile web] [--json]
+
+Commands:
+  attribute   which layer introduced each row, and who patched it since
+  conflicts   rows whose fields have multiple writers, and who wins
+  diff        declared (static layers) vs actual (dump-config) tree
+  snapshot    content-addressed lockfile of the effective composition`);
+  process.exit(args._[0] ? 2 : 0);
+}
+try {
+  cmd(args);
+} catch (err) {
+  console.error(`error: ${err.message}`);
+  process.exit(2);
+}

package/cordis.patch.yml

@@ -1,5 +1,4 @@
-# dsh-xray bundle patch: mounts the xray plugin into the composed tree.
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
 - insert:
-    id: dsh-xray
-    name: dsh-xray
-    config: {}
+    - id: dsh-xray
+      name: dsh-xray

package/lib/collect/dump.js

@@ -0,0 +1,51 @@
+'use strict';
+// Dump collector: runs `dsh --profile <p> --dump-config` and parses the
+// composed tree, preserving dsh's own provenance comments (`# == <layer>`),
+// which annotate the row group that follows them.
+
+const { execFileSync } = require('node:child_process');
+const YAML = require('yaml');
+
+const jsTag = { tag: 'tag:yaml.org,2002:js', resolve: (str) => ({ $js: str }) };
+
+function runDump(profileName, { dshBin = 'dsh' } = {}) {
+  return execFileSync(dshBin, ['--profile', profileName, '--dump-config'], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+/**
+ * @returns {{rows: [{id, name, config, disabled, provenance: string|null}], raw}}
+ * provenance is dsh's own `# ==` annotation, e.g.
+ * "@deepseek-ai/dsh-base, patched by @deepseek-ai/dsh-web-app".
+ */
+function parseDump(text) {
+  const docs = YAML.parse(text, { customTags: [jsTag] });
+  if (!Array.isArray(docs)) throw new Error('dump-config did not yield a YAML array');
+
+  // Map each top-level row start line -> most recent `# ==` header.
+  const headerByLine = [];
+  let current = null;
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^# == (.+)$/);
+    if (m) current = m[1].trim();
+    if (/^- /.test(lines[i])) headerByLine.push(current);
+  }
+
+  const rows = docs.map((row, i) => ({
+    id: row.id ?? null,
+    name: row.name ?? null,
+    config: row.config,
+    disabled: row.disabled === true,
+    provenance: headerByLine[i] ?? null,
+  }));
+  return { rows, raw: text };
+}
+
+function collectDump(profileName, opts) {
+  return parseDump(runDump(profileName, opts));
+}
+
+module.exports = { collectDump, parseDump };

package/lib/collect/static.js

@@ -0,0 +1,118 @@
+'use strict';
+// Static collector: reads the layer stack from DSH_HOME without running dsh.
+// Layers, in application order: each profile bundle's patch, the profile's
+// cordis.patch.yml, the home-level cordis.patch.yml.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const YAML = require('yaml');
+
+// `!!js` expressions are loader-evaluated; statically we keep them as opaque
+// markers so comparison logic can treat them as "dynamic, not comparable".
+const jsTag = {
+  tag: 'tag:yaml.org,2002:js',
+  resolve: (str) => ({ $js: str }),
+};
+
+function parseYaml(text, file) {
+  try {
+    return { value: YAML.parse(text, { customTags: [jsTag] }), error: null };
+  } catch (err) {
+    return { value: null, error: `${file}: ${err.message}` };
+  }
+}
+
+function dshHome() {
+  return process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve a bundle package dir: profile node_modules flat closure. */
+function resolveBundleDir(home, profileDir, name) {
+  const candidates = [
+    path.join(profileDir, 'node_modules', name),
+    path.join(home, 'profiles', 'node_modules', name),
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+  }
+  return null;
+}
+
+/**
+ * Collect the static layer stack for a profile.
+ * @returns {{home, profile, layers, packages, warnings}}
+ *   layers: [{kind: 'bundle'|'profile-patch'|'home-patch', name, file, entries, hash}]
+ *   packages: profile dependencies with a `dsh` field (mounted or not)
+ */
+function collectStatic(profileName) {
+  const home = dshHome();
+  const profileDir = path.join(home, 'profiles', profileName);
+  const warnings = [];
+  const layers = [];
+
+  const manifestFile = path.join(profileDir, 'package.json');
+  const manifest = readJson(manifestFile);
+  if (!manifest) {
+    throw new Error(`profile manifest not found: ${manifestFile}`);
+  }
+  const bundles = manifest.dsh?.profile?.bundles ?? [];
+
+  for (const name of bundles) {
+    const dir = resolveBundleDir(home, profileDir, name);
+    if (!dir) {
+      warnings.push(`bundle not resolvable: ${name}`);
+      continue;
+    }
+    const pkg = readJson(path.join(dir, 'package.json'));
+    const rel = pkg?.dsh?.bundle?.patch;
+    if (!rel) {
+      warnings.push(`bundle ${name} has no dsh.bundle.patch`);
+      continue;
+    }
+    const file = path.join(dir, rel);
+    const text = fs.readFileSync(file, 'utf8');
+    const { value, error } = parseYaml(text, file);
+    if (error) warnings.push(error);
+    layers.push({
+      kind: 'bundle',
+      name,
+      version: pkg.version ?? null,
+      file,
+      entries: Array.isArray(value) ? value : [],
+      text,
+    });
+  }
+
+  for (const [kind, file] of [
+    ['profile-patch', path.join(profileDir, 'cordis.patch.yml')],
+    ['home-patch', path.join(home, 'cordis.patch.yml')],
+  ]) {
+    if (!fs.existsSync(file)) continue;
+    const text = fs.readFileSync(file, 'utf8');
+    const { value, error } = parseYaml(text, file);
+    if (error) warnings.push(error);
+    layers.push({ kind, name: kind, version: null, file, entries: Array.isArray(value) ? value : [], text });
+  }
+
+  // Out-of-tree plugins: profile dependencies carrying a `dsh` field.
+  const packages = [];
+  for (const dep of Object.keys(manifest.dependencies ?? {})) {
+    const dir = resolveBundleDir(home, profileDir, dep);
+    const pkg = dir ? readJson(path.join(dir, 'package.json')) : null;
+    if (pkg?.dsh) packages.push({ name: dep, version: pkg.version ?? null, dir, dsh: pkg.dsh });
+    if (!dir) warnings.push(`dependency not installed: ${dep}`);
+  }
+
+  return { home, profile: profileName, manifestFile, bundles, layers, packages, warnings };
+}
+
+module.exports = { collectStatic, dshHome };

package/lib/model.js

@@ -0,0 +1,160 @@
+'use strict';
+// Model layer: pure functions over collector output. No IO here.
+
+const crypto = require('node:crypto');
+
+/**
+ * Replay patch layers over an empty row list, recording per-row provenance.
+ *
+ * Patch entry shapes (verified against dsh-base/web-app bundle patches and
+ * dsh's loader semantics: id-targeted whole-config replacement, insert lists):
+ *   - { insert: [row, ...] }          append new rows
+ *   - { id, config?, disabled?, ... } override an existing row by id
+ *
+ * @param layers output of collectStatic().layers
+ * @returns {{rows: Map<id, row>, orphans: [], provenance: Map<id, [event]>}}
+ *   event: {layer, kind, action: 'insert'|'override', file, fields}
+ */
+function replayLayers(layers) {
+  const rows = new Map();
+  const provenance = new Map();
+  const orphans = []; // overrides targeting an id that does not exist (silently skipped by dsh)
+
+  const record = (id, event) => {
+    if (!provenance.has(id)) provenance.set(id, []);
+    provenance.get(id).push(event);
+  };
+
+  for (const layer of layers) {
+    const meta = { layer: layer.name, kind: layer.kind, file: layer.file };
+    for (const entry of layer.entries) {
+      if (entry && Array.isArray(entry.insert)) {
+        for (const row of entry.insert) {
+          const id = row.id ?? row.name;
+          rows.set(id, { ...row, id });
+          record(id, { ...meta, action: 'insert', fields: Object.keys(row) });
+        }
+      } else if (entry && entry.id !== undefined) {
+        const { id, ...rest } = entry;
+        if (!rows.has(id)) {
+          orphans.push({ ...meta, id, fields: Object.keys(rest) });
+          continue;
+        }
+        // Loader semantics: whole-config replacement, not deep merge.
+        rows.set(id, { ...rows.get(id), ...rest });
+        record(id, { ...meta, action: 'override', fields: Object.keys(rest) });
+      }
+    }
+  }
+  return { rows, provenance, orphans };
+}
+
+/** F1: per-row layer attribution table. */
+function attribute(staticData) {
+  const { rows, provenance, orphans } = replayLayers(staticData.layers);
+  const table = [...rows.values()].map((row) => {
+    const events = provenance.get(row.id) ?? [];
+    const origin = events.find((e) => e.action === 'insert') ?? null;
+    return {
+      id: row.id,
+      name: row.name ?? null,
+      disabled: row.disabled === true,
+      origin: origin ? { layer: origin.layer, kind: origin.kind } : null,
+      overrides: events.filter((e) => e.action === 'override')
+        .map((e) => ({ layer: e.layer, kind: e.kind, fields: e.fields })),
+    };
+  });
+  return { rows: table, orphans, warnings: staticData.warnings };
+}
+
+/** F3: rows written by more than one layer, with the winning writer last. */
+function conflicts(staticData) {
+  const { provenance } = replayLayers(staticData.layers);
+  const out = [];
+  for (const [id, events] of provenance) {
+    // A conflict needs two writers touching the same field set beyond the insert.
+    const writers = events.filter((e) => e.action === 'override');
+    if (writers.length === 0) continue;
+    const byField = new Map();
+    for (const e of events) {
+      for (const f of e.fields) {
+        if (f === 'id') continue;
+        if (!byField.has(f)) byField.set(f, []);
+        byField.get(f).push({ layer: e.layer, kind: e.kind, action: e.action });
+      }
+    }
+    const contested = [...byField.entries()].filter(([, w]) => w.length > 1);
+    if (contested.length === 0) continue;
+    out.push({
+      id,
+      fields: contested.map(([field, writers]) => ({
+        field,
+        writers,
+        winner: writers[writers.length - 1].layer,
+      })),
+    });
+  }
+  return out;
+}
+
+/** F2: declared (static replay) vs actual (dump-config) diff. */
+function diff(staticData, dumpData) {
+  const declared = replayLayers(staticData.layers);
+  const actualById = new Map(dumpData.rows.map((r) => [r.id, r]));
+
+  const missingFromActual = []; // declared but dsh dropped it
+  const missingFromDeclared = []; // in the boot tree but no static layer declares it
+  const disabledMismatch = [];
+
+  for (const [id, row] of declared.rows) {
+    const actual = actualById.get(id);
+    if (!actual) {
+      missingFromActual.push({ id, name: row.name ?? null });
+      continue;
+    }
+    if ((row.disabled === true) !== actual.disabled) {
+      disabledMismatch.push({ id, declared: row.disabled === true, actual: actual.disabled });
+    }
+  }
+  for (const row of dumpData.rows) {
+    if (!declared.rows.has(row.id)) {
+      missingFromDeclared.push({ id: row.id, name: row.name, provenance: row.provenance });
+    }
+  }
+
+  // Installed out-of-tree plugins whose bundle patch rows never made it in.
+  const inactivePackages = staticData.packages
+    .filter((p) => p.dsh?.bundle)
+    .filter((p) => ![...declared.rows.values()].some((r) => r.name === p.name)
+      && !dumpData.rows.some((r) => r.name === p.name))
+    .map((p) => ({ name: p.name, version: p.version }));
+
+  return {
+    missingFromActual,
+    missingFromDeclared,
+    disabledMismatch,
+    orphanOverrides: declared.orphans,
+    inactivePackages,
+  };
+}
+
+/** F9: content-addressed snapshot of the effective composition. */
+function snapshot(staticData, dumpData) {
+  const sha = (s) => crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+  return {
+    schema: 'dsh-xray/snapshot@1',
+    createdAt: new Date().toISOString(),
+    profile: staticData.profile,
+    bundles: staticData.layers
+      .filter((l) => l.kind === 'bundle')
+      .map((l) => ({ name: l.name, version: l.version, patchHash: sha(l.text) })),
+    patches: staticData.layers
+      .filter((l) => l.kind !== 'bundle')
+      .map((l) => ({ kind: l.kind, file: l.file, hash: sha(l.text) })),
+    packages: staticData.packages.map((p) => ({ name: p.name, version: p.version })),
+    composedHash: dumpData ? sha(dumpData.raw) : null,
+    rowCount: dumpData ? dumpData.rows.length : null,
+  };
+}
+
+module.exports = { replayLayers, attribute, conflicts, diff, snapshot };

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "dsh-xray",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "license": "MIT",
   "main": "lib/index.js",
+  "bin": {
+    "dsh-xray": "bin/xray.js"
+  },
   "exports": {
     ".": "./lib/index.js",
     "./package.json": "./package.json",
@@ -11,10 +14,17 @@
   },
   "files": [
     "lib",
+    "bin",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md"
   ],
+  "dependencies": {
+    "yaml": "^2.6.0"
+  },
+  "scripts": {
+    "test": "node --test tests/model.spec.js"
+  },
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",