@shidesheng0218/dsh-plugin-lint 0.0.0-stage → 0.4.0

package/src/probe/probe.js

@@ -0,0 +1,278 @@
+import { readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadPackage } from '../core/load.js';
+import { lineOfIndex } from '../core/mask.js';
+import { sha256 } from '../shared/hash.js';
+import { ToolError } from '../shared/errors.js';
+import { downloadArtifact } from './artifact-resolver.js';
+import { classify } from './classify.js';
+import { readInstalledArtifact } from './installed-artifact.js';
+import { WEB_READY, resolveDsh, startStub } from './dsh-adapter.js';
+
+export async function capture(fn) {
+  try {
+    const result = await fn();
+    const out = typeof result === 'string'
+      ? result
+      : result?.out !== undefined
+        ? String(result.out)
+        : String(result?.stdout || '') + String(result?.stderr || '');
+    return { out, failed: false };
+  } catch (error) {
+    return { out: String(error.stdout || '') + String(error.stderr || ''), failed: true, error };
+  }
+}
+
+export const redact = (value) => String(value).replace(/token=[^\s&"']+/gi, 'token=<redacted>');
+
+export function parseInactive(text) {
+  const out = [];
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => /did not activate/.test(line));
+  if (start < 0) return out;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const match = /^(\S.*?)\s+\((\S+)\):\s*(.*)$/.exec(lines[index]);
+    if (match) {
+      out.push({ name: match[1], id: match[2], reason: match[3].trim() });
+      continue;
+    }
+    if (out.length > 0 && /^\s+at /.test(lines[index])) {
+      const last = out[out.length - 1];
+      last.detail = (last.detail ? last.detail + ' ' : '') + lines[index].trim();
+      continue;
+    }
+    if (out.length > 0) break;
+  }
+  return out;
+}
+
+export function awaitedServices(entries) {
+  const services = [];
+  for (const entry of entries) {
+    // The host prints "waiting for service: x" for one and "waiting for
+    // services: x, y" for several; both must reach the cell.
+    const match = /waiting for services?:\s*([^)]+)/.exec(entry.reason || '');
+    if (!match) continue;
+    for (const name of match[1].split(',')) {
+      const service = name.trim();
+      if (service) services.push(service);
+    }
+  }
+  return [...new Set(services)];
+}
+
+export function rejectionOf(installText) {
+  const match = /installation rejected:\s*([^\n]+)/.exec(installText);
+  return match ? match[1].trim().slice(0, 400) : undefined;
+}
+
+export function noteOf(text) {
+  return redact(text).split('\n').map((line) => line.trim())
+    .filter((line) => line && !/MISSING_CREDENTIAL/.test(line) && !/^at /.test(line))
+    .slice(0, 3).join(' | ').slice(0, 300);
+}
+
+export const payloadOf = (seen) => seen.filter((body) => Array.isArray(body.tools)).pop();
+
+async function prepareDsh(dsh, environment) {
+  if (dsh.kind === 'desktop') {
+    if (environment.isolation === 'docker') {
+      throw new ToolError('ISOLATION_UNSUPPORTED', 'Desktop DSH is not supported by the Docker backend.');
+    }
+    return dsh;
+  }
+  if (!dsh.cli || (environment.isolation === 'docker' && !dsh.containerCli)) {
+    return resolveDsh(dsh.version, environment.dshDir, { environment });
+  }
+  return dsh;
+}
+
+function scanCapabilities(dir) {
+  const pkg = loadPackage(dir);
+  const observed = new Map();
+  const patterns = [
+    [/\bctx\.slots\.(register|inject)\s*\(/, 'ui-injection'],
+    [/\bctx\.llm\.(stream|complete|chat)\s*\(/, 'llm'],
+    [/\bctx\.session\.append\s*\(/, 'session-write'],
+    [/\bctx\.connection\b/, 'connection'],
+    [/\bfetch\s*\(/, 'network'],
+    [/\bhttps?\.request\s*\(/, 'network'],
+    [/\bnet\.connect\s*\(/, 'network'],
+    [/\bchild_process\b/, 'shell'],
+    [/\bexec(?:File)?\s*\(/, 'shell'],
+    [/\bspawn\s*\(/, 'shell'],
+    [/\bfs\.(write|append|createWrite)/, 'fs-write'],
+    [/\bfs\.(read|createRead)/, 'fs-read'],
+    [/\bprocess\.env\b/, 'env'],
+    [/\bnavigator\.sendBeacon\s*\(/, 'telemetry'],
+  ];
+  for (const file of pkg.jsFiles) {
+    for (const [pattern, capability] of patterns) {
+      const match = pattern.exec(file.structural);
+      if (!match) continue;
+      if (!observed.has(capability)) observed.set(capability, []);
+      observed.get(capability).push({ file: file.path, line: lineOfIndex(file.lineStarts, match.index) });
+    }
+  }
+  return { observed: [...observed.entries()].map(([capability, sites]) => ({ capability, sites: sites.length, first: sites[0] })) };
+}
+
+function toolDiff(before, after) {
+  const names = (payload) => payload.tools.map((tool) => tool.name);
+  const baseline = new Set(names(before));
+  const current = new Set(names(after));
+  return {
+    tools: { baseline: baseline.size, total: current.size, added: [...current].filter((name) => !baseline.has(name)), removed: [...baseline].filter((name) => !current.has(name)) },
+    systemPrompt: { baselineChars: JSON.stringify(before.system ?? '').length, chars: JSON.stringify(after.system ?? '').length },
+    packagesAdded: [...new Set((after.dsh_plugin_packages?.packages ?? []).map((pkg) => pkg.name + '@' + pkg.version))]
+      .filter((name) => !new Set((before.dsh_plugin_packages?.packages ?? []).map((pkg) => pkg.name + '@' + pkg.version)).has(name)),
+  };
+}
+
+function publicError(error) {
+  const code = typeof error?.code === 'string' && error.code !== '' ? error.code : 'PROBE_FAILED';
+  // Keep a short, redacted tail of the child output: a generic message makes
+  // an infrastructure failure impossible to diagnose from the cell alone.
+  const out = String(error?.stderr || error?.stdout || '').trim();
+  const message = error instanceof ToolError
+    ? error.message
+    : out
+      ? 'The probe could not complete: ' + redact(out).slice(-400)
+      : 'The probe could not complete because of an internal or host failure.';
+  return { code, message };
+}
+
+export async function probePackage({
+  artifact: inputArtifact,
+  dsh: inputDsh,
+  environment,
+  stub: inputStub,
+  tools = false,
+  keep = false,
+  composition = 'headless',
+  audit = false,
+}) {
+  const started = Date.now();
+  const observation = { outcome: 'completed', install: 'ok', entries: [], durationMs: 0 };
+  let stub = inputStub;
+  let ownsStub = false;
+  try {
+    const dsh = await prepareDsh(inputDsh, environment);
+    const artifact = inputArtifact.local || inputArtifact.tarballPath ? inputArtifact : await downloadArtifact(inputArtifact);
+    const materialized = await environment.materialize(artifact);
+    if (tools && composition !== 'web' && !stub) {
+      stub = environment.startStub ? await environment.startStub() : await startStub();
+      ownsStub = true;
+    }
+    const profile = composition === 'web' ? 'web' : 'headless';
+    const bootEnv = tools && stub ? { PROBE_API_KEY: 'probe' } : {};
+    const patchPath = environment.isolation === 'docker' ? '/profile/probe-patch.yml' : join(environment.profileDir, 'probe-patch.yml');
+    if (tools && stub) {
+      const baseURL = stub.baseURL || `http://127.0.0.1:${stub.port}`;
+      writeFileSync(join(environment.profileDir, 'probe-patch.yml'), [
+        '- id: llm-deepseek',
+        '  name: "@deepseek-ai/dsh-llm-deepseek-api-key"',
+        '  config:',
+        `    baseURL: ${baseURL}`,
+        '    apiKeyEnv: PROBE_API_KEY',
+        '',
+      ].join('\n'));
+    }
+    const bootArgs = composition === 'web'
+      ? ['--profile', 'web', '--port', '0', '--no-open']
+      : ['--profile', 'headless', ...(tools ? ['--patch', patchPath] : []), 'probe'];
+    const bootInput = {
+      dsh,
+      args: bootArgs,
+      env: bootEnv,
+      composition,
+      readyRe: composition === 'web' ? WEB_READY : undefined,
+      network: composition !== 'web' && stub?.network ? stub.network : undefined,
+    };
+    const baseline = await capture(() => environment.boot(bootInput));
+    let booted;
+    if (!readdirSync(environment.profileDir).includes('profiles')) {
+      throw new ToolError('TEMPLATE_FAILED', 'DSH did not create a temporary profile.');
+    }
+    if (stub?.sync) await stub.sync();
+    const before = tools && composition !== 'web' ? payloadOf(stub.seen.splice(0)) : undefined;
+
+    const installed = await capture(() => environment.install({ dsh, target: materialized, profile, env: bootEnv }));
+    const rejection = rejectionOf(installed.out);
+    const profileDir = join(environment.profileDir, 'profiles', profile);
+    let installedArtifact;
+    try {
+      installedArtifact = readInstalledArtifact(profileDir, artifact.name);
+    } catch (error) {
+      if (!rejection) throw error;
+    }
+    if (installedArtifact && installedArtifact.version !== artifact.resolvedVersion) {
+      throw new ToolError('VERSION_MISMATCH', 'The installed artifact version differs from the pinned artifact.');
+    }
+    observation.loadedVersion = installedArtifact?.version;
+    if (installed.failed) observation.install = 'ok-with-warnings';
+    if (rejection) {
+      observation.result = {
+        status: 'rejected-by-host',
+        composition,
+        rejection,
+        entries: [],
+        awaitedServices: [],
+        clientHalf: 'not-covered',
+      };
+    } else {
+      booted = await capture(() => environment.boot(bootInput));
+      if (stub?.sync) await stub.sync();
+      const entries = parseInactive(booted.out);
+      const after = tools && composition !== 'web' ? payloadOf(stub.seen.splice(0)) : undefined;
+      const ready = composition === 'web' ? WEB_READY.test(booted.out) : undefined;
+      const status = classify(booted.out, entries, composition === 'web' ? ready : (tools ? Boolean(after) : undefined));
+      const diff = before && after ? toolDiff(before, after) : undefined;
+      const auditResult = audit ? scanCapabilities(artifact.local ? materialized.hostPath : (installedArtifact?.path || materialized.hostPath)) : undefined;
+      observation.result = {
+        status,
+        composition,
+        ready,
+        awaitedServices: awaitedServices(entries),
+        entries,
+        tools: diff?.tools || (tools && composition !== 'web' ? { error: 'the harness sent no tool-bearing request' } : undefined),
+        systemPrompt: diff?.systemPrompt,
+        packagesAdded: diff?.packagesAdded,
+        audit: auditResult,
+        clientHalf: 'not-covered',
+      };
+    }
+    observation.entries = observation.result.entries;
+    observation.audit = observation.result.audit;
+    observation.tools = observation.result.tools;
+    observation.systemPrompt = observation.result.systemPrompt;
+    observation.packagesAdded = observation.result.packagesAdded;
+    observation.status = observation.result.status;
+    observation.composition = composition;
+    observation.note = noteOf(booted?.out || baseline.out);
+    observation.outputSha256 = sha256(installed.out + '\n' + (booted?.out || baseline.out));
+    observation.reproduce = {
+      command: `node scripts/probe-boot.mjs ${artifact.installTarget}${tools ? ' --tools' : ''}${composition === 'web' ? ' --mode web' : ''} --dsh ${dsh.version}${environment.isolation === 'host-unsafe' ? ' --unsafe-host' : ''}`,
+    };
+    if (installed.failed) observation.installOutput = redact(installed.out).slice(-700);
+  } catch (error) {
+    observation.outcome = 'error';
+    observation.error = publicError(error);
+    observation.result = undefined;
+  } finally {
+    observation.durationMs = Date.now() - started;
+    try {
+      await environment.destroy();
+    } catch (error) {
+      // Cleanup failure is an infrastructure note, not a plugin verdict. A
+      // completed observation keeps its result; an earlier error keeps its code.
+      observation.cleanup = {
+        code: 'ISOLATION_CLEANUP_FAILED',
+        message: 'The probe environment could not be cleaned up.',
+      };
+    }
+    if (ownsStub && stub?.server) stub.server.close();
+    void keep;
+  }
+  return observation;
+}

package/src/report.js

@@ -0,0 +1 @@
+export * from './core/report.js';

package/src/rules.js

@@ -0,0 +1 @@
+export * from './core/rules.js';

package/src/security.js

@@ -0,0 +1 @@
+export * from './experimental/security.js';

package/src/shared/errors.js

@@ -0,0 +1,7 @@
+export class ToolError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message, { cause });
+    this.name = 'ToolError';
+    this.code = code;
+  }
+}

package/src/shared/hash.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { isPlainObject } from './validate.js';
+
+export function stableStringify(value) {
+  return JSON.stringify(normalizeJson(value, new Set()));
+}
+
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function normalizeJson(value, ancestors) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('stableStringify only accepts JSON data');
+    return value;
+  }
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    throw new TypeError('stableStringify only accepts JSON data');
+  }
+  if (ancestors.has(value)) throw new TypeError('stableStringify cannot encode a JSON cycle');
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) return value.map((entry) => normalizeJson(entry, ancestors));
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) normalized[key] = normalizeJson(value[key], ancestors);
+    return normalized;
+  } finally {
+    ancestors.delete(value);
+  }
+}

