@vuau/agent-memory 0.1.0 → 0.2.0

package/README.md

@@ -82,9 +82,18 @@ npx @vuau/agent-memory init
 npx @vuau/agent-memory init --force          # Overwrite existing files
 npx @vuau/agent-memory init --name "My App"  # Custom project name
 npx @vuau/agent-memory init --no-copilot     # Skip copilot-instructions.md
+npx @vuau/agent-memory init --opencode       # Wire up OpenCode plugin
 npx @vuau/agent-memory doctor                # Validate structure
 ```
 
+#### `--opencode` flag
+
+Wires up the OpenCode plugin automatically:
+- Creates/updates `.opencode/package.json` with `@vuau/agent-memory` dependency
+- Creates/updates `opencode.json` with `"plugin": ["@vuau/agent-memory"]`
+
+After running, restart OpenCode to activate the plugin.
+
 ## How It Works
 
 ### For AI Agents

package/dist/bin/cli.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+// src/core/scaffold.ts
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// src/core/types.ts
+var AGENTS_DIR = ".agents";
+var SPEC_DIR = ".agents/spec";
+var MEMORY_FILE = ".agents/MEMORY.md";
+var TASKS_FILE = ".agents/TASKS.md";
+var AGENTS_MD = "AGENTS.md";
+var COPILOT_INSTRUCTIONS = ".github/copilot-instructions.md";
+
+// src/core/scaffold.ts
+function getTemplatesDir() {
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const candidate = resolve(thisDir, "../../templates");
+    if (existsSync(candidate)) return candidate;
+  } catch {
+  }
+  const candidate2 = resolve(__dirname, "../../templates");
+  if (existsSync(candidate2)) return candidate2;
+  throw new Error("Cannot locate templates directory");
+}
+var TEMPLATES_DIR = getTemplatesDir();
+function readTemplate(name) {
+  const templatePath = join(TEMPLATES_DIR, name);
+  return readFileSync(templatePath, "utf-8");
+}
+function applyVars(content, vars) {
+  let result = content;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}
+function scaffold(projectDir, config = {}, force = false) {
+  const result = { created: [], skipped: [] };
+  const projectName = config.projectName || guessProjectName(projectDir);
+  const vars = { PROJECT_NAME: projectName };
+  const dirs = [
+    join(projectDir, AGENTS_DIR),
+    join(projectDir, SPEC_DIR)
+  ];
+  if (config.copilotInstructions !== false) {
+    dirs.push(join(projectDir, ".github"));
+  }
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+  const files = [
+    { target: AGENTS_MD, template: "AGENTS.md" },
+    { target: MEMORY_FILE, template: "MEMORY.md" },
+    { target: TASKS_FILE, template: "TASKS.md" }
+  ];
+  if (config.copilotInstructions !== false) {
+    files.push({
+      target: COPILOT_INSTRUCTIONS,
+      template: "copilot-instructions.md"
+    });
+  }
+  for (const { target, template } of files) {
+    const targetPath = join(projectDir, target);
+    if (existsSync(targetPath) && !force) {
+      result.skipped.push(target);
+      continue;
+    }
+    const content = applyVars(readTemplate(template), vars);
+    writeFileSync(targetPath, content);
+    result.created.push(target);
+  }
+  const specKeep = join(projectDir, SPEC_DIR, ".gitkeep");
+  if (!existsSync(specKeep)) {
+    writeFileSync(specKeep, "");
+    result.created.push(`${SPEC_DIR}/.gitkeep`);
+  }
+  if (config.opencode) {
+    scaffoldOpenCode(projectDir, result, force);
+  }
+  return result;
+}
+function scaffoldOpenCode(projectDir, result, force) {
+  const PACKAGE_NAME = "@vuau/agent-memory";
+  const opencodePkgPath = join(projectDir, ".opencode", "package.json");
+  const opencodeDir = join(projectDir, ".opencode");
+  if (!existsSync(opencodeDir)) {
+    mkdirSync(opencodeDir, { recursive: true });
+  }
+  if (!existsSync(opencodePkgPath)) {
+    writeFileSync(
+      opencodePkgPath,
+      JSON.stringify({ dependencies: { [PACKAGE_NAME]: "latest" } }, null, 2) + "\n"
+    );
+    result.created.push(".opencode/package.json");
+  } else {
+    const pkg = JSON.parse(readFileSync(opencodePkgPath, "utf-8"));
+    const deps = pkg.dependencies || {};
+    if (!deps[PACKAGE_NAME] || force) {
+      deps[PACKAGE_NAME] = "latest";
+      pkg.dependencies = deps;
+      writeFileSync(opencodePkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      if (!deps[PACKAGE_NAME]) {
+        result.created.push(".opencode/package.json");
+      }
+    } else {
+      result.skipped.push(".opencode/package.json");
+    }
+  }
+  const opencodeJsonPath = join(projectDir, "opencode.json");
+  if (!existsSync(opencodeJsonPath)) {
+    writeFileSync(
+      opencodeJsonPath,
+      JSON.stringify({ plugin: [PACKAGE_NAME] }, null, 2) + "\n"
+    );
+    result.created.push("opencode.json");
+  } else {
+    const config = JSON.parse(readFileSync(opencodeJsonPath, "utf-8"));
+    const plugins = config.plugin || [];
+    if (!plugins.includes(PACKAGE_NAME)) {
+      config.plugin = [...plugins, PACKAGE_NAME];
+      writeFileSync(opencodeJsonPath, JSON.stringify(config, null, 2) + "\n");
+      result.created.push("opencode.json (merged plugin)");
+    } else {
+      result.skipped.push("opencode.json");
+    }
+  }
+}
+function guessProjectName(dir) {
+  const pkgPath = join(dir, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      if (pkg.name) return pkg.name;
+    } catch {
+    }
+  }
+  return dir.split("/").pop() || "Project";
+}
+
+// src/core/doctor.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+function doctor(projectDir) {
+  const issues = [];
+  const required = [
+    { file: AGENTS_MD, desc: "Root router file" },
+    { file: MEMORY_FILE, desc: "Long-term memory" },
+    { file: TASKS_FILE, desc: "Working memory" }
+  ];
+  for (const { file, desc } of required) {
+    const filePath = join2(projectDir, file);
+    if (!existsSync2(filePath)) {
+      issues.push({ level: "error", file, message: `Missing ${desc}` });
+    }
+  }
+  for (const dir of [AGENTS_DIR, SPEC_DIR]) {
+    if (!existsSync2(join2(projectDir, dir))) {
+      issues.push({ level: "error", file: dir, message: "Directory missing" });
+    }
+  }
+  const copilotPath = join2(projectDir, COPILOT_INSTRUCTIONS);
+  if (!existsSync2(copilotPath)) {
+    issues.push({
+      level: "warning",
+      file: COPILOT_INSTRUCTIONS,
+      message: "Copilot instructions missing \u2014 VSCode/GitHub Copilot won't have context"
+    });
+  }
+  const agentsPath = join2(projectDir, AGENTS_MD);
+  if (existsSync2(agentsPath)) {
+    const content = readFileSync2(agentsPath, "utf-8");
+    if (!content.includes(".agents/")) {
+      issues.push({
+        level: "warning",
+        file: AGENTS_MD,
+        message: "No references to .agents/ \u2014 agents may not find memory files"
+      });
+    }
+    if (content.split("\n").length > 150) {
+      issues.push({
+        level: "warning",
+        file: AGENTS_MD,
+        message: "Over 150 lines \u2014 consider keeping it concise as a router"
+      });
+    }
+  }
+  const memoryPath = join2(projectDir, MEMORY_FILE);
+  if (existsSync2(memoryPath)) {
+    const lines = readFileSync2(memoryPath, "utf-8").split("\n").length;
+    if (lines > 150) {
+      issues.push({
+        level: "warning",
+        file: MEMORY_FILE,
+        message: `${lines} lines \u2014 consider compressing or archiving old entries`
+      });
+    }
+  }
+  const opencodePkgPath = join2(projectDir, ".opencode", "package.json");
+  const opencodeJsonPath = join2(projectDir, "opencode.json");
+  const opencodeExists = existsSync2(join2(projectDir, ".opencode"));
+  if (opencodeExists) {
+    if (!existsSync2(opencodePkgPath)) {
+      issues.push({
+        level: "warning",
+        file: ".opencode/package.json",
+        message: "Missing \u2014 run 'agent-memory init --opencode' to wire up the plugin"
+      });
+    } else {
+      try {
+        const pkg = JSON.parse(readFileSync2(opencodePkgPath, "utf-8"));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (!deps["@vuau/agent-memory"]) {
+          issues.push({
+            level: "warning",
+            file: ".opencode/package.json",
+            message: "@vuau/agent-memory not in dependencies \u2014 run 'agent-memory init --opencode'"
+          });
+        }
+      } catch {
+        issues.push({ level: "warning", file: ".opencode/package.json", message: "Invalid JSON" });
+      }
+    }
+    if (!existsSync2(opencodeJsonPath)) {
+      issues.push({
+        level: "warning",
+        file: "opencode.json",
+        message: "Missing \u2014 run 'agent-memory init --opencode' to wire up the plugin"
+      });
+    } else {
+      try {
+        const config = JSON.parse(readFileSync2(opencodeJsonPath, "utf-8"));
+        const plugins = config.plugin || [];
+        if (!plugins.includes("@vuau/agent-memory")) {
+          issues.push({
+            level: "warning",
+            file: "opencode.json",
+            message: "@vuau/agent-memory not in plugin array \u2014 run 'agent-memory init --opencode'"
+          });
+        }
+      } catch {
+        issues.push({ level: "warning", file: "opencode.json", message: "Invalid JSON" });
+      }
+    }
+  }
+  return { ok: issues.filter((i) => i.level === "error").length === 0, issues };
+}
+
+// bin/cli.ts
+var args = process.argv.slice(2);
+var command = args[0];
+function printUsage() {
+  console.log(`
+@vuau/agent-memory \u2014 Structured AI memory for codebases
+
+Usage:
+  agent-memory init [options]    Scaffold .agents/ structure
+  agent-memory doctor            Validate .agents/ structure
+  agent-memory help              Show this help
+
+Options (init):
+  --force                        Overwrite existing files
+  --name <name>                  Project name (default: from package.json)
+  --no-copilot                   Skip .github/copilot-instructions.md
+  --opencode                     Wire up OpenCode plugin (.opencode/package.json + opencode.json)
+`);
+}
+function runInit() {
+  const force = args.includes("--force");
+  const noCopilot = args.includes("--no-copilot");
+  const opencode = args.includes("--opencode");
+  const nameIdx = args.indexOf("--name");
+  const projectName = nameIdx !== -1 ? args[nameIdx + 1] : void 0;
+  const cwd = process.cwd();
+  console.log(`Initializing agent memory in ${cwd}...`);
+  const result = scaffold(cwd, {
+    projectName,
+    copilotInstructions: !noCopilot,
+    opencode
+  }, force);
+  if (result.created.length > 0) {
+    console.log("\nCreated:");
+    for (const f of result.created) {
+      console.log(`  \u2713 ${f}`);
+    }
+  }
+  if (result.skipped.length > 0) {
+    console.log("\nSkipped (already exist):");
+    for (const f of result.skipped) {
+      console.log(`  - ${f}`);
+    }
+  }
+  if (result.created.length === 0 && result.skipped.length > 0) {
+    console.log("\nAll files already exist. Use --force to overwrite.");
+  }
+  console.log("\nNext steps:");
+  console.log("  1. Edit AGENTS.md \u2014 add your project-specific rules");
+  console.log("  2. Add spec files to .agents/spec/ for detailed documentation");
+  if (opencode) {
+    console.log("  3. Restart OpenCode to activate the plugin");
+  } else {
+    console.log("  3. For OpenCode: run with --opencode flag to wire up the plugin");
+  }
+  console.log("");
+}
+function runDoctor() {
+  const cwd = process.cwd();
+  const result = doctor(cwd);
+  if (result.issues.length === 0) {
+    console.log("\u2713 All checks passed!");
+    return;
+  }
+  for (const issue of result.issues) {
+    const icon = issue.level === "error" ? "\u2717" : issue.level === "warning" ? "\u26A0" : "\u2139";
+    console.log(`  ${icon} [${issue.level}] ${issue.file}: ${issue.message}`);
+  }
+  console.log("");
+  if (result.ok) {
+    console.log("\u26A0 Passed with warnings. Run 'agent-memory init' to fix missing files.");
+  } else {
+    console.log("\u2717 Failed. Run 'agent-memory init' to create missing files.");
+    process.exit(1);
+  }
+}
+switch (command) {
+  case "init":
+    runInit();
+    break;
+  case "doctor":
+    runDoctor();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+  case void 0:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}