@dzhechkov/harness-core 0.2.0

package/src/operations.ts

@@ -0,0 +1,388 @@
+/**
+ * The harness operations — `init`, `sync`, `verify`, `doctor` — as pure-ish
+ * functions returning structured reports. `@dzhechkov/harness-cli` is a thin
+ * argv shell over these.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { claudeAdapter } from '@dzhechkov/adapter-claude';
+
+import { applyEmitResult } from './apply.js';
+import { discoverSkillIds, loadSkillFromDir } from './skills.js';
+import { TARGETS } from './targets.js';
+import type { TargetName } from './targets.js';
+
+// ---------------------------------------------------------------------------
+// init — compile a skills directory for a target and write it (additively)
+// ---------------------------------------------------------------------------
+
+/** Options for {@link runInit}. */
+export interface InitOptions {
+  readonly target: TargetName;
+  /** Source directory of canonical skills. */
+  readonly skillsDir: string;
+  /** Project root the platform tree is written under. */
+  readonly projectRoot: string;
+  /** Overwrite existing files. Default `false` — additive. */
+  readonly force?: boolean;
+  /** When set, install only these skill ids (a preset selection). */
+  readonly select?: readonly string[];
+}
+
+/** Per-skill outcome of {@link runInit}. */
+export interface InitSkillResult {
+  readonly id: string;
+  readonly written: string[];
+  readonly skipped: string[];
+  readonly warnings: string[];
+}
+
+/** The outcome of {@link runInit}. */
+export interface InitReport {
+  readonly target: TargetName;
+  readonly skillsDir: string;
+  readonly projectRoot: string;
+  readonly skills: InitSkillResult[];
+}
+
+/** Compile every skill in `skillsDir` for `target` and apply it under `projectRoot`. */
+export async function runInit(options: InitOptions): Promise<InitReport> {
+  const adapter = TARGETS[options.target];
+  const skills: InitSkillResult[] = [];
+  const selection = options.select;
+  const ids = discoverSkillIds(options.skillsDir).filter(
+    (id) => selection === undefined || selection.includes(id),
+  );
+  for (const id of ids) {
+    const skill = loadSkillFromDir(options.skillsDir, id);
+    const emit = await adapter.compile(skill, { targetRoot: options.projectRoot });
+    const applied = applyEmitResult(emit, {
+      targetRoot: options.projectRoot,
+      force: options.force === true,
+    });
+    skills.push({ id, written: applied.written, skipped: applied.skipped, warnings: [...emit.warnings] });
+  }
+  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills };
+}
+
+// ---------------------------------------------------------------------------
+// verify — compile + structurally verify every skill for a target
+// ---------------------------------------------------------------------------
+
+/** Options for {@link runVerify}. */
+export interface VerifyOptions {
+  readonly skillsDir: string;
+  /** Target to verify against. Default `claude-code`. */
+  readonly target?: TargetName;
+}
+
+/** Per-skill outcome of {@link runVerify}. */
+export interface VerifySkillResult {
+  readonly id: string;
+  readonly ok: boolean;
+  readonly errors: string[];
+  readonly warnings: string[];
+}
+
+/** The outcome of {@link runVerify}. */
+export interface VerifyReport {
+  readonly target: TargetName;
+  readonly skillsDir: string;
+  readonly total: number;
+  readonly valid: number;
+  readonly skills: VerifySkillResult[];
+}
+
+/** Compile every skill for `target` and report whether each verifies. */
+export async function runVerify(options: VerifyOptions): Promise<VerifyReport> {
+  const target: TargetName = options.target ?? 'claude-code';
+  const adapter = TARGETS[target];
+  const skills: VerifySkillResult[] = [];
+  for (const id of discoverSkillIds(options.skillsDir)) {
+    try {
+      const skill = loadSkillFromDir(options.skillsDir, id);
+      const emit = await adapter.compile(skill, { targetRoot: '.' });
+      const result = await adapter.verify(emit);
+      skills.push({ id, ok: result.ok, errors: [...result.errors], warnings: [...result.warnings] });
+    } catch (error) {
+      skills.push({
+        id,
+        ok: false,
+        errors: [error instanceof Error ? error.message : String(error)],
+        warnings: [],
+      });
+    }
+  }
+  return {
+    target,
+    skillsDir: options.skillsDir,
+    total: skills.length,
+    valid: skills.filter((skill) => skill.ok).length,
+    skills,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// sync — canonical pack -> legacy .claude/skills tree (ADR-002)
+// ---------------------------------------------------------------------------
+
+/** Options for {@link runSync}. */
+export interface SyncOptions {
+  /** Canonical skill pack directory (single source). */
+  readonly canonicalDir?: string;
+  /** Multiple canonical pack directories (multi-source). Takes precedence over canonicalDir. */
+  readonly canonicalDirs?: readonly string[];
+  /** Project root containing the legacy `.claude/skills` tree. */
+  readonly projectRoot: string;
+  /** Report only, write nothing. */
+  readonly dryRun?: boolean;
+  /** Overwrite drifted legacy files. Default `false`. */
+  readonly force?: boolean;
+}
+
+/** Per-skill outcome of {@link runSync}. */
+export interface SyncSkillResult {
+  readonly id: string;
+  readonly status: 'in-sync' | 'missing' | 'drift';
+  readonly written: string[];
+}
+
+/** The outcome of {@link runSync}. */
+export interface SyncReport {
+  readonly dryRun: boolean;
+  readonly skills: SyncSkillResult[];
+  readonly summary: { total: number; inSync: number; missing: number; drift: number };
+}
+
+/** Compare each canonical skill (compiled for Claude Code) to the legacy tree. */
+export async function runSync(options: SyncOptions): Promise<SyncReport> {
+  const dirs = options.canonicalDirs ?? (options.canonicalDir ? [options.canonicalDir] : []);
+  const skills: SyncSkillResult[] = [];
+  for (const canonicalDir of dirs) {
+    for (const id of discoverSkillIds(canonicalDir)) {
+    const skill = loadSkillFromDir(canonicalDir, id);
+    const emit = await claudeAdapter.compile(skill, { targetRoot: options.projectRoot });
+
+    let differ = false;
+    let missing = false;
+    for (const file of emit.files) {
+      const absolutePath = join(options.projectRoot, file.path);
+      if (!existsSync(absolutePath)) missing = true;
+      else if (readFileSync(absolutePath, 'utf-8') !== file.content) differ = true;
+    }
+    const status: SyncSkillResult['status'] = differ ? 'drift' : missing ? 'missing' : 'in-sync';
+
+    let written: string[] = [];
+    const shouldWrite = status === 'missing' || (status === 'drift' && options.force === true);
+    if (options.dryRun !== true && shouldWrite) {
+      written = applyEmitResult(emit, {
+        targetRoot: options.projectRoot,
+        force: status === 'drift',
+      }).written;
+    }
+    skills.push({ id, status, written });
+  }}
+  return {
+    dryRun: options.dryRun === true,
+    skills,
+    summary: {
+      total: skills.length,
+      inSync: skills.filter((skill) => skill.status === 'in-sync').length,
+      missing: skills.filter((skill) => skill.status === 'missing').length,
+      drift: skills.filter((skill) => skill.status === 'drift').length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// migrate — detect keysarium/.bto/.keysarium.json installations
+// ---------------------------------------------------------------------------
+
+/** A detected legacy CLI installation. */
+export interface MigrateDetection {
+  readonly manifest: string;
+  readonly version: string;
+  readonly components: string[];
+  readonly fileCount: number;
+}
+
+/** The outcome of {@link runMigrate}. */
+export interface MigrateReport {
+  readonly projectRoot: string;
+  readonly detections: MigrateDetection[];
+  readonly skillsFound: number;
+  readonly recommendation: string;
+}
+
+/** Detect keysarium/bto/etc installations and report migration path. */
+export function runMigrate(options: { projectRoot: string }): MigrateReport {
+  const root = options.projectRoot;
+  const detections: MigrateDetection[] = [];
+
+  // Check for known manifests
+  const manifests = ['.keysarium.json', '.bto.json', '.analyst-manual.json', '.edu-site.json', '.transcript-site.json', '.feature-adr.json'];
+  for (const manifest of manifests) {
+    const path = join(root, manifest);
+    if (existsSync(path)) {
+      try {
+        const data = JSON.parse(readFileSync(path, 'utf-8'));
+        detections.push({
+          manifest,
+          version: data.version ?? 'unknown',
+          components: data.components ?? [],
+          fileCount: Array.isArray(data.files) ? data.files.length : 0,
+        });
+      } catch {
+        detections.push({ manifest, version: 'parse-error', components: [], fileCount: 0 });
+      }
+    }
+  }
+
+  // Count skills in .claude/skills
+  const skillsDir = join(root, '.claude', 'skills');
+  let skillsFound = 0;
+  if (existsSync(skillsDir)) {
+    skillsFound = readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && existsSync(join(skillsDir, e.name, 'SKILL.md')))
+      .length;
+  }
+
+  let recommendation: string;
+  if (detections.length === 0) {
+    recommendation = 'No legacy installations detected. Use `dz init` to install skills.';
+  } else if (detections.length === 1) {
+    const d = detections[0]!;
+    recommendation = `Found ${d.manifest} (v${d.version}, ${d.fileCount} files). Skills are already in .claude/skills/ — use \`dz sync\` to manage them canonically.`;
+  } else {
+    recommendation = `Found ${detections.length} legacy manifests. Skills coexist in .claude/skills/. Run \`dz doctor\` to verify health, then \`dz sync\` to adopt canonical management.`;
+  }
+
+  return { projectRoot: root, detections, skillsFound, recommendation };
+}
+
+// ---------------------------------------------------------------------------
+// doctor — environment diagnostics
+// ---------------------------------------------------------------------------
+
+/** A single {@link runDoctor} check. */
+export interface DoctorCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail: string;
+}
+
+/** The outcome of {@link runDoctor}. */
+export interface DoctorReport {
+  readonly node: string;
+  readonly checks: DoctorCheck[];
+  readonly ok: boolean;
+}
+
+/** Report environment diagnostics for the harness. */
+export async function runDoctor(options: { projectRoot: string }): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = [];
+  const root = options.projectRoot;
+
+  // 1. Node version
+  const nodeMajor = Number(process.versions.node.split('.')[0] ?? '0');
+  checks.push({ name: 'node >= 20', ok: nodeMajor >= 20, detail: `node ${process.version}` });
+
+  // 2. Key directories
+  for (const dir of ['.claude/skills', 'packages/@dzhechkov/skills-meta']) {
+    checks.push({
+      name: `${dir} present`,
+      ok: existsSync(join(root, dir)),
+      detail: dir,
+    });
+  }
+
+  // 3. Adapter resolvability
+  const adapters = ['adapter-claude', 'adapter-codex', 'adapter-hermes', 'adapter-opencode'];
+  const foundAdapters = adapters.filter((a) => existsSync(join(root, 'packages/@dzhechkov', a)));
+  checks.push({
+    name: 'adapters present',
+    ok: foundAdapters.length === 4,
+    detail: `${foundAdapters.length}/4 adapters found`,
+  });
+
+  // 4. Package version consistency
+  const pkgsDir = join(root, 'packages/@dzhechkov');
+  if (existsSync(pkgsDir)) {
+    const versions = new Map<string, string>();
+    let consistent = true;
+    let detail = '';
+    try {
+      const entries = readdirSync(pkgsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const pjPath = join(pkgsDir, entry.name, 'package.json');
+        if (!existsSync(pjPath)) continue;
+        const pj = JSON.parse(readFileSync(pjPath, 'utf-8'));
+        if (pj.version) versions.set(entry.name, pj.version as string);
+      }
+      const uniqueVersions = new Set(versions.values());
+      detail = `${versions.size} packages, ${uniqueVersions.size} unique version(s)`;
+      // Warn if more than 10 unique versions (some variation is expected in a large monorepo)
+      if (uniqueVersions.size > 10) {
+        consistent = false;
+        detail += ' — high version divergence';
+      }
+    } catch {
+      consistent = false;
+      detail = 'failed to read package versions';
+    }
+    checks.push({ name: 'package versions', ok: consistent, detail });
+  }
+
+  // 5. Config lint (.agentic-qe/config.yaml)
+  const configPath = join(root, '.agentic-qe', 'config.yaml');
+  if (existsSync(configPath)) {
+    try {
+      const { parse: parseYaml } = await import('yaml');
+      const content = readFileSync(configPath, 'utf-8');
+      const parsed = parseYaml(content);
+      const hasProject = typeof parsed?.project === 'string';
+      checks.push({
+        name: 'aqe config valid',
+        ok: hasProject,
+        detail: hasProject ? `project: ${parsed.project}` : 'missing project field',
+      });
+    } catch (error) {
+      checks.push({
+        name: 'aqe config valid',
+        ok: false,
+        detail: `parse error: ${error instanceof Error ? error.message : String(error)}`,
+      });
+    }
+  } else {
+    checks.push({ name: 'aqe config valid', ok: true, detail: 'no .agentic-qe/config.yaml (optional)' });
+  }
+
+  // 6. SQLite memory backend probe
+  try {
+    const { createRequire } = await import('node:module');
+    const req = createRequire(join(root, 'package.json'));
+    req.resolve('better-sqlite3');
+    checks.push({ name: 'sqlite backend', ok: true, detail: 'better-sqlite3 available' });
+  } catch {
+    checks.push({ name: 'sqlite backend', ok: true, detail: 'better-sqlite3 not installed (JSON fallback)' });
+  }
+
+  // 7. Skills directory health
+  const skillsDir = join(root, '.claude', 'skills');
+  if (existsSync(skillsDir)) {
+    const skillDirs = readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory());
+    const withSkillMd = skillDirs.filter((e) => existsSync(join(skillsDir, e.name, 'SKILL.md')));
+    checks.push({
+      name: 'skills health',
+      ok: withSkillMd.length === skillDirs.length,
+      detail: `${withSkillMd.length}/${skillDirs.length} skill dirs have SKILL.md`,
+    });
+  }
+
+  return { node: process.version, checks, ok: checks.every((check) => check.ok) };
+}

package/src/security/boundaries.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "Input boundary catalog for DZ harness — every external input surface and its validator.",
+  "version": "0.1.0-RC",
+  "boundaries": [
+    {
+      "id": "cli-args",
+      "description": "Raw argv from the `dz` CLI — parsed by the internal parseArgs function that splits positional, --key value, and --flag tokens.",
+      "validator": "packages/@dzhechkov/harness-cli/src/cli.ts",
+      "scan": "parseArgs"
+    },
+    {
+      "id": "mcp-tool-inputs",
+      "description": "JSON-RPC tool call parameters received by the MCP server — each tool's inputSchema is a Zod schema that validates before the handler runs.",
+      "validator": "packages/@dzhechkov/mcp-server-tools/src/server.ts",
+      "scan": "zod-inputSchema"
+    },
+    {
+      "id": "skills-dir",
+      "description": "Filesystem path to the skills directory — resolved to an absolute path and checked with existsSync before any I/O.",
+      "validator": "packages/@dzhechkov/harness-core/src/skills.ts",
+      "scan": "existsSync"
+    },
+    {
+      "id": "emit-paths",
+      "description": "Skill id and asset paths used during emit — assertSafeId rejects empty, dot-dot, and slash-containing ids; normalizeAssetPath rejects traversal.",
+      "validator": "packages/@dzhechkov/core/src/skill-emit.ts",
+      "scan": "assertSafeId"
+    },
+    {
+      "id": "preset-name",
+      "description": "The --preset value supplied to `dz init` — validated by isPresetName which checks against the PRESETS const object.",
+      "validator": "packages/@dzhechkov/harness-presets/src/presets.ts",
+      "scan": "isPresetName"
+    },
+    {
+      "id": "target-name",
+      "description": "The --target value supplied to `dz init` / `dz verify` — validated by isTargetName which checks against the TARGETS const object.",
+      "validator": "packages/@dzhechkov/harness-core/src/targets.ts",
+      "scan": "isTargetName"
+    },
+    {
+      "id": "memory-record-id",
+      "description": "The unique record id for memory backend put/query — typed as string in the MemoryRecord interface; no further runtime validation beyond TypeScript.",
+      "validator": "packages/@dzhechkov/memory/src/backend.ts",
+      "scan": "string-type"
+    },
+    {
+      "id": "config-yaml",
+      "description": "The .agentic-qe/config.yaml file parsed by `dz doctor` — validated by yaml.parse with a structural check (typeof parsed?.project === 'string').",
+      "validator": "packages/@dzhechkov/harness-core/src/operations.ts",
+      "scan": "yaml.parse"
+    }
+  ]
+}