package/src/shared/status.js

@@ -0,0 +1,12 @@
+export const STATUS = Object.freeze({
+  ACTIVE: 'active',
+  AWAITING_SERVICE: 'awaiting-service',
+  INACTIVE_ERROR: 'inactive-error',
+});
+
+export const TRUST = Object.freeze({
+  SELF_REPORTED: 'self-reported',
+  VERIFIED: 'verified',
+  DISPUTED: 'disputed',
+  LEGACY_UNPINNED: 'legacy-unpinned',
+});

package/src/shared/validate.js

@@ -0,0 +1,14 @@
+export function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function requireFields(value, fields, path) {
+  if (!isPlainObject(value)) return [`${path} must be an object`];
+  const errors = [];
+  for (const field of fields) {
+    if (!Object.hasOwn(value, field) || value[field] === undefined) errors.push(`${path}.${field} is required`);
+  }
+  return errors;
+}

package/src/shared/version.js

@@ -0,0 +1,4 @@
+export const CELL_SCHEMA_VERSION = 2;
+export const EXPERIMENTAL_SCHEMA_VERSION = 2;
+export const PANEL_PAYLOAD_SCHEMA_VERSION = 2;
+export const PROBE_VERSION = '0.4.0';

package/src/upgrade/compatibility.js

@@ -0,0 +1,14 @@
+const INCOMPATIBLE = /incompatible|unsupported|broken|failed|rejected|inactive|boot/i;
+
+export function classifyCompatibilityDeclaration(value) {
+  if (value === true || value === 'compatible') return 'compatible';
+  if (value === false || value === 'incompatible') return 'incompatible';
+  if (typeof value === 'string') return INCOMPATIBLE.test(value) ? 'incompatible' : 'unknown';
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (value.compatible === true) return 'compatible';
+    if (value.compatible === false) return 'incompatible';
+    const status = value.status ?? value.verdict;
+    if (typeof status === 'string' && INCOMPATIBLE.test(status)) return 'incompatible';
+  }
+  return 'unknown';
+}

