@dzhechkov/harness-core 0.3.18 → 0.3.20

package/src/recommend.ts

@@ -14,6 +14,7 @@
  */
 
 import type { Registry, RegistryEntry } from './registry.js';
+import { pretrain } from './pretrain.js';
 
 /** A recommended skill with relevance score. */
 export interface SkillRecommendation {
@@ -60,13 +61,15 @@ export interface RecommendationReport {
   readonly commands: readonly CommandRecommendation[];
   readonly installCommand: string;
   readonly plan: readonly string[];
+  /** Set when task was too generic and pretrain was used as fallback. */
+  readonly pretrainFallback?: boolean;
 }
 
 /** Topic → keywords mapping for task decomposition. */
 const TOPIC_KEYWORDS: Record<string, string[]> = {
   'api': ['api', 'rest', 'graphql', 'endpoint', 'openapi', 'swagger', 'http', 'grpc'],
   'testing': ['test', 'testing', 'tdd', 'unit test', 'integration test', 'e2e', 'coverage', 'spec'],
-  'ci-cd': ['ci', 'cd', 'pipeline', 'github actions', 'gitlab', 'jenkins', 'deploy', 'build'],
+  'ci-cd': ['ci/cd', 'ci cd', 'pipeline', 'github actions', 'gitlab', 'jenkins', 'deploy', 'continuous integration', 'continuous delivery'],
   'security': ['security', 'audit', 'vulnerability', 'owasp', 'injection', 'auth', 'codeql', 'sast'],
   'database': ['database', 'migration', 'schema', 'sql', 'postgres', 'mysql', 'query', 'index'],
   'kubernetes': ['kubernetes', 'k8s', 'helm', 'pod', 'deployment', 'container', 'cluster', 'service mesh'],
@@ -75,7 +78,7 @@ const TOPIC_KEYWORDS: Record<string, string[]> = {
   'monitoring': ['monitoring', 'observability', 'metrics', 'logs', 'traces', 'alerting', 'slo', 'grafana', 'prometheus'],
   'incident': ['incident', 'outage', 'postmortem', 'oncall', 'pagerduty', 'sev1', 'downtime'],
   'monorepo': ['monorepo', 'workspace', 'pnpm', 'turborepo', 'nx', 'changeset', 'lerna'],
-  'review': ['review', 'pr', 'pull request', 'code review', 'merge'],
+  'review': ['review', 'pull request', 'code review', 'merge', ' pr ', 'pr '],
   'debug': ['debug', 'error', 'crash', 'stack trace', 'bug', 'fix', 'troubleshoot'],
   'frontend': ['frontend', 'react', 'vue', 'component', 'ui', 'css', 'tailwind'],
   'git': ['git', 'merge', 'rebase', 'conflict', 'branch', 'cherry-pick'],
@@ -167,9 +170,32 @@ function scoreSkill(entry: RegistryEntry, topics: string[]): number {
   return score;
 }
 
-/** Generate recommendation from a task and registry. */
-export function recommend(task: string, registry: Registry): RecommendationReport {
-  const topics = extractTopics(task);
+/** Generate recommendation from a task and registry.
+ *  When task is too generic (only 'general' topic), falls back to pretrain
+ *  to analyze the actual project and recommend based on tech stack.
+ */
+export function recommend(task: string, registry: Registry, projectRoot?: string): RecommendationReport {
+  let topics = extractTopics(task);
+  let pretrainFallback = false;
+
+  // Fallback: if task is too generic, use pretrain to detect project stack
+  if (topics.length === 1 && topics[0] === 'general' && projectRoot) {
+    const analysis = pretrain(projectRoot);
+    const pretrainTopics: string[] = [];
+    const techNames = analysis.techs.map((t) => t.name.toLowerCase());
+    if (techNames.some((t) => t.includes('node') || t.includes('typescript'))) pretrainTopics.push('api', 'testing');
+    if (techNames.some((t) => t.includes('python') || t.includes('django') || t.includes('fastapi'))) pretrainTopics.push('api', 'testing');
+    if (techNames.some((t) => t.includes('react') || t.includes('vue') || t.includes('angular'))) pretrainTopics.push('frontend');
+    if (analysis.hasDocker) pretrainTopics.push('docker');
+    if (analysis.hasTerraform) pretrainTopics.push('terraform');
+    if (analysis.hasKubernetes) pretrainTopics.push('kubernetes');
+    if (analysis.hasCI) pretrainTopics.push('ci-cd');
+    if (analysis.hasTests) pretrainTopics.push('testing');
+    if (pretrainTopics.length > 0) {
+      topics = [...new Set(pretrainTopics)];
+      pretrainFallback = true;
+    }
+  }
 
   // Score and rank skills
   const scored = registry.entries
@@ -252,5 +278,5 @@ export function recommend(task: string, registry: Registry): RecommendationRepor
   }
   plan.push(`${plan.length + 1}. Use your agent normally — skills auto-activate on matching tasks`);
 
-  return { task, topics, skills, presets, toolkits, commands, installCommand, plan };
+  return { task, topics, skills, presets, toolkits, commands, installCommand, plan, pretrainFallback };
 }

package/src/setup.ts

@@ -29,6 +29,8 @@ export interface SetupOptions {
   readonly noMemory?: boolean | undefined;
   readonly noPretrain?: boolean | undefined;
   readonly force?: boolean | undefined;
+  /** Also deploy the operating-instructions "driver" skill + agent docs. */
+  readonly installDriver?: boolean | undefined;
 }
 
 /** Setup result. */
@@ -122,6 +124,125 @@ function isAgentdbAvailable(): boolean {
 }
 
 /** Run full environment setup. */
+/** Marker that brackets the dz-harness section in a shared CLAUDE.md/AGENTS.md. */
+const DRIVER_MARKER_START = '<!-- dz-harness-driver:start -->';
+const DRIVER_MARKER_END = '<!-- dz-harness-driver:end -->';
+
+/**
+ * Operating instructions for a coding agent that should *drive* the dz CLI
+ * correctly. Inspired by Visa VVAH `--install-agents`: the toolkit ships its own
+ * "how to operate me" doc so agents use the CLI as intended rather than guessing.
+ */
+function generateDriverInstructions(): string {
+  return `# Operating dz-harness-hub (CLI driver)
+
+You have the \`dz\` CLI (\`@dzhechkov/harness-cli\`) available. It manages cross-platform
+AI skills (the agentskills.io \`SKILL.md\` format) across Claude Code, Codex, OpenCode,
+Hermes, and OpenClaude.
+
+## Core commands
+
+| Command | Use it when |
+|---------|-------------|
+| \`dz recommend "<task>"\` | The user describes a task — suggests the right skills/preset/npx package. Start here. |
+| \`dz setup --target <t> [--preset <p>] [--memory agentdb]\` | Bootstrap a project: config, hooks, learning memory. |
+| \`dz init --target <t> [--preset <p>] [--select id,id]\` | Install skills into a project for a platform. |
+| \`dz benchmark <skill-dir>\` | Score a skill (L0 structural checks, grade A–F, cost band). |
+| \`dz pretrain\` | Detect the project's tech stack and pre-load relevant skills. |
+| \`dz scout [--deep]\` | Discover new skill sources across the ecosystem. |
+| \`dz import-ecc\` | Import skills from an ECC repo. |
+
+## Rules for driving this CLI
+
+1. **Do NOT hand-edit \`SKILL.md\` files to make a benchmark pass** — fix the underlying
+   structure (missing frontmatter, sections, schema) instead.
+2. **Do NOT hand-write \`.dz/config.json\`** — run \`dz setup\` and let it generate config.
+3. **Skills are agentskills.io format** — YAML frontmatter (name, description, trust_tier,
+   validation) + a Markdown body with a Protocol and Anti-Patterns section.
+4. **Presets bundle skills**; prefer \`--preset\` over selecting individual skills unless the
+   user wants a minimal install.
+5. **Trust tiers**: tier 1 (Structured) → run \`/bto-test\` to promote to tier 2 (Validated).
+6. When unsure which skills fit, run \`dz recommend\` first and follow its output.
+
+## Targets (platform install dirs)
+
+claude-code → \`.claude/skills/\` · codex → \`.agents/skills/\` · opencode → \`.opencode/\` ·
+hermes → \`.hermes/\` · openclaude → \`.claude/skills/\`. The SKILL.md format is identical
+across all five — only the directory differs.
+`;
+}
+
+/** The same instructions packaged as a loadable Claude Code skill. */
+function generateDriverSkill(): string {
+  return `---
+name: dz-harness-driver
+description: >
+  Operating instructions for the dz-harness-hub CLI (@dzhechkov/harness-cli). Load this when
+  asked to install/manage AI skills, set up a project with dz, benchmark a skill, or pick
+  the right preset. Tells you which dz command to run and the rules for driving the toolkit.
+  Triggers on: "dz setup", "install skills", "benchmark skill", "which preset", "dz recommend".
+trust_tier: 0
+trust_tier_label: "Reference"
+---
+
+${generateDriverInstructions()}
+`;
+}
+
+/**
+ * Write the driver docs non-destructively. New files are created; an existing
+ * CLAUDE.md/AGENTS.md gets a marked section appended only if not already present.
+ * Returns a short detail string for the setup step.
+ */
+function installDriverDocs(projectRoot: string, force: boolean): string {
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  // 1. The loadable skill (own directory — always safe to write/refresh)
+  const skillDir = join(projectRoot, '.claude', 'skills', 'dz-harness-driver');
+  const skillPath = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillPath) || force) {
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(skillPath, generateDriverSkill());
+    written.push('skill');
+  } else {
+    skipped.push('skill');
+  }
+
+  // 2. Standalone agent docs — create only if absent (never clobber the user's).
+  const instructions = generateDriverInstructions();
+  for (const name of ['AGENTS.md', 'GEMINI.md']) {
+    const p = join(projectRoot, name);
+    if (!existsSync(p)) {
+      writeFileSync(p, instructions);
+      written.push(name);
+    } else {
+      skipped.push(name);
+    }
+  }
+
+  // 3. CLAUDE.md — append a marked block if the file lacks one (additive, idempotent).
+  const claudePath = join(projectRoot, 'CLAUDE.md');
+  const block = `\n${DRIVER_MARKER_START}\n\n${instructions}\n${DRIVER_MARKER_END}\n`;
+  if (!existsSync(claudePath)) {
+    writeFileSync(claudePath, block.trimStart());
+    written.push('CLAUDE.md');
+  } else {
+    const existing = readFileSync(claudePath, 'utf-8');
+    if (!existing.includes(DRIVER_MARKER_START)) {
+      writeFileSync(claudePath, existing + block);
+      written.push('CLAUDE.md(appended)');
+    } else {
+      skipped.push('CLAUDE.md');
+    }
+  }
+
+  const parts: string[] = [];
+  if (written.length) parts.push(`wrote ${written.join(', ')}`);
+  if (skipped.length) parts.push(`skipped ${skipped.join(', ')}`);
+  return parts.join('; ') || 'no changes';
+}
+
 export function runSetup(opts: SetupOptions): SetupResult {
   const steps: SetupStep[] = [];
   const dzDir = join(opts.projectRoot, '.dz');
@@ -268,6 +389,12 @@ export function runSetup(opts: SetupOptions): SetupResult {
     steps.push({ name: 'Create .gitignore', status: 'done', detail: 'with .dz entries' });
   }
 
+  // Step 7: Install the CLI-driver skill + agent docs (--install-driver)
+  if (opts.installDriver) {
+    const detail = installDriverDocs(opts.projectRoot, opts.force ?? false);
+    steps.push({ name: 'Install driver skill', status: 'done', detail });
+  }
+
   return {
     steps,
     totalSteps: steps.length,

package/src/sync-upstream.ts

@@ -57,7 +57,11 @@ export function loadSourcesManifest(packageDir: string): SourcesManifest | undef
   const sourcesPath = join(packageDir, 'sources.json');
   if (!existsSync(sourcesPath)) return undefined;
   const raw = readFileSync(sourcesPath, 'utf-8');
-  return JSON.parse(raw) as SourcesManifest;
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  // Only return if it has the expected origin + skills structure
+  if (!parsed.origin || typeof parsed.origin !== 'object') return undefined;
+  if (!parsed.skills || typeof parsed.skills !== 'object') return undefined;
+  return parsed as unknown as SourcesManifest;
 }
 
 /** Info about a package with external sources. */