@dzhechkov/harness-core 0.3.23 → 0.3.25

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/targets.ts

@@ -6,6 +6,7 @@
 
 import { claudeAdapter } from '@dzhechkov/adapter-claude';
 import { codexAdapter } from '@dzhechkov/adapter-codex';
+import { copilotAdapter } from '@dzhechkov/adapter-copilot';
 import { hermesAdapter } from '@dzhechkov/adapter-hermes';
 import { opencodeAdapter } from '@dzhechkov/adapter-opencode';
 import { openclaudeAdapter } from '@dzhechkov/adapter-openclaude';
@@ -15,16 +16,20 @@ import type { Adapter } from '@dzhechkov/core';
  * The targets the harness can initialise. The key is the CLI `--target` name
  * (`claude-code`, not `claude`); the value is the adapter that emits for it.
  */
-export const TARGETS = {
+/** A valid `--target` name. */
+export type TargetName = 'claude-code' | 'codex' | 'opencode' | 'hermes' | 'openclaude' | 'copilot';
+
+// Explicitly annotated (not `as const satisfies`) so the type is portable across
+// the workspace — adapters compiled against slightly different `@dzhechkov/core`
+// versions would otherwise make the inferred type un-nameable (TS2742).
+export const TARGETS: Record<TargetName, Adapter> = {
   'claude-code': claudeAdapter,
   codex: codexAdapter,
   opencode: opencodeAdapter,
   hermes: hermesAdapter,
   openclaude: openclaudeAdapter,
-} as const satisfies Record<string, Adapter>;
-
-/** A valid `--target` name. */
-export type TargetName = keyof typeof TARGETS;
+  copilot: copilotAdapter,
+};
 
 /** Every supported `--target` name. */
 export const TARGET_NAMES = Object.keys(TARGETS) as TargetName[];