package/src/upgrade/planner.js

@@ -0,0 +1,119 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { readCells } from '../matrix/cells.js';
+import { recommendationEligible, selectCells } from '../matrix/cell.js';
+import { readProfile } from './profile.js';
+
+function readMatrix(matrixDir, targetDsh) {
+  if (!existsSync(matrixDir)) throw new ToolError('MATRIX_INPUT_INVALID', 'matrix directory not found: ' + matrixDir);
+  const cellsDir = existsSync(join(matrixDir, 'cells')) ? join(matrixDir, 'cells') : matrixDir;
+  const reads = readCells(cellsDir);
+  const damaged = reads.filter((entry) => !entry.ok);
+  if (damaged.length > 0) throw new ToolError('MATRIX_INPUT_INVALID', `cannot read ${damaged.length} matrix cell(s), first: ${damaged[0].path}`);
+  const cells = reads.filter((entry) => entry.kind === 'v2' || entry.kind === 'legacy-v1').map((entry) => entry.cell);
+  if (cells.length === 0) throw new ToolError('MATRIX_INPUT_INVALID', `no matrix cells found under ${cellsDir} (no data for ${targetDsh})`);
+  const dshVersions = [...new Set(cells.map((cell) => cell.dsh.version))].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  if (!dshVersions.includes(targetDsh)) {
+    throw new ToolError('MATRIX_INPUT_INVALID', `the matrix has no cells for DSH ${targetDsh} (it covers: ${dshVersions.join(', ') || 'nothing'})`);
+  }
+  const byPlugin = new Map();
+  for (const cell of cells) {
+    if (!byPlugin.has(cell.plugin.name)) byPlugin.set(cell.plugin.name, []);
+    byPlugin.get(cell.plugin.name).push(cell);
+  }
+  return { byPlugin, dshVersions, count: cells.length };
+}
+
+function classifyPlugin(plugin, matrix, targetDsh, composition) {
+  const base = { name: plugin.name, version: plugin.version ?? null, firstParty: false };
+  if (!plugin.version) return { ...base, category: 'unknown', status: 'unknown', reason: 'installed version unknown' };
+  const own = matrix.byPlugin.get(plugin.name) || [];
+  const testedVersions = [...new Set(own.map((cell) => cell.plugin.resolvedVersion || cell.plugin.version))].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  const current = own.filter((cell) => (cell.plugin.resolvedVersion || cell.plugin.version) === plugin.version);
+  if (current.length === 0) {
+    return {
+      ...base,
+      category: 'unknown',
+      status: 'unknown',
+      testedVersions,
+      reason: own.length === 0
+        ? 'plugin is not covered by the matrix'
+        : `version ${plugin.version} is not covered for DSH ${targetDsh} (tested versions: ${testedVersions.join(', ')})`,
+    };
+  }
+  const selection = selectCells(current, { dshVersion: targetDsh, composition });
+  if (selection.kind !== 'cells') {
+    return {
+      ...base,
+      category: selection.kind,
+      status: selection.kind,
+      testedVersions,
+      reason: selection.kind === 'mixed'
+        ? 'multiple compositions are present but the current profile composition is unknown'
+        : selection.kind === 'unknown'
+          ? 'the current profile composition or trust evidence is unknown'
+          : 'no exact cell exists for the installed version, target DSH, and composition',
+    };
+  }
+
+  const statuses = new Set(selection.cells.map((cell) => cell.result.status));
+  const allActiveAndEligible = selection.cells.every((cell) => cell.result.status === 'active' && recommendationEligible(cell));
+  if (allActiveAndEligible) return { ...base, category: 'compatible', status: 'active', composition };
+  if (statuses.size > 1) return { ...base, category: 'mixed', status: 'mixed', testedVersions, reason: 'observations disagree within the selected composition' };
+
+  const currentStatus = selection.cells[0].result.status;
+  const alternatives = testedVersions.filter((version) => version !== plugin.version).filter((version) => {
+    const candidate = selectCells(own.filter((cell) => (cell.plugin.resolvedVersion || cell.plugin.version) === version), { dshVersion: targetDsh, composition });
+    return candidate.kind === 'cells' && candidate.cells.every((cell) => cell.result.status === 'active' && recommendationEligible(cell));
+  }).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  const negative = !['active', 'awaiting-service'].includes(currentStatus);
+  if (alternatives.length > 0 && negative) {
+    return { ...base, category: 'needsUpdate', status: currentStatus, composition, recommendedVersion: alternatives[0], reason: `version ${alternatives[0]} has verified active evidence on the same DSH and composition` };
+  }
+  if (negative) {
+    return { ...base, category: 'noCompatibleVersion', status: currentStatus, composition, testedVersions, reason: 'no verified active version exists for this DSH and composition' };
+  }
+  return { ...base, category: 'untested', status: currentStatus, composition, testedVersions, reason: 'active evidence is missing, self-reported, legacy, stale, or composition-incomplete' };
+}
+
+export async function planUpgrade({ profileDir, matrixDir, from, to, composition }) {
+  if (composition !== undefined && !['headless', 'web'].includes(composition)) throw new ToolError('MATRIX_INPUT_INVALID', 'composition must be headless or web');
+  const profile = readProfile(profileDir);
+  const matrix = readMatrix(matrixDir, to);
+  const selectedComposition = composition || profile.composition;
+  const categories = { compatible: [], untested: [], needsUpdate: [], noCompatibleVersion: [], unknown: [], mixed: [], firstParty: [] };
+  for (const plugin of profile.plugins) {
+    if (plugin.firstParty) {
+      categories.firstParty.push({ name: plugin.name, version: plugin.version ?? null, firstParty: true, category: 'firstParty', status: 'not-covered', reason: 'first-party bundle; the community matrix does not cover it' });
+      continue;
+    }
+    const classified = classifyPlugin(plugin, matrix, to, selectedComposition);
+    categories[classified.category].push(classified);
+  }
+  const installTargets = categories.needsUpdate.filter((plugin) => plugin.recommendedVersion).map((plugin) => `${plugin.name}@${plugin.recommendedVersion}`);
+  const summary = {
+    total: profile.plugins.length,
+    community: profile.plugins.length - categories.firstParty.length,
+    compatible: categories.compatible.length,
+    untested: categories.untested.length,
+    needsUpdate: categories.needsUpdate.length,
+    noCompatibleVersion: categories.noCompatibleVersion.length,
+    unknown: categories.unknown.length,
+    mixed: categories.mixed.length,
+    firstParty: categories.firstParty.length,
+    needAction: categories.needsUpdate.length + categories.noCompatibleVersion.length,
+  };
+  return {
+    schemaVersion: 2,
+    mode: 'upgrade-plan',
+    from,
+    to,
+    composition: selectedComposition || null,
+    profile: { path: profile.path, source: profile.source, bundles: profile.plugins.length, composition: profile.composition || null },
+    matrix: { dir: matrixDir, cells: matrix.count, dshVersions: matrix.dshVersions },
+    categories,
+    summary,
+    installCommand: installTargets.length ? 'npm install ' + installTargets.join(' ') : null,
+  };
+}

