@dzhechkov/harness-core 0.3.22 → 0.3.24

package/src/reconcile.ts

@@ -0,0 +1,207 @@
+/**
+ * `dz mcp-scan --reconcile` — static capability reconciliation (Phase 3).
+ *
+ * Joins two things `dz` can read deterministically:
+ *  - the project's GRANT surface (`scanMcp` of `.claude/settings*.json` + `.mcp.json`), and
+ *  - the aggregate DECLARED capabilities of the installed skills (`.claude/skills/<id>/SKILL.md`),
+ * then REPORTS the gaps (under-grant / over-grant) and, optionally, EMITS a
+ * least-privilege advisory policy artifact for a host to consume.
+ *
+ * HONESTY: `dz` is build-time / static. It does NOT run agents and CANNOT block,
+ * time out, or rate-limit a tool call. The HOST (Claude Code enforcing
+ * settings.json allow/deny; or an MCP server consuming a policy.json) is the only
+ * thing that enforces at call time. Verbs here are REPORT / RECONCILE / EMIT /
+ * CANDIDATE — never BLOCK / DENIED / ENFORCED.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { parseDeclaredCapabilities, parseDeclaredLimits, type DeclaredLimits } from './capability-vocab.js';
+import type { McpScanReport } from './mcp-scan.js';
+
+/** The honesty banner — repeated in --help, the report header, and the artifact $comment. */
+export const RECONCILE_BANNER =
+  'dz is build-time/static: it REPORTS the grant-vs-declaration gap and may EMIT an advisory policy, ' +
+  'but does NOT block, time out, or rate-limit anything. The HOST (Claude Code settings.json; or an MCP ' +
+  'server consuming policy.json) is the only thing that enforces at call time.';
+
+/** A reconcilable capability axis (the axes BOTH the grant surface and the manifest expose). */
+export type ReconcileAxis = 'shell' | 'network' | 'file-write';
+const AXES: readonly ReconcileAxis[] = ['shell', 'network', 'file-write'];
+
+/** Per-axis reconciliation state. */
+export interface AxisState {
+  readonly axis: ReconcileAxis;
+  /** Project permits this capability (from scanMcp). */
+  readonly grant: boolean;
+  /** At least one installed skill declares it needs this (declared === true). */
+  readonly need: boolean;
+  /** Skills that declared need (true) — for attribution. */
+  readonly needSkills: readonly string[];
+  /** Installed skills that are SILENT on this axis (declared === undefined). */
+  readonly silentCount: number;
+}
+
+/** A single reconciliation finding. */
+export interface ReconcileFinding {
+  readonly id: string;
+  readonly kind: 'under-grant' | 'over-grant';
+  readonly severity: 'medium' | 'low' | 'info';
+  readonly axis: ReconcileAxis;
+  readonly detail: string;
+  readonly skills: readonly string[];
+}
+
+/** Aggregated declared limits across installed skills (tightest values; inert). */
+export interface LimitsRollup {
+  readonly declaredBy: number;
+  readonly toolTimeoutMs?: number;
+  readonly maxToolCallsPerTurn?: number;
+  readonly requireApprovalForDangerous?: boolean;
+}
+
+/** The least-privilege advisory policy artifact (only written with --emit-policy). */
+export interface PolicyArtifact {
+  readonly $comment: string;
+  readonly version: 1;
+  readonly defaultDeny: true;
+  /** axis → true ONLY where an installed skill declared need; absent otherwise. */
+  readonly allow: Partial<Record<ReconcileAxis, true>>;
+  readonly limits?: LimitsRollup;
+  readonly derivedFrom: {
+    readonly grants: Record<ReconcileAxis, boolean>;
+    readonly declaredNeed: Record<ReconcileAxis, boolean>;
+    readonly skillsByAxis: Partial<Record<ReconcileAxis, readonly string[]>>;
+  };
+}
+
+/** Result of {@link reconcileCapabilities}. */
+export interface ReconcileReport {
+  readonly skillsDir: string;
+  readonly installedCount: number;
+  readonly axes: readonly AxisState[];
+  readonly findings: readonly ReconcileFinding[];
+  readonly limits: LimitsRollup | null;
+  readonly policy: PolicyArtifact;
+}
+
+interface InstalledDecl {
+  id: string;
+  caps: ReturnType<typeof parseDeclaredCapabilities>;
+  limits: DeclaredLimits;
+}
+
+function readInstalled(skillsDir: string): InstalledDecl[] {
+  if (!existsSync(skillsDir)) return [];
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: InstalledDecl[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const md = join(skillsDir, e.name, 'SKILL.md');
+    if (!existsSync(md)) continue;
+    let content: string;
+    try {
+      content = readFileSync(md, 'utf-8');
+    } catch {
+      continue;
+    }
+    out.push({ id: e.name, caps: parseDeclaredCapabilities(content), limits: parseDeclaredLimits(content) });
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function grantFor(report: McpScanReport, axis: ReconcileAxis): boolean {
+  const c = report.capabilities;
+  return axis === 'shell' ? c.shell : axis === 'network' ? c.network : c.fileWrite;
+}
+
+/**
+ * Statically reconcile a project's GRANT surface against the DECLARED needs of
+ * its installed skills. Pure: same inputs → same report. No execution, no writes.
+ */
+export function reconcileCapabilities(report: McpScanReport, skillsDir: string): ReconcileReport {
+  const installed = readInstalled(skillsDir);
+
+  const axes: AxisState[] = [];
+  const findings: ReconcileFinding[] = [];
+  const allow: Partial<Record<ReconcileAxis, true>> = {};
+  const grants = {} as Record<ReconcileAxis, boolean>;
+  const declaredNeed = {} as Record<ReconcileAxis, boolean>;
+  const skillsByAxis: Partial<Record<ReconcileAxis, readonly string[]>> = {};
+
+  for (const axis of AXES) {
+    const grant = grantFor(report, axis);
+    const needSkills = installed.filter((s) => s.caps[axis] === true).map((s) => s.id);
+    const need = needSkills.length > 0;
+    const silentCount = installed.filter((s) => s.caps[axis] === undefined).length;
+    axes.push({ axis, grant, need, needSkills, silentCount });
+    grants[axis] = grant;
+    declaredNeed[axis] = need;
+    if (need) {
+      skillsByAxis[axis] = needSkills;
+      allow[axis] = true;
+    }
+
+    if (need && !grant) {
+      findings.push({
+        id: `MS-UNDERGRANT-${axis.toUpperCase()}`,
+        kind: 'under-grant',
+        severity: 'medium',
+        axis,
+        detail: `${needSkills.length} installed skill(s) declare needing ${axis}, but the grant surface does not permit it — the host will starve them at runtime. Add the grant or remove the skill(s).`,
+        skills: needSkills,
+      });
+    } else if (grant && !need) {
+      // over-grant is ALWAYS advisory; downgrade to info when any skill is silent
+      // (it may genuinely need the grant but didn't declare), or when there are
+      // no installed skills at all.
+      const downgrade = silentCount > 0 || installed.length === 0;
+      findings.push({
+        id: `MS-OVERGRANT-${axis.toUpperCase()}`,
+        kind: 'over-grant',
+        severity: downgrade ? 'info' : 'low',
+        axis,
+        detail: `The project permits ${axis} but no installed skill declares needing it${silentCount > 0 ? ` (${silentCount} skill(s) silent on ${axis})` : ''} — least-privilege CANDIDATE to revoke; may be for the operator or a non-skill MCP server.`,
+        skills: [],
+      });
+    }
+  }
+
+  // limits roll-up (tightest values) — INERT, never a gate
+  const withLimits = installed.filter((s) => Object.keys(s.limits).length > 0);
+  let limits: LimitsRollup | null = null;
+  if (withLimits.length > 0) {
+    const tts = withLimits.map((s) => s.limits.toolTimeoutMs).filter((n): n is number => typeof n === 'number');
+    const mcs = withLimits.map((s) => s.limits.maxToolCallsPerTurn).filter((n): n is number => typeof n === 'number');
+    const ras = withLimits.some((s) => s.limits.requireApprovalForDangerous === true);
+    limits = {
+      declaredBy: withLimits.length,
+      ...(tts.length > 0 ? { toolTimeoutMs: Math.min(...tts) } : {}),
+      ...(mcs.length > 0 ? { maxToolCallsPerTurn: Math.min(...mcs) } : {}),
+      ...(ras ? { requireApprovalForDangerous: true } : {}),
+    };
+  }
+
+  const policy: PolicyArtifact = {
+    $comment: `ADVISORY. ${RECONCILE_BANNER} A host MUST consume this; dz does not.`,
+    version: 1,
+    defaultDeny: true,
+    allow,
+    ...(limits ? { limits } : {}),
+    derivedFrom: { grants, declaredNeed, skillsByAxis },
+  };
+
+  // stable ordering: under-grant (medium) first, then over-grant
+  const order = { medium: 0, low: 1, info: 2 } as const;
+  findings.sort((a, b) => order[a.severity] - order[b.severity] || a.axis.localeCompare(b.axis));
+
+  return { skillsDir, installedCount: installed.length, axes, findings, limits, policy };
+}

package/src/skills.ts

@@ -30,6 +30,31 @@ export interface SkillInfo {
   readonly frontmatter: Record<string, unknown>;
 }
 
+/**
+ * Read one asset file, choosing the encoding that round-trips losslessly.
+ *
+ * Text files are read as `utf-8`. Binary files (detected by a NUL byte or a
+ * byte sequence that does not survive a `utf-8` decode/encode round-trip) are
+ * read as `base64` so {@link applyEmitResult} writes them back byte-for-byte.
+ * Without this, binary assets (PNGs, fonts, archives) were silently mangled by
+ * a hardcoded `utf-8` read while `verify` still reported `ok`.
+ */
+function readAssetContent(path: string): { encoding: 'utf-8' | 'base64'; content: string } {
+  const buf = readFileSync(path);
+  // NUL byte is a strong, cheap signal of binary content.
+  if (buf.includes(0)) {
+    return { encoding: 'base64', content: buf.toString('base64') };
+  }
+  // Round-trip through utf-8: if decoding then re-encoding changes the bytes,
+  // the file is not valid utf-8 (e.g. latin-1 / arbitrary binary) and must be
+  // preserved as base64.
+  const decoded = buf.toString('utf-8');
+  if (!Buffer.from(decoded, 'utf-8').equals(buf)) {
+    return { encoding: 'base64', content: buf.toString('base64') };
+  }
+  return { encoding: 'utf-8', content: decoded };
+}
+
 /** Recursively list every file under `dir`. */
 function walkFiles(dir: string): string[] {
   const out: string[] = [];
@@ -99,11 +124,14 @@ export function loadSkillFromDir(skillsDir: string, id: string): CanonicalSkill
   const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
   const assets: SkillAsset[] = walkFiles(skillDir)
     .filter((path) => path !== skillMdPath)
-    .map((path) => ({
-      path: relative(skillDir, path).split('\\').join('/'),
-      encoding: 'utf-8' as const,
-      content: readFileSync(path, 'utf-8'),
-    }))
+    .map((path) => {
+      const { encoding, content } = readAssetContent(path);
+      return {
+        path: relative(skillDir, path).split('\\').join('/'),
+        encoding,
+        content,
+      };
+    })
     .sort((a, b) => a.path.localeCompare(b.path));
   return { id, frontmatter, document, assets };
 }