nymor 1.0.1

package/src/compiler/block.ts

@@ -0,0 +1,26 @@
+const BLOCK_START = "<!-- nymor:start -->";
+const BLOCK_END = "<!-- nymor:end -->";
+
+export function renderManagedBlock(content: string): string {
+  const body = content.trimEnd();
+  return `${BLOCK_START}\n${body}\n${BLOCK_END}`;
+}
+
+export function upsertManagedBlock(existing: string | null, content: string): string {
+  const block = renderManagedBlock(content);
+  if (!existing) {
+    return `${block}\n`;
+  }
+
+  const pattern = new RegExp(`${escapeRegExp(BLOCK_START)}[\\s\\S]*?${escapeRegExp(BLOCK_END)}`);
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, block);
+  }
+
+  const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${separator}${block}\n`;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&");
+}

package/src/compiler/claude.ts

@@ -0,0 +1,13 @@
+import fs from "fs-extra";
+import path from "path";
+import { SkillFile } from "../utils/skills";
+
+export async function compileClaudeSkills(skills: SkillFile[], projectRoot: string): Promise<void> {
+  const outputRoot = path.join(projectRoot, ".claude", "skills");
+  await fs.ensureDir(outputRoot);
+
+  for (const skill of skills) {
+    const targetDir = path.join(outputRoot, skill.id);
+    await fs.copy(skill.dirPath, targetDir, { overwrite: true });
+  }
+}

package/src/compiler/copilot.ts

@@ -0,0 +1,28 @@
+import fs from "fs-extra";
+import path from "path";
+import { SkillFile } from "../utils/skills";
+
+export async function compileCopilotSkills(skills: SkillFile[], projectRoot: string): Promise<void> {
+  const outputRoot = path.join(projectRoot, ".github", "instructions");
+  await fs.ensureDir(outputRoot);
+
+  for (const skill of skills) {
+    const fileName = `nymor-${skill.id}.instructions.md`;
+    const outputPath = path.join(outputRoot, fileName);
+    const content = renderCopilotInstructions(skill);
+    await fs.writeFile(outputPath, content, "utf8");
+  }
+}
+
+export function renderCopilotInstructions(skill: SkillFile): string {
+  const globs = skill.frontmatter.globs ?? [];
+  const applyTo = globs.length > 0 ? globs.join(", ") : "**/*";
+  const lines = ["---", `applyTo: ${formatYamlValue(applyTo)}`, "---", ""];
+
+  return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}
+
+function formatYamlValue(value: string): string {
+  const escaped = value.replace(/"/g, "\\\"");
+  return `"${escaped}"`;
+}

package/src/compiler/cursor.ts

@@ -0,0 +1,38 @@
+import fs from "fs-extra";
+import path from "path";
+import { SkillFile } from "../utils/skills";
+
+export async function compileCursorSkills(skills: SkillFile[], projectRoot: string): Promise<void> {
+  const outputRoot = path.join(projectRoot, ".cursor", "rules");
+  await fs.ensureDir(outputRoot);
+
+  for (const skill of skills) {
+    const fileName = `nymor-${skill.id}.mdc`;
+    const outputPath = path.join(outputRoot, fileName);
+    const content = renderCursorRule(skill);
+    await fs.writeFile(outputPath, content, "utf8");
+  }
+}
+
+export function renderCursorRule(skill: SkillFile): string {
+  const description = skill.frontmatter.description || skill.frontmatter.name;
+  const globs = skill.frontmatter.globs ?? [];
+  const alwaysApply = Boolean(skill.frontmatter.alwaysApply);
+  const lines: string[] = ["---", `description: ${formatYamlValue(description)}`];
+
+  if (globs.length > 0) {
+    lines.push("globs:");
+    globs.forEach((glob) => lines.push(`  - ${formatYamlValue(glob)}`));
+  } else {
+    lines.push("globs: []");
+  }
+
+  lines.push(`alwaysApply: ${alwaysApply}`, "---", "");
+
+  return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}
+
+function formatYamlValue(value: string): string {
+  const escaped = value.replace(/"/g, "\\\"");
+  return `"${escaped}"`;
+}

package/src/compiler/kiro.ts

@@ -0,0 +1,22 @@
+import fs from "fs-extra";
+import path from "path";
+import { SkillFile } from "../utils/skills";
+
+export async function compileKiroSkills(skills: SkillFile[], projectRoot: string): Promise<void> {
+  const outputRoot = path.join(projectRoot, ".kiro", "steering");
+  await fs.ensureDir(outputRoot);
+
+  for (const skill of skills) {
+    const fileName = `nymor-${skill.id}.md`;
+    const outputPath = path.join(outputRoot, fileName);
+    const content = renderKiroSteering(skill);
+    await fs.writeFile(outputPath, content, "utf8");
+  }
+}
+
+export function renderKiroSteering(skill: SkillFile): string {
+  const inclusion = skill.frontmatter.alwaysApply ? "always" : "manual";
+  const lines = ["---", `inclusion: ${inclusion}`, "---", ""];
+
+  return `${lines.join("\n")}\n${skill.body.trimStart()}\n`;
+}

package/src/detector/agents.ts

@@ -0,0 +1,26 @@
+import path from "path";
+import fs from "fs-extra";
+import { AGENT_TARGETS, AgentTarget } from "../agents/targets";
+
+export type AgentPresence = Record<AgentTarget, boolean>;
+
+export async function detectAgents(projectRoot: string): Promise<AgentPresence> {
+  const entries = await Promise.all(
+    AGENT_TARGETS.map(async (target) => {
+      const detected = await hasAnyPath(projectRoot, target.detectPaths);
+      return [target.id, detected] as const;
+    })
+  );
+
+  return Object.fromEntries(entries) as AgentPresence;
+}
+
+async function hasAnyPath(projectRoot: string, relativePaths: string[]): Promise<boolean> {
+  for (const relativePath of relativePaths) {
+    if (await fs.pathExists(path.join(projectRoot, relativePath))) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/detector/stack.ts

@@ -0,0 +1,135 @@
+import fs from "fs-extra";
+import path from "path";
+import { glob } from "glob";
+
+export type Stack = "nodejs" | "react" | "vue" | "fullstack" | "python" | "django" | "fastapi" | "rust" | "go";
+
+const NODE_DEPENDENCIES = new Set(["express", "fastify", "koa", "hapi", "@nestjs/core"]);
+const REACT_DEPENDENCIES = new Set(["react", "next", "@remix-run/react"]);
+const VUE_DEPENDENCIES = new Set(["vue", "nuxt", "@nuxt/schema"]);
+const FULLSTACK_DEPENDENCIES = new Set(["next", "@remix-run/react"]);
+
+const SIGNALS: Record<Stack, string[]> = {
+  nodejs: ["server.js", "server.ts", "src/server.ts", "src/server.js"],
+  react: ["src/App.tsx", "src/App.jsx", "next.config.js", "next.config.ts"],
+  vue: ["vue.config.js", "nuxt.config.js", "nuxt.config.ts", "vite.config.ts"],
+  fullstack: ["next.config.js", "next.config.ts", "remix.config.js"],
+  python: ["requirements.txt", "pyproject.toml", "setup.py"],
+  django: ["manage.py"],
+  fastapi: ["main.py", "app/main.py"],
+  rust: ["Cargo.toml"],
+  go: ["go.mod"]
+};
+
+export async function detectStack(projectRoot: string): Promise<Stack | null> {
+  const packageDependencies = await readPackageDependencies(projectRoot);
+  const pythonManifest = await readPythonManifest(projectRoot);
+  const detected = new Set<Stack>();
+
+  if (hasAnyDependency(packageDependencies, FULLSTACK_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.fullstack))) {
+    detected.add("fullstack");
+  }
+
+  if (hasAnyDependency(packageDependencies, REACT_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.react))) {
+    detected.add("react");
+  }
+
+  if (hasAnyDependency(packageDependencies, VUE_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.vue))) {
+    detected.add("vue");
+  }
+
+  if (hasAnyDependency(packageDependencies, NODE_DEPENDENCIES) || (await hasAnySignal(projectRoot, SIGNALS.nodejs))) {
+    detected.add("nodejs");
+  }
+
+  if ((await hasAnySignal(projectRoot, SIGNALS.django)) && hasPythonDependency(pythonManifest, "django")) {
+    detected.add("django");
+  }
+
+  if (hasPythonDependency(pythonManifest, "fastapi") || (await hasAnySignal(projectRoot, SIGNALS.fastapi))) {
+    detected.add("fastapi");
+  }
+
+  if (pythonManifest || (await hasAnySignal(projectRoot, SIGNALS.python))) {
+    detected.add("python");
+  }
+
+  if (await hasAnySignal(projectRoot, SIGNALS.rust)) {
+    detected.add("rust");
+  }
+
+  if (await hasAnySignal(projectRoot, SIGNALS.go)) {
+    detected.add("go");
+  }
+
+  if (detected.has("django") || detected.has("fastapi")) {
+    detected.delete("python");
+  }
+
+  if (detected.size === 0) {
+    return null;
+  }
+
+  if (detected.has("fullstack") || detected.size > 1) {
+    return "fullstack";
+  }
+
+  return [...detected][0];
+}
+
+async function readPackageDependencies(projectRoot: string): Promise<Set<string>> {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!(await fs.pathExists(packageJsonPath))) {
+    return new Set();
+  }
+
+  try {
+    const pkg = await fs.readJson(packageJsonPath);
+    return new Set(Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }));
+  } catch {
+    return new Set();
+  }
+}
+
+async function readPythonManifest(projectRoot: string): Promise<string | null> {
+  const files = ["requirements.txt", "pyproject.toml", "setup.py"];
+  const contents: string[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(projectRoot, file);
+    if (await fs.pathExists(filePath)) {
+      contents.push(await fs.readFile(filePath, "utf8"));
+    }
+  }
+
+  return contents.length > 0 ? contents.join("\n").toLowerCase() : null;
+}
+
+function hasAnyDependency(actual: Set<string>, expected: Set<string>): boolean {
+  return [...expected].some((dependency) => actual.has(dependency));
+}
+
+function hasPythonDependency(manifest: string | null, dependency: string): boolean {
+  if (!manifest) {
+    return false;
+  }
+
+  return new RegExp(`(^|[^a-z0-9_-])${dependency}([^a-z0-9_-]|$)`, "i").test(manifest);
+}
+
+async function hasAnySignal(projectRoot: string, patterns: string[]): Promise<boolean> {
+  for (const pattern of patterns) {
+    const matches = await glob(pattern, {
+      cwd: projectRoot,
+      nodir: true,
+      dot: true,
+      ignore: ["**/node_modules/**", "**/.git/**"]
+    });
+
+    if (matches.length > 0) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { initCommand } from "./commands/init";
+import { compileCommand } from "./commands/compile";
+import { learnCommand } from "./commands/learn";
+import { listCommand } from "./commands/list";
+import { doctorCommand } from "./commands/doctor";
+import { validateCommand } from "./commands/validate";
+
+const program = new Command();
+
+program
+  .name("nymor")
+  .description("Teach your repo what your AI agents keep forgetting")
+  .version("2.0.0");
+
+program
+  .command("init")
+  .description("Initialize Nymor in the current repo")
+  .action(() => initCommand());
+
+program
+  .command("compile")
+  .description("Compile skills to agent surfaces")
+  .action(() => compileCommand());
+
+program
+  .command("learn", { hidden: true })
+  .argument("<rule>", "One-line rule or convention to capture")
+  .option("--id <id>", "Local skill folder id")
+  .option("--name <name>", "Skill name")
+  .option("--description <description>", "Skill description")
+  .option("--globs <globs>", "Comma-separated file globs")
+  .option("--always-apply", "Apply the skill regardless of globs")
+  .option("--why <why>", "Why this rule matters")
+  .option("--example <example>", "Example or counter-example")
+  .description("Internal fallback for capturing a project rule as a local skill")
+  .action((rule, options) => learnCommand(rule, options));
+
+program
+  .command("list")
+  .description("List active repo skills")
+  .action(() => listCommand());
+
+program
+  .command("doctor")
+  .description("Check skills for common issues")
+  .action(() => doctorCommand());
+
+program
+  .command("validate")
+  .description("Validate skill file format and index entries")
+  .action(() => validateCommand());
+
+program.parseAsync(process.argv).catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  process.exitCode = 1;
+});

package/src/templates/bootstrap.ts

@@ -0,0 +1,109 @@
+import { AgentTargetDefinition } from "../agents/targets";
+import { SkillFile } from "../utils/skills";
+
+const LEARN_TRIGGER = "/nymor-learn";
+
+function getLearnArgumentsPlaceholder(target: AgentTargetDefinition): string {
+  return target.id === "copilot" ? "{{input}}" : "$ARGUMENTS";
+}
+
+export function renderBootstrap(target: AgentTargetDefinition, skills: SkillFile[] = [], wrap = true): string {
+  const body = [
+    "# Nymor",
+    "",
+    "Nymor teaches this repo what AI agents keep forgetting.",
+    "",
+    "Source skills live in `.nymor/skills/`. Apply any matching skill during the task, using `globs` and `alwaysApply` to decide relevance.",
+    "",
+    "If the user states a durable repo rule, says things like \"always\", \"never\", \"in this repo\", \"we use\", \"remember this\", or corrects the same behavior more than once, gently suggest:",
+    "",
+    "`This looks like a reusable repo rule. Want me to capture it with /nymor-learn?`",
+    "",
+    `Only create a skill after the user explicitly invokes ${LEARN_TRIGGER}.`,
+    "",
+    `When the user invokes ${LEARN_TRIGGER} "<rule>":`,
+    "",
+    "1. Infer the durable rule from the conversation.",
+    "2. Choose a stable lowercase folder id with hyphens.",
+    "3. Read `nymor.json` and `.nymor/skills/`.",
+    "4. Write `.nymor/skills/<id>/SKILL.md` directly.",
+    "5. Include complete frontmatter: `name`, `description`, `globs`, and `alwaysApply`.",
+    "6. Include complete sections: `## Rule`, `## Why`, and `## Example`.",
+    "7. Keep `globs` narrow unless the rule is genuinely global.",
+    "8. Add `<id>` to `nymor.json.local` if missing.",
+    "9. Run `nymor compile`.",
+    "10. Run `nymor validate`.",
+    "11. Report the captured rule and skill path.",
+    "",
+    "Never create placeholders. Write directly to the active skill path. Create only the requested skill; do not seed unrelated skills or use external installs.",
+    "",
+    renderAlwaysApplySection(skills)
+  ].join("\n");
+
+  return wrap ? wrapBootstrap(target, body) : body;
+}
+
+export function renderLearnCommand(target: AgentTargetDefinition): string {
+  const inputPlaceholder = getLearnArgumentsPlaceholder(target);
+
+  return [
+    "---",
+    "description: Capture a durable repo rule as a Nymor skill.",
+    "---",
+    "",
+    `# ${target.label} Nymor Learn`,
+    "",
+    "User input:",
+    "",
+    "```text",
+    inputPlaceholder,
+    "```",
+    "",
+    renderBootstrap(target, [], false)
+  ].join("\n");
+}
+
+export function renderLearnSkill(target: AgentTargetDefinition): string {
+  return [
+    "---",
+    "name: Nymor Learn",
+    "description: Capture durable repo rules as active Nymor skills.",
+    "globs:",
+    "  - \"**/*\"",
+    "alwaysApply: true",
+    "---",
+    "",
+    renderBootstrap(target, [], false)
+  ].join("\n");
+}
+
+function wrapBootstrap(target: AgentTargetDefinition, body: string): string {
+  if (target.id === "cursor") {
+    return ["---", "description: Nymor repo-memory capture and skill guidance.", "globs:", "  - \"**/*\"", "alwaysApply: true", "---", "", body].join(
+      "\n"
+    );
+  }
+
+  if (target.id === "copilot") {
+    return ["---", "applyTo: \"**/*\"", "---", "", body].join("\n");
+  }
+
+  if (target.id === "kiro") {
+    return ["---", "inclusion: always", "---", "", body].join("\n");
+  }
+
+  return body;
+}
+
+function renderAlwaysApplySection(skills: SkillFile[]): string {
+  const alwaysApply = skills.filter((skill) => skill.frontmatter.alwaysApply);
+  if (alwaysApply.length === 0) {
+    return "No always-apply Nymor skills are currently configured.";
+  }
+
+  return [
+    "## Always-Apply Nymor Skills",
+    "",
+    ...alwaysApply.map((skill) => [`### ${skill.frontmatter.name}`, "", skill.body.trim()].join("\n")).join("\n\n---\n\n").split("\n")
+  ].join("\n");
+}