package/src/upgrade/profile.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function isDirectory(path) {
+  try { return statSync(path).isDirectory(); } catch { return false; }
+}
+
+function exactVersion(value) {
+  return typeof value === 'string' && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value) ? value : undefined;
+}
+
+function installedVersion(profileDir, name, entry, profileManifest) {
+  if (entry && typeof entry === 'object' && exactVersion(entry.version)) return entry.version;
+  const manifestPath = join(profileDir, 'node_modules', ...name.split('/'), 'package.json');
+  if (existsSync(manifestPath)) {
+    try {
+      const manifest = readJson(manifestPath);
+      if (exactVersion(manifest.version)) return manifest.version;
+    } catch { /* use the profile declaration below */ }
+  }
+  return exactVersion({ ...(profileManifest?.dependencies || {}), ...(profileManifest?.devDependencies || {}) }[name]);
+}
+
+export function readProfile(profileDir) {
+  if (!existsSync(profileDir) || !isDirectory(profileDir)) throw new Error('profile directory not found: ' + profileDir);
+  const manifestPath = join(profileDir, 'package.json');
+  const manifest = existsSync(manifestPath) ? readJson(manifestPath) : undefined;
+  const declared = manifest?.dsh?.profile?.bundles;
+  const composition = ['headless', 'web'].includes(manifest?.dsh?.profile?.composition) ? manifest.dsh.profile.composition : undefined;
+  const plugins = [];
+  const seen = new Set();
+  if (Array.isArray(declared) && declared.length > 0) {
+    for (const entry of declared) {
+      const name = typeof entry === 'string'
+        ? entry.trim()
+        : entry && typeof entry === 'object'
+          ? entry.name || entry.id || entry.package || entry.bundle || entry.plugin
+          : undefined;
+      if (typeof name !== 'string' || !name || seen.has(name)) continue;
+      seen.add(name);
+      plugins.push({ name, version: installedVersion(profileDir, name, entry, manifest), firstParty: name.startsWith('@deepseek-ai/'), source: 'dsh.profile.bundles' });
+    }
+    return { path: profileDir, manifest, plugins, source: 'dsh.profile.bundles', composition };
+  }
+
+  const nodeModulesDir = join(profileDir, 'node_modules');
+  if (manifest === undefined && (!existsSync(nodeModulesDir) || !isDirectory(nodeModulesDir))) {
+    throw new Error('not a profile directory (no package.json and no node_modules): ' + profileDir);
+  }
+  if (!existsSync(nodeModulesDir) || !isDirectory(nodeModulesDir)) {
+    return { path: profileDir, manifest, plugins: [], source: 'none', composition };
+  }
+  const consider = (dir, fallbackName) => {
+    const manifestFile = join(dir, 'package.json');
+    if (!existsSync(manifestFile)) return;
+    let pkg;
+    try { pkg = readJson(manifestFile); } catch { return; }
+    if (!pkg.dsh && !(Array.isArray(pkg.keywords) && pkg.keywords.includes('dsh-plugin'))) return;
+    const name = typeof pkg.name === 'string' && pkg.name ? pkg.name : fallbackName;
+    if (seen.has(name)) return;
+    seen.add(name);
+    plugins.push({ name, version: exactVersion(pkg.version), firstParty: name.startsWith('@deepseek-ai/'), source: 'node_modules' });
+  };
+  for (const entry of readdirSync(nodeModulesDir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const entryPath = join(nodeModulesDir, entry.name);
+    if (!(entry.isDirectory() || (entry.isSymbolicLink() && isDirectory(entryPath)))) continue;
+    if (entry.name.startsWith('@')) {
+      for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+        const childPath = join(entryPath, child.name);
+        if (child.isDirectory() || (child.isSymbolicLink() && isDirectory(childPath))) consider(childPath, entry.name + '/' + child.name);
+      }
+    } else {
+      consider(entryPath, entry.name);
+    }
+  }
+  return { path: profileDir, manifest, plugins, source: 'node_modules', composition };
+}