package/src/skills.ts

@@ -0,0 +1,109 @@
+/**
+ * Skill discovery + loading — the consolidated filesystem loader.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { ClaudeSkillFrontmatterSchema, parseSkillDocument } from '@dzhechkov/core';
+import type { CanonicalSkill, SkillAsset } from '@dzhechkov/core';
+
+/** A discovered skill — id plus its description, for listings. */
+export interface SkillSummary {
+  readonly id: string;
+  readonly description: string;
+}
+
+/** Detailed skill info. */
+export interface SkillInfo {
+  readonly id: string;
+  readonly description: string;
+  readonly name: string;
+  readonly trustTier: number | undefined;
+  readonly version: string | number | undefined;
+  readonly assetCount: number;
+  readonly assetPaths: string[];
+  readonly frontmatter: Record<string, unknown>;
+}
+
+/** Recursively list every file under `dir`. */
+function walkFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(full));
+    else if (entry.isFile()) out.push(full);
+  }
+  return out;
+}
+
+/** Return the ids of every `<skillsDir>/<id>/SKILL.md`, sorted. */
+export function discoverSkillIds(skillsDir: string): string[] {
+  if (!existsSync(skillsDir)) return [];
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(skillsDir, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+/** Discover every skill in `skillsDir`, returning id + description. */
+export function listSkills(skillsDir: string): SkillSummary[] {
+  return discoverSkillIds(skillsDir).map((id) => {
+    const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
+    const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
+    return { id, description: frontmatter.description };
+  });
+}
+
+/** Get detailed info about a single skill without loading all assets. */
+export function getSkillInfo(skillsDir: string, id: string): SkillInfo | undefined {
+  const skillDir = join(skillsDir, id);
+  const skillMdPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMdPath)) return undefined;
+  const document = parseSkillDocument(readFileSync(skillMdPath, 'utf-8'));
+  const fm = parseYaml(document.frontmatterYaml) as Record<string, unknown>;
+  const parsed = ClaudeSkillFrontmatterSchema.parse(fm);
+  const assetPaths = walkFiles(skillDir)
+    .filter((p) => p !== skillMdPath)
+    .map((p) => relative(skillDir, p).split('\\').join('/'))
+    .sort();
+  return {
+    id,
+    description: parsed.description,
+    name: parsed.name ?? id,
+    trustTier: fm['trust_tier'] as number | undefined,
+    version: parsed.version as string | number | undefined,
+    assetCount: assetPaths.length,
+    assetPaths,
+    frontmatter: fm,
+  };
+}
+
+/**
+ * Load one `<skillsDir>/<id>/` directory into a {@link CanonicalSkill}: its
+ * `SKILL.md` document plus every other file as a bundled asset.
+ *
+ * @throws if the skill directory has no `SKILL.md`.
+ */
+export function loadSkillFromDir(skillsDir: string, id: string): CanonicalSkill {
+  const skillDir = join(skillsDir, id);
+  const skillMdPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMdPath)) {
+    throw new Error(`skill not found: ${JSON.stringify(id)} (looked in ${skillsDir})`);
+  }
+  const document = parseSkillDocument(readFileSync(skillMdPath, 'utf-8'));
+  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'),
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  return { id, frontmatter, document, assets };
+}

package/src/targets.ts

@@ -0,0 +1,33 @@
+/**
+ * `--target` names → platform adapters.
+ *
+ * @packageDocumentation
+ */
+
+import { claudeAdapter } from '@dzhechkov/adapter-claude';
+import { codexAdapter } from '@dzhechkov/adapter-codex';
+import { hermesAdapter } from '@dzhechkov/adapter-hermes';
+import { opencodeAdapter } from '@dzhechkov/adapter-opencode';
+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 = {
+  'claude-code': claudeAdapter,
+  codex: codexAdapter,
+  opencode: opencodeAdapter,
+  hermes: hermesAdapter,
+} as const satisfies Record<string, Adapter>;
+
+/** A valid `--target` name. */
+export type TargetName = keyof typeof TARGETS;
+
+/** Every supported `--target` name. */
+export const TARGET_NAMES = Object.keys(TARGETS) as TargetName[];
+
+/** Type guard: is `value` a supported `--target` name? */
+export function isTargetName(value: string): value is TargetName {
+  return Object.prototype.hasOwnProperty.call(TARGETS, value);
+}