nymor 1.0.1

package/src/commands/doctor.ts

@@ -0,0 +1,253 @@
+import path from "path";
+import fs from "fs-extra";
+import { glob } from "glob";
+import yaml from "yaml";
+import { AGENT_TARGETS, AgentTarget } from "../agents/targets";
+import { planCompileOutputs } from "./compile";
+import { NymorManifest } from "../utils/manifest";
+import { getManifestPath, getSkillsDir } from "../utils/paths";
+import { listSkillDirectories } from "../utils/skills";
+
+const VALID_AGENTS: AgentTarget[] = AGENT_TARGETS.map((target) => target.id);
+
+interface CheckResult {
+  ok: boolean;
+  label: string;
+  filePath: string;
+  message: string;
+  warn?: boolean;
+}
+
+interface ParsedSkillFrontmatter {
+  id: string;
+  filePath: string;
+  name: string;
+  globs: string[];
+  alwaysApply: boolean;
+  valid: boolean;
+}
+
+export async function doctorCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const results: CheckResult[] = [];
+
+  await checkManifest(projectRoot, results);
+  const frontmatters = await checkSkillFrontmatter(projectRoot, results);
+  await checkGlobExistence(projectRoot, frontmatters, results);
+  checkDuplicateNames(projectRoot, frontmatters, results);
+  await checkCompiledOutput(projectRoot, results);
+
+  for (const result of results) {
+    const status = result.warn ? "WARN" : result.ok ? "PASS" : "FAIL";
+    console.log(`${status} ${result.label} - ${result.filePath}${result.message ? ` - ${result.message}` : ""}`);
+  }
+
+  if (results.some((result) => !result.ok && !result.warn)) {
+    process.exitCode = 1;
+  }
+}
+
+async function checkManifest(projectRoot: string, results: CheckResult[]): Promise<NymorManifest | null> {
+  const manifestPath = getManifestPath(projectRoot);
+
+  try {
+    const manifest = (await fs.readJson(manifestPath)) as NymorManifest;
+    const errors: string[] = [];
+
+    if (manifest.version !== "1") {
+      errors.push('version must be "1"');
+    }
+
+    const invalidAgents = (manifest.agents ?? []).filter((agent) => !VALID_AGENTS.includes(agent));
+    if (invalidAgents.length > 0) {
+      errors.push(`invalid agents: ${invalidAgents.join(", ")}`);
+    }
+
+    results.push({
+      ok: errors.length === 0,
+      label: "Manifest sanity",
+      filePath: manifestPath,
+      message: errors.join("; ")
+    });
+
+    return errors.length === 0 ? normalizeManifest(manifest) : null;
+  } catch (err) {
+    results.push({
+      ok: false,
+      label: "Manifest sanity",
+      filePath: manifestPath,
+      message: err instanceof Error ? err.message : String(err)
+    });
+    return null;
+  }
+}
+
+async function checkSkillFrontmatter(projectRoot: string, results: CheckResult[]): Promise<ParsedSkillFrontmatter[]> {
+  const skillsDir = getSkillsDir(projectRoot);
+  const skillDirs = await listSkillDirectories(skillsDir);
+  const parsed: ParsedSkillFrontmatter[] = [];
+
+  for (const id of skillDirs) {
+    const skillPath = path.join(skillsDir, id, "SKILL.md");
+    const errors: string[] = [];
+    let frontmatter: Record<string, unknown> = {};
+
+    if (!(await fs.pathExists(skillPath))) {
+      errors.push("missing SKILL.md");
+    } else {
+      try {
+        frontmatter = parseFrontmatter(await fs.readFile(skillPath, "utf8"));
+      } catch (err) {
+        errors.push(err instanceof Error ? err.message : String(err));
+      }
+    }
+
+    if (!frontmatter.name) {
+      errors.push("missing name");
+    }
+    if (frontmatter.globs !== undefined && !Array.isArray(frontmatter.globs)) {
+      errors.push("globs must be an array");
+    }
+
+    const isValid = errors.length === 0;
+    results.push({
+      ok: isValid,
+      label: "Frontmatter validity",
+      filePath: skillPath,
+      message: errors.join("; ")
+    });
+
+    parsed.push({
+      id,
+      filePath: skillPath,
+      name: typeof frontmatter.name === "string" ? frontmatter.name : "",
+      globs: Array.isArray(frontmatter.globs) ? frontmatter.globs.map(String) : [],
+      alwaysApply: Boolean(frontmatter.alwaysApply),
+      valid: isValid
+    });
+  }
+
+  return parsed;
+}
+
+async function checkGlobExistence(
+  projectRoot: string,
+  frontmatters: ParsedSkillFrontmatter[],
+  results: CheckResult[]
+): Promise<void> {
+  for (const skill of frontmatters) {
+    if (!skill.valid || skill.alwaysApply || skill.globs.length === 0) {
+      continue;
+    }
+
+    const missing: string[] = [];
+    for (const pattern of skill.globs) {
+      const matches = await glob(pattern, {
+        cwd: projectRoot,
+        nodir: true,
+        dot: true,
+        ignore: ["**/node_modules/**", "**/.git/**", "**/.nymor/**"]
+      });
+      if (matches.length === 0) {
+        missing.push(pattern);
+      }
+    }
+
+    results.push({
+      ok: missing.length === 0,
+      label: "Glob existence",
+      filePath: skill.filePath,
+      message: missing.length > 0 ? `no matches: ${missing.join(", ")}` : ""
+    });
+  }
+}
+
+function checkDuplicateNames(
+  projectRoot: string,
+  frontmatters: ParsedSkillFrontmatter[],
+  results: CheckResult[]
+): void {
+  const seen = new Map<string, ParsedSkillFrontmatter>();
+
+  for (const skill of frontmatters.filter((item) => item.valid)) {
+    const previous = seen.get(skill.name);
+    if (previous) {
+      results.push({
+        ok: false,
+        label: "Duplicate names",
+        filePath: skill.filePath,
+        message: `duplicates ${previous.filePath}`
+      });
+    } else {
+      seen.set(skill.name, skill);
+    }
+  }
+
+  if (![...seen.values()].some((skill) => hasDuplicate(skill.name, frontmatters))) {
+    results.push({
+      ok: true,
+      label: "Duplicate names",
+      filePath: getSkillsDir(projectRoot),
+      message: ""
+    });
+  }
+}
+
+async function checkCompiledOutput(projectRoot: string, results: CheckResult[]): Promise<void> {
+  try {
+    const planned = await planCompileOutputs(projectRoot);
+    const stale: string[] = [];
+
+    for (const file of planned) {
+      if (!(await fs.pathExists(file.path))) {
+        stale.push(file.path);
+        continue;
+      }
+
+      const actual = await fs.readFile(file.path);
+      if (!actual.equals(file.content)) {
+        stale.push(file.path);
+      }
+    }
+
+    results.push({
+      ok: stale.length === 0,
+      label: "Compiled output staleness",
+      filePath: projectRoot,
+      message: stale.length > 0 ? "run `nymor compile`" : ""
+    });
+  } catch (err) {
+    results.push({
+      ok: false,
+      label: "Compiled output staleness",
+      filePath: projectRoot,
+      message: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+
+function parseFrontmatter(content: string): Record<string, unknown> {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") {
+    throw new Error("missing frontmatter");
+  }
+
+  const endIndex = lines.slice(1).findIndex((line) => line.trim() === "---");
+  if (endIndex === -1) {
+    throw new Error("frontmatter is not closed");
+  }
+
+  return (yaml.parse(lines.slice(1, endIndex + 1).join("\n")) ?? {}) as Record<string, unknown>;
+}
+
+function normalizeManifest(manifest: NymorManifest): NymorManifest {
+  return {
+    version: manifest.version,
+    agents: manifest.agents ?? [],
+    local: manifest.local ?? []
+  };
+}
+
+function hasDuplicate(name: string, frontmatters: ParsedSkillFrontmatter[]): boolean {
+  return frontmatters.filter((skill) => skill.valid && skill.name === name).length > 1;
+}

package/src/commands/init.ts

@@ -0,0 +1,113 @@
+import fs from "fs-extra";
+import inquirer from "inquirer";
+import { AGENT_TARGETS, AgentTarget, DEFAULT_AGENT_TARGETS } from "../agents/targets";
+import { compileCommand } from "./compile";
+import { detectAgents } from "../detector/agents";
+import { createDefaultManifest } from "../templates/nymor-json";
+import { NymorManifest, readManifest, writeManifest } from "../utils/manifest";
+import { getManifestPath, getNymorDir, getSkillsDir } from "../utils/paths";
+
+type InitMode = "new" | "update" | "reinit";
+
+const AGENT_CHOICES: Array<{ name: string; value: AgentTarget; short: string }> = AGENT_TARGETS.map((target) => ({
+  name: `${target.label} (${target.description})`,
+  value: target.id,
+  short: target.short
+}));
+
+export async function initCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const nymorDir = getNymorDir(projectRoot);
+  const skillsDir = getSkillsDir(projectRoot);
+
+  const mode = await resolveInitMode(nymorDir);
+  if (!mode) {
+    return;
+  }
+
+  if (mode === "reinit") {
+    await fs.remove(nymorDir);
+  }
+
+  const manifestPath = getManifestPath(projectRoot);
+  const existingManifest = (await fs.pathExists(manifestPath)) ? await readManifest(projectRoot) : null;
+  const manifest = createDefaultManifest() as NymorManifest;
+  manifest.agents = await selectAgentTargets(projectRoot, existingManifest?.agents);
+  manifest.local = mode === "reinit" ? [] : existingManifest?.local ?? [];
+  await writeManifest(projectRoot, manifest);
+
+  await fs.ensureDir(skillsDir);
+  await compileCommand();
+  printSummary(manifest.agents);
+}
+
+async function resolveInitMode(nymorDir: string): Promise<InitMode | null> {
+  if (!(await fs.pathExists(nymorDir))) {
+    return "new";
+  }
+
+  if (!process.stdin.isTTY) {
+    return "update";
+  }
+
+  const { action } = await inquirer.prompt<{ action: InitMode | "cancel" }>([
+    {
+      type: "list",
+      name: "action",
+      message: "Nymor already initialized. What do you want to do?",
+      choices: [
+        { name: "Update agent targets", value: "update" },
+        { name: "Reinitialize (overwrites .nymor/)", value: "reinit" },
+        { name: "Cancel", value: "cancel" }
+      ]
+    }
+  ]);
+
+  return action === "cancel" ? null : action;
+}
+
+async function selectAgentTargets(projectRoot: string, existingAgents?: AgentTarget[]): Promise<AgentTarget[]> {
+  const detectedAgents = await detectExistingAgentTargets(projectRoot);
+  const defaults = existingAgents && existingAgents.length > 0 ? existingAgents : detectedAgents;
+
+  if (!process.stdin.isTTY) {
+    return defaults.length > 0 ? defaults : [...DEFAULT_AGENT_TARGETS];
+  }
+
+  const { agents } = await inquirer.prompt<{ agents: AgentTarget[] }>([
+    {
+      type: "checkbox",
+      name: "agents",
+      message: "Which agent outputs should Nymor manage?",
+      choices: AGENT_CHOICES,
+      default: defaults.length > 0 ? defaults : DEFAULT_AGENT_TARGETS
+    }
+  ]);
+
+  return agents;
+}
+
+async function detectExistingAgentTargets(projectRoot: string): Promise<AgentTarget[]> {
+  const detected = await detectAgents(projectRoot);
+  return AGENT_TARGETS.filter((target) => detected[target.id]).map((target) => target.id);
+}
+
+function printSummary(agents: AgentTarget[]): void {
+  const checkMark = "\u2713";
+
+  console.log("");
+  console.log(`${checkMark} Nymor initialized`);
+  console.log("");
+  console.log("Skills directory: .nymor/skills/");
+  console.log("Index created:    .nymor/index.md");
+  console.log(`Agent outputs:    ${formatAgentSummary(agents)}`);
+}
+
+function formatAgentSummary(agents: AgentTarget[]): string {
+  if (agents.length === 0) {
+    return "none selected";
+  }
+
+  const labels = new Map<AgentTarget, string>(AGENT_CHOICES.map((choice) => [choice.value, choice.short]));
+  return agents.map((agent) => labels.get(agent) ?? agent).join(", ");
+}

package/src/commands/learn.ts

@@ -0,0 +1,175 @@
+import path from "path";
+import fs from "fs-extra";
+import inquirer from "inquirer";
+import type { DistinctQuestion } from "inquirer";
+import yaml from "yaml";
+import pc from "picocolors";
+import { compileCommand } from "./compile";
+import { readManifest, writeManifest } from "../utils/manifest";
+import { getSkillsDir } from "../utils/paths";
+
+interface LearnAnswers {
+  name: string;
+  description: string;
+  globs: string;
+  alwaysApply: boolean;
+  why: string;
+  example: string;
+}
+
+export interface LearnOptions {
+  id?: string;
+  name?: string;
+  description?: string;
+  globs?: string;
+  alwaysApply?: boolean;
+  why?: string;
+  example?: string;
+}
+
+export async function learnCommand(rule: string, options: LearnOptions = {}): Promise<void> {
+  const projectRoot = process.cwd();
+  const slug = slugifyRule(options.id ?? rule);
+  const skillDir = path.join(getSkillsDir(projectRoot), slug);
+  const skillPath = path.join(skillDir, "SKILL.md");
+
+  if (await fs.pathExists(skillPath)) {
+    throw new Error(`A local skill already exists at ${skillPath}`);
+  }
+
+  const answers = await promptForSkill(rule, slug, options);
+
+  const frontmatter = yaml.stringify({
+    name: answers.name,
+    description: answers.description,
+    globs: parseGlobs(answers.globs),
+    alwaysApply: answers.alwaysApply
+  });
+  const content = [
+    "---",
+    frontmatter.trimEnd(),
+    "---",
+    "",
+    `# Skill: ${answers.name}`,
+    "",
+    "## Rule",
+    rule,
+    "",
+    "## Why",
+    answers.why,
+    "",
+    "## Example",
+    answers.example,
+    ""
+  ].join("\n");
+
+  await fs.ensureDir(skillDir);
+  await fs.writeFile(skillPath, content, "utf8");
+
+  const manifest = await readManifest(projectRoot);
+  if (!manifest.local.includes(slug)) {
+    manifest.local.push(slug);
+  }
+  await writeManifest(projectRoot, manifest);
+
+  await compileCommand();
+
+  console.log("");
+  console.log(`${pc.green("✓")} Created local skill: ${skillPath}`);
+}
+
+export function slugifyRule(rule: string): string {
+  const slug = rule
+    .toLowerCase()
+    .replace(/['"]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50)
+    .replace(/-+$/g, "");
+
+  return slug || "new-skill";
+}
+
+function parseGlobs(value: string): string[] {
+  return value
+    .split(",")
+    .map((glob) => glob.trim())
+    .filter(Boolean);
+}
+
+function titleCase(value: string): string {
+  return value
+    .split("-")
+    .filter(Boolean)
+    .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
+    .join(" ");
+}
+
+async function promptForSkill(rule: string, slug: string, options: LearnOptions): Promise<LearnAnswers> {
+  const defaults: LearnAnswers = {
+    name: options.name ?? titleCase(slug),
+    description: options.description ?? rule,
+    globs: options.globs ?? "**/*",
+    alwaysApply: options.alwaysApply ?? false,
+    why: options.why ?? "TBD - describe why",
+    example: options.example ?? "TBD - add an example"
+  };
+
+  if (!process.stdin.isTTY) {
+    return defaults;
+  }
+
+  const questions: Array<DistinctQuestion<Partial<LearnAnswers>>> = [];
+
+  if (options.name === undefined) {
+    questions.push({
+      type: "input",
+      name: "name",
+      message: "Skill name",
+      default: defaults.name
+    });
+  }
+  if (options.description === undefined) {
+    questions.push({
+      type: "input",
+      name: "description",
+      message: "Description",
+      default: defaults.description
+    });
+  }
+  if (options.globs === undefined) {
+    questions.push({
+      type: "input",
+      name: "globs",
+      message: "Globs",
+      default: defaults.globs
+    });
+  }
+  if (options.alwaysApply === undefined) {
+    questions.push({
+      type: "confirm",
+      name: "alwaysApply",
+      message: "Always apply?",
+      default: defaults.alwaysApply
+    });
+  }
+  if (options.why === undefined) {
+    questions.push({
+      type: "input",
+      name: "why",
+      message: "Why",
+      default: defaults.why
+    });
+  }
+  if (options.example === undefined) {
+    questions.push({
+      type: "input",
+      name: "example",
+      message: "Example",
+      default: defaults.example
+    });
+  }
+
+  const answers = questions.length > 0 ? await inquirer.prompt<Partial<LearnAnswers>>(questions) : {};
+  return { ...defaults, ...answers };
+}

package/src/commands/list.ts

@@ -0,0 +1,57 @@
+import fs from "fs-extra";
+import { getIndexJsonPath, getSkillsDir } from "../utils/paths";
+import { loadSkills, SkillIndexEntry } from "../utils/skills";
+import { readManifest } from "../utils/manifest";
+
+export async function listCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const skillsDir = getSkillsDir(projectRoot);
+  const indexJsonPath = getIndexJsonPath(projectRoot);
+
+  if (!(await fs.pathExists(skillsDir))) {
+    console.log("No skills found. Run nymor init first.");
+    return;
+  }
+
+  let entries: SkillIndexEntry[] = [];
+
+  if (await fs.pathExists(indexJsonPath)) {
+    const index = await fs.readJson(indexJsonPath);
+    entries = Array.isArray(index.skills) ? index.skills : [];
+  } else {
+    const skills = await loadSkills(skillsDir);
+    entries = skills.map((skill) => ({
+      id: skill.id,
+      name: skill.frontmatter.name,
+      description: skill.frontmatter.description ?? "",
+      globs: skill.frontmatter.globs ?? [],
+      alwaysApply: Boolean(skill.frontmatter.alwaysApply)
+    }));
+  }
+
+  console.log(`Nymor Skills (${entries.length})`);
+  console.log("");
+
+  if (entries.length === 0) {
+    return;
+  }
+
+  const arrow = "\u2192";
+  const manifest = await readManifest(projectRoot);
+  const rows = entries.map((entry) => ({
+    entry,
+    source: manifest.local.includes(entry.id) ? "local" : "unknown"
+  }));
+  const skillWidth = Math.max("Skill".length, ...rows.map((row) => row.entry.id.length));
+  const sourceWidth = Math.max("Source".length, ...rows.map((row) => row.source.length));
+
+  console.log(`  ${"Skill".padEnd(skillWidth)}  ${"Source".padEnd(sourceWidth)}  Description`);
+  console.log(`  ${"-".repeat(skillWidth)}  ${"-".repeat(sourceWidth)}  -----------`);
+
+  rows.forEach(({ entry, source }) => {
+    const slug = entry.id.padEnd(skillWidth, " ");
+    const sourceColumn = source.padEnd(sourceWidth, " ");
+    const description = entry.description || entry.name || "(no description)";
+    console.log(`  ${slug}  ${sourceColumn}  ${arrow} ${description}`);
+  });
+}

package/src/commands/validate.ts

@@ -0,0 +1,89 @@
+import path from "path";
+import fs from "fs-extra";
+import { getIndexJsonPath, getSkillsDir } from "../utils/paths";
+import { listSkillDirectories, parseSkillContent } from "../utils/skills";
+
+export async function validateCommand(): Promise<void> {
+  const projectRoot = process.cwd();
+  const skillsDir = getSkillsDir(projectRoot);
+  const indexJsonPath = getIndexJsonPath(projectRoot);
+
+  if (!(await fs.pathExists(skillsDir))) {
+    console.log("No skills found. Run nymor init first.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const indexExists = await fs.pathExists(indexJsonPath);
+  const indexEntries = indexExists ? await fs.readJson(indexJsonPath) : { skills: [] };
+  const indexIds = new Set(
+    Array.isArray(indexEntries.skills) ? indexEntries.skills.map((entry: { id: string }) => entry.id) : []
+  );
+
+  const skillDirs = await listSkillDirectories(skillsDir);
+
+  console.log("Validating skills...\n");
+
+  let errorCount = 0;
+  const okMark = "\u2713";
+  const errMark = "\u2717";
+
+  for (const dirName of skillDirs) {
+    const skillPath = path.join(skillsDir, dirName, "SKILL.md");
+    const errors: string[] = [];
+
+    if (!(await fs.pathExists(skillPath))) {
+      errors.push("missing SKILL.md");
+    } else {
+      const content = await fs.readFile(skillPath, "utf8");
+      try {
+        const { frontmatter, body } = parseSkillContent(content, dirName);
+
+        if (!frontmatter.name) {
+          errors.push("missing frontmatter name");
+        }
+
+        if (!hasSection(body, "Rule")) {
+          errors.push("missing ## Rule section");
+        }
+        if (!hasSection(body, "Why")) {
+          errors.push("missing ## Why section");
+        }
+        if (!hasSection(body, "Example")) {
+          errors.push("missing ## Example section");
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(message);
+      }
+    }
+
+    if (indexExists && !indexIds.has(dirName)) {
+      errors.push("not found in index.json");
+    }
+
+    if (errors.length === 0) {
+      console.log(`  ${okMark} ${dirName}`);
+    } else {
+      errorCount += 1;
+      console.log(`  ${errMark} ${dirName} - ${errors.join("; ")}`);
+    }
+  }
+
+  if (!indexExists) {
+    errorCount += 1;
+    console.log("\nIndex not found. Run nymor compile to regenerate index.json.");
+  }
+
+  if (errorCount > 0) {
+    console.log(`\n${errorCount} issues found. Fix them or run nymor compile again.`);
+    process.exitCode = 1;
+  } else {
+    console.log("\nAll skills look good.");
+  }
+}
+
+function hasSection(content: string, heading: string): boolean {
+  const regex = new RegExp(`^##\\s+${heading}\\b`, "m");
+  return regex.test(content);
+}