package/src/templates/nymor-json.ts

@@ -0,0 +1,15 @@
+import { DEFAULT_AGENT_TARGETS } from "../agents/targets";
+
+export interface NymorManifestTemplate {
+  version: string;
+  agents: string[];
+  local: string[];
+}
+
+export function createDefaultManifest(): NymorManifestTemplate {
+  return {
+    version: "1",
+    agents: [...DEFAULT_AGENT_TARGETS],
+    local: []
+  };
+}

package/src/utils/manifest.ts

@@ -0,0 +1,38 @@
+import fs from "fs-extra";
+import { AgentTarget, isAgentTarget } from "../agents/targets";
+import { createDefaultManifest } from "../templates/nymor-json";
+import { getManifestPath } from "./paths";
+
+export interface NymorManifest {
+  version: string;
+  agents: AgentTarget[];
+  local: string[];
+}
+
+export async function readManifest(projectRoot: string): Promise<NymorManifest> {
+  const manifestPath = getManifestPath(projectRoot);
+  if (!(await fs.pathExists(manifestPath))) {
+    return createDefaultManifest() as NymorManifest;
+  }
+
+  const manifest = await fs.readJson(manifestPath);
+  return normalizeManifest(manifest);
+}
+
+export async function writeManifest(projectRoot: string, manifest: NymorManifest): Promise<void> {
+  const manifestPath = getManifestPath(projectRoot);
+  await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+}
+
+function normalizeManifest(raw: Partial<NymorManifest>): NymorManifest {
+  const defaultManifest = createDefaultManifest();
+  const agents = (raw.agents ?? defaultManifest.agents).filter((agent): agent is AgentTarget =>
+    isAgentTarget(String(agent))
+  );
+
+  return {
+    version: raw.version ?? defaultManifest.version,
+    agents,
+    local: raw.local ?? []
+  };
+}

package/src/utils/paths.ts

@@ -0,0 +1,25 @@
+import path from "path";
+
+export function getRepoRoot(cwd: string = process.cwd()): string {
+  return cwd;
+}
+
+export function getNymorDir(root: string): string {
+  return path.join(root, ".nymor");
+}
+
+export function getSkillsDir(root: string): string {
+  return path.join(getNymorDir(root), "skills");
+}
+
+export function getIndexMarkdownPath(root: string): string {
+  return path.join(getNymorDir(root), "index.md");
+}
+
+export function getIndexJsonPath(root: string): string {
+  return path.join(getNymorDir(root), "index.json");
+}
+
+export function getManifestPath(root: string): string {
+  return path.join(root, "nymor.json");
+}