@dzhechkov/harness-core 0.4.4 → 0.5.0

package/src/skills.ts

@@ -75,7 +75,17 @@ export function discoverSkillIds(skillsDir: string): string[] {
     .sort();
 }
 
-/** Discover every skill in `skillsDir`, returning id + description. */
+/**
+ * Discover every skill in `skillsDir`, returning id + description.
+ *
+ * **Throws on the first unloadable skill — deliberately, and permanently.** This is a
+ * published export; silently turning it into a skip-and-collect function would downgrade
+ * every unknown third-party consumer from fail-closed to fail-silent without their
+ * consent (an incomplete catalogue reported as complete). Callers that want a partial
+ * listing ask for one by name: {@link listSkillsDetailed}. A pinned regression test
+ * asserts this function still throws, so a future "helpful" refactor cannot quietly
+ * erase the strict variant. (feature dz-cli-defects, ADR-001 as amended by AM-6.)
+ */
 export function listSkills(skillsDir: string): SkillSummary[] {
   return discoverSkillIds(skillsDir).map((id) => {
     const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
@@ -84,6 +94,169 @@ export function listSkills(skillsDir: string): SkillSummary[] {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Skip-and-collect (feature dz-cli-defects, D1)
+//
+// The parser (`@dzhechkov/core/src/skill-document.ts`) is handed only TEXT, so its
+// message can never carry a path. `describeSkillLoadFailure` is the ONE place that
+// turns a pathless throw into a named failure — every consumer calls it, so "named,
+// never anonymous" has one implementation and one test.
+// ---------------------------------------------------------------------------
+
+/** How much of the offending file's first line is echoed back to the user. */
+export const SKILL_FAILURE_FIRST_LINE_MAX = 100;
+
+/** One skill directory that could not be loaded. Named, so a log is actionable. */
+export interface SkillLoadFailure {
+  /** The skill id (its directory name), e.g. `bto`. */
+  readonly id: string;
+  /** ABSOLUTE path to the offending `SKILL.md`. */
+  readonly path: string;
+  /** The caught error's message, verbatim — the classifier stays out of the loader. */
+  readonly reason: string;
+  /**
+   * First line of the source text, trimmed and capped at
+   * {@link SKILL_FAILURE_FIRST_LINE_MAX}; `''` when the file is unreadable. Echoing it
+   * is what turns the message into a FIX — the user sees the H1 and knows to add the
+   * frontmatter fence.
+   */
+  readonly firstLine: string;
+}
+
+/** A listing that separates what parsed from what did not. */
+export interface SkillListing {
+  /** Sorted by id — same order, same shape as {@link listSkills} produces today. */
+  readonly skills: readonly SkillSummary[];
+  /** Sorted by id. Empty when every skill loaded. */
+  readonly failures: readonly SkillLoadFailure[];
+}
+
+/**
+ * Attribute any skill-load throw to a file. Shared by every consumer
+ * (`listSkillsDetailed`, `runInit`, `runInitSingleFileMd`, `runSync`).
+ *
+ * Best-effort on the first line: an unreadable file yields `''` rather than a second
+ * throw — this helper runs on an error path and must never become one.
+ */
+export function describeSkillLoadFailure(
+  skillsDir: string,
+  id: string,
+  error: unknown,
+): SkillLoadFailure {
+  const path = join(skillsDir, id, 'SKILL.md');
+  let firstLine = '';
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const line = (raw.split('\n', 1)[0] ?? '').replace(/\r$/, '').trim();
+    firstLine =
+      line.length > SKILL_FAILURE_FIRST_LINE_MAX
+        ? `${line.slice(0, SKILL_FAILURE_FIRST_LINE_MAX)}…`
+        : line;
+  } catch {
+    firstLine = '';
+  }
+  return {
+    id,
+    path,
+    reason: error instanceof Error ? error.message : String(error),
+    firstLine,
+  };
+}
+
+/**
+ * Discover every skill in `skillsDir`, separating the ones that parsed from the ones
+ * that did not. One broken `SKILL.md` never hides the rest.
+ *
+ * Catch policy: **every** error per id, not only `SkillDocumentError` — an `EACCES`, a
+ * YAML syntax error and a Zod schema rejection are all equally "this one skill is
+ * unusable". The `reason` is the caught message verbatim.
+ */
+export function listSkillsDetailed(skillsDir: string): SkillListing {
+  const skills: SkillSummary[] = [];
+  const failures: SkillLoadFailure[] = [];
+  for (const id of discoverSkillIds(skillsDir)) {
+    try {
+      const document = parseSkillDocument(readFileSync(join(skillsDir, id, 'SKILL.md'), 'utf-8'));
+      const frontmatter = ClaudeSkillFrontmatterSchema.parse(parseYaml(document.frontmatterYaml));
+      skills.push({ id, description: frontmatter.description });
+    } catch (error) {
+      failures.push(describeSkillLoadFailure(skillsDir, id, error));
+    }
+  }
+  return { skills, failures };
+}
+
+/**
+ * Render a `SkillLoadFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * One helper, two rendering modes, chosen by the CALLER — never by the helper sniffing
+ * the path. `dz list` / `dz sync` print absolute paths (the user can act on those);
+ * `dz install` passes `relativeTo` = the downloaded package root, because a
+ * `node_modules/**` absolute path is not something the user can act on.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export function formatSkillLoadFailures(
+  failures: readonly SkillLoadFailure[],
+  opts: { readonly relativeTo?: string } = {},
+): string[] {
+  if (failures.length === 0) return [];
+  const lines = [`⚠ ${failures.length} skill(s) skipped (unparseable SKILL.md):`];
+  for (const failure of failures) {
+    const shown =
+      opts.relativeTo !== undefined
+        ? relative(opts.relativeTo, failure.path).split('\\').join('/')
+        : failure.path;
+    lines.push(`  ${shown}`);
+    lines.push(`    ${failure.reason}`);
+    if (failure.firstLine !== '') lines.push(`    (line 1: ${JSON.stringify(failure.firstLine)})`);
+  }
+  return lines;
+}
+
+// ---------------------------------------------------------------------------
+// The SECOND failure kind (fix round 1, QE F4)
+//
+// A load failure and an APPLY failure are different accusations. The first says
+// "this SKILL.md is broken"; the second says "this skill is fine, the target could
+// not be written". Funnelling both through `describeSkillLoadFailure` produced a
+// message that contradicted its own body — an `EEXIST: mkdir …/.claude/skills/alpha`
+// rendered under the header "unparseable SKILL.md", quoting `line 1: "---"` (a VALID
+// fence) as its evidence and naming the innocent SOURCE file (MEASURED 2026-08-18).
+// Driver D2 ("every failure must name its subject") is worse than unmet when the
+// subject named is the wrong artifact.
+// ---------------------------------------------------------------------------
+
+/**
+ * One skill that LOADED cleanly but could not be compiled for, or written to, the
+ * target. The subject is the TARGET, never the source `SKILL.md`.
+ */
+export interface SkillApplyFailure {
+  /** The skill id (its directory name). */
+  readonly id: string;
+  /** The caught error's message, verbatim. */
+  readonly reason: string;
+}
+
+/**
+ * Render a `SkillApplyFailure[]` as the diagnostic block a CLI writes to **stderr**.
+ *
+ * Deliberately a DIFFERENT header from {@link formatSkillLoadFailures}: the two kinds
+ * point the user at two different files, and a shared header is what let a write
+ * failure masquerade as a parse failure.
+ *
+ * Returns `[]` for an empty input, so callers can splice it unconditionally.
+ */
+export function formatSkillApplyFailures(failures: readonly SkillApplyFailure[]): string[] {
+  if (failures.length === 0) return [];
+  const lines = [`✗ ${failures.length} skill(s) failed to install (compile/write error):`];
+  for (const failure of failures) {
+    lines.push(`  ${failure.id}`);
+    lines.push(`    ${failure.reason}`);
+  }
+  return lines;
+}
+
 /** 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);

package/src/targets.ts

@@ -48,3 +48,192 @@ export const TARGET_NAMES = Object.keys(TARGETS) as TargetName[];
 export function isTargetName(value: string): value is TargetName {
   return Object.prototype.hasOwnProperty.call(TARGETS, value);
 }
+
+// ---------------------------------------------------------------------------
+// `--target` resolution — alias table + did-you-mean (feature dz-cli-defects, D3)
+//
+// `isTargetName`, `TARGETS` and `TARGET_NAMES` above are UNCHANGED: `boundaries.json`
+// names `isTargetName` as the scanned validation boundary for `--target`, and every
+// resolution below ends in exactly that guard, so the security boundary is preserved
+// rather than relocated (ADR-002 / architecture §3.1).
+// ---------------------------------------------------------------------------
+
+/** `TARGET_NAMES` sorted alphabetically, for display in error messages. */
+export const TARGET_NAMES_SORTED: readonly TargetName[] = [...TARGET_NAMES].sort();
+
+/**
+ * Semantic `--target` aliases — DATA, not branching logic. Adding a row is one line
+ * and zero control flow (ADR-002 §Rationale D5).
+ *
+ * Purely typographic variants (`Claude_Code`, `claudecode`, `agents.md`) are handled by
+ * normalisation, not by rows; the rows below carry only meanings normalisation cannot
+ * derive (`claude` ≠ `claude-code` by any string rule — it is an owner decision).
+ */
+export const TARGET_ALIASES: Readonly<Record<string, TargetName>> = {
+  claude: 'claude-code',
+  cc: 'claude-code',
+  agents: 'agents-md',
+  gpt: 'codex',
+  openai: 'codex',
+};
+
+/**
+ * Rows deleted in fix round 1 (QE F7) because they were UNREACHABLE, not because their
+ * inputs stopped working: `claude_code`, `claudecode`, `agentsmd` and `agents.md` all
+ * normalise onto a canonical name, and precedence step 2 (normalised canonical) runs
+ * BEFORE step 3 (this table). Every one of them still resolves — through normalisation,
+ * which is where the README already says typographic variants are handled.
+ *
+ * They were invisible dead data because the table test iterated every row asserting
+ * `via === 'alias'`, which is true on both paths — a PRESENCE assertion where a
+ * REACHABILITY one was intended. `target-resolution.test.ts` now removes each row from a
+ * COPY of the table and asserts the resolution changes, so a future dead row is red.
+ */
+
+
+/** The outcome of {@link resolveTargetName}. Total: every string maps to one of these. */
+export type TargetResolution =
+  | { readonly kind: 'ok'; readonly target: TargetName; readonly via: 'canonical' | 'alias' }
+  | { readonly kind: 'unknown'; readonly input: string; readonly suggestion: TargetName | null };
+
+/** Levenshtein suggestions are only offered at or below this edit distance. */
+export const TARGET_SUGGESTION_MAX_DISTANCE = 3;
+
+/**
+ * Normalise a `--target` token for matching: byte-level lowercase (never
+ * `toLocaleLowerCase` — behaviour must not vary with the host locale), trimmed, with
+ * every separator dropped so `Claude_Code`, `claude-code` and `claudecode` collapse.
+ *
+ * Exported so the alias-REACHABILITY test can ask the production normaliser whether a
+ * proposed alias row is already carried by precedence step 2, instead of keeping a
+ * second copy of this rule in the test file (fix round 1, QE F7).
+ */
+export function normalizeTargetToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[-_.\s]/g, '');
+}
+
+/** Iterative two-row Levenshtein. No dependency: harness-core ships no fuzzy matcher. */
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev: number[] = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr: number[] = new Array<number>(b.length + 1).fill(0);
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min((curr[j - 1] ?? 0) + 1, (prev[j] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+    }
+    const swap = prev;
+    prev = curr;
+    curr = swap;
+  }
+  return prev[b.length] ?? 0;
+}
+
+/**
+ * Suggest a canonical target for an input that did not resolve.
+ *
+ * Two legs, in order, and each closes a case the other cannot:
+ *
+ * - **unique normalised prefix** — carries `clau → claude-code`, which is edit distance 5
+ *   and therefore unreachable by any sane Levenshtein threshold. An input that prefixes
+ *   TWO OR MORE canonical names is AMBIGUOUS and terminates with **no** suggestion
+ *   (`co` → `codex`/`copilot`): guessing between two live targets is worse than a
+ *   round-trip, and the fall-through would otherwise hand `co` to `codex` on a distance
+ *   of 3 — a confident answer to a question the user has not yet decided.
+ * - **Levenshtein ≤ 3, strictly better than the runner-up** — carries the typo case
+ *   `clade-code → claude-code`. A tie yields `null` for the same reason.
+ */
+function suggestTargetName(normalized: string): TargetName | null {
+  if (normalized.length === 0) return null;
+
+  const prefixHits = TARGET_NAMES_SORTED.filter((name) =>
+    normalizeTargetToken(name).startsWith(normalized),
+  );
+  if (prefixHits.length === 1) return prefixHits[0] ?? null;
+  // Ambiguous prefix is TERMINAL, not a fall-through (see doc comment).
+  if (prefixHits.length > 1) return null;
+
+  let best: TargetName | null = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  let runnerUpDistance = Number.POSITIVE_INFINITY;
+  for (const name of TARGET_NAMES_SORTED) {
+    const distance = levenshtein(normalized, normalizeTargetToken(name));
+    if (distance < bestDistance) {
+      runnerUpDistance = bestDistance;
+      bestDistance = distance;
+      best = name;
+    } else if (distance < runnerUpDistance) {
+      runnerUpDistance = distance;
+    }
+  }
+  if (best === null) return null;
+  if (bestDistance > TARGET_SUGGESTION_MAX_DISTANCE) return null;
+  // Strictly better than the runner-up — a tie is not a suggestion.
+  if (bestDistance === runnerUpDistance) return null;
+  return best;
+}
+
+/**
+ * Resolve a user-supplied `--target` value to a canonical {@link TargetName}.
+ *
+ * Total, pure, no I/O. Precedence (fixed and tested):
+ *
+ * 1. exact canonical hit → `{kind:'ok', via:'canonical'}` (`isTargetName` semantics);
+ * 2. normalised canonical hit → `{kind:'ok', via:'alias'}` (`Claude_Code`, `agentsmd`);
+ * 3. explicit {@link TARGET_ALIASES} row → `{kind:'ok', via:'alias'}`;
+ * 4. unique normalised prefix → `{kind:'unknown', suggestion}`;
+ * 5. Levenshtein ≤ 3 strictly better than the runner-up → `{kind:'unknown', suggestion}`;
+ * 6. otherwise → `{kind:'unknown', suggestion:null}`.
+ *
+ * **Aliases ACCEPT; prefix and Levenshtein only SUGGEST.** An alias row is an owner
+ * decision recorded in data; a fuzzy match is a guess, and silently installing to the
+ * wrong target on a guess is worse than one round-trip.
+ */
+export function resolveTargetName(value: string): TargetResolution {
+  if (isTargetName(value)) return { kind: 'ok', target: value, via: 'canonical' };
+
+  const normalized = normalizeTargetToken(value);
+  for (const name of TARGET_NAMES) {
+    if (normalizeTargetToken(name) === normalized) {
+      return { kind: 'ok', target: name, via: 'alias' };
+    }
+  }
+
+  const aliased =
+    Object.prototype.hasOwnProperty.call(TARGET_ALIASES, normalized)
+      ? TARGET_ALIASES[normalized]
+      : Object.prototype.hasOwnProperty.call(TARGET_ALIASES, value.trim().toLowerCase())
+        ? TARGET_ALIASES[value.trim().toLowerCase()]
+        : undefined;
+  if (aliased !== undefined) return { kind: 'ok', target: aliased, via: 'alias' };
+
+  return { kind: 'unknown', input: value, suggestion: suggestTargetName(normalized) };
+}
+
+/**
+ * Render the two-line failure for an unresolvable `--target`.
+ *
+ * Line 2 keeps the literal substring `--target must be one of:` — three shipped
+ * assertions (`test/cli.test.ts`) pin it, and keeping the shape additive is what makes
+ * the D3 change prove itself with NEW tests instead of rewriting old ones. The values
+ * are {@link TARGET_NAMES_SORTED} (alphabetical), which the pre-change message was not.
+ */
+export function formatTargetProblem(
+  command: string,
+  resolution: Extract<TargetResolution, { kind: 'unknown' }>,
+): readonly string[] {
+  const suggestion =
+    resolution.suggestion !== null ? ` — did you mean ${JSON.stringify(resolution.suggestion)}?` : '';
+  return [
+    `${command}: unknown --target ${JSON.stringify(resolution.input)}${suggestion}`,
+    `  --target must be one of: ${TARGET_NAMES_SORTED.join(', ')}`,
+  ];
+}
+
+/** The one-line diagnostic emitted (on stderr) when an alias was accepted. */
+export function formatTargetAliasNote(command: string, input: string, target: TargetName): string {
+  return `${command}: --target ${JSON.stringify(input)} → ${target} (alias)`;
+}