engmemory 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import process from "process";
+import { Command } from "commander";
+import fs from "fs";
+import path from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  cleanIndexes,
+  diffKnowledge,
+  doctor,
+  initializeRepository,
+  publishKnowledge,
+  scanRepository,
+  syncRepository,
+  verifyKnowledge
+} from "@engmemory/core";
+import { searchKnowledge } from "@engmemory/knowledge-retrieval";
+var program = new Command();
+program.name("engmemory").description("Persistent engineering knowledge for Git repositories").version("0.1.0");
+program.command("init").description("Initialize Engineering Memory in the current Git repository").option("--json", "Print machine-readable output").action(async (options) => {
+  try {
+    const result = await initializeRepository(process.cwd());
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(`Initialized Engineering Memory at ${result.repositoryRoot}
+`);
+    if (result.created.length > 0) {
+      process.stdout.write(`Created ${result.created.length} knowledge files.
+`);
+    }
+    if (result.preserved.length > 0) {
+      process.stdout.write(`Preserved ${result.preserved.length} existing knowledge files.
+`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    program.error(message, { exitCode: 1 });
+  }
+});
+program.command("diff").description("Show pending knowledge changes").option("--json").action(async (options) => {
+  const result = await diffKnowledge(process.cwd());
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  else process.stdout.write(result.output || `Pending knowledge files:
+${result.files.map((file) => `  ${file}`).join("\n") || "none"}
+`);
+});
+program.command("publish").description("Create a knowledge branch and pull request").option("--dry-run", "Validate publishing without creating a branch or commit").option("--branch <name>", "Knowledge branch name").action(async (options) => {
+  const result = await publishKnowledge(process.cwd(), options);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+});
+program.command("doctor").description("Diagnose local Git and GitHub tooling").option("--json").action(async (options) => {
+  const result = await doctor(process.cwd());
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+});
+program.command("clean").description("Remove derived knowledge indexes for a rebuild").action(async () => {
+  const removed = await cleanIndexes(process.cwd());
+  process.stdout.write(`Removed derived index entries: ${removed.length}
+`);
+});
+program.command("status").description("Show repository knowledge status").option("--json", "Print machine-readable output").action(async (options) => {
+  try {
+    const fs2 = await import("fs");
+    const path2 = await import("path");
+    const indexPath = path2.join(process.cwd(), ".engineering-memory", "indexes", "extracted-knowledge.json");
+    if (!fs2.existsSync(indexPath)) {
+      program.error("Knowledge index not found. Run engmemory scan first.", { exitCode: 1 });
+    }
+    const knowledge = JSON.parse(fs2.readFileSync(indexPath, "utf8"));
+    const result = {
+      apis: knowledge.apis?.length ?? 0,
+      databases: knowledge.databases?.length ?? 0,
+      businessRules: knowledge.businessRules?.length ?? 0,
+      technicalRules: knowledge.technicalRules?.length ?? 0
+    };
+    if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    else process.stdout.write(`APIs: ${result.apis}; databases: ${result.databases}; business rules: ${result.businessRules}; technical rules: ${result.technicalRules}
+`);
+  } catch (error) {
+    program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+  }
+});
+program.command("mcp").description("Start the local read-only MCP server").action(() => {
+  const repositoryRoot = process.cwd();
+  const server = new McpServer({
+    name: "engineering-memory",
+    version: "0.1.0"
+  });
+  server.registerTool(
+    "search_knowledge",
+    {
+      description: "Search Engineering Memory knowledge in the repository.",
+      inputSchema: {
+        query: z.string().min(1),
+        category: z.string().optional(),
+        status: z.string().optional()
+      }
+    },
+    async ({ query, category, status }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(searchKnowledge(repositoryRoot, query, { category, status }), null, 2)
+      }]
+    })
+  );
+  server.registerTool(
+    "get_project_overview",
+    {
+      description: "Read the repository Engineering Memory overview.",
+      inputSchema: {}
+    },
+    async () => {
+      const overviewPath = path.join(repositoryRoot, ".engineering-memory", "project", "overview.md");
+      const overview = fs.existsSync(overviewPath) ? fs.readFileSync(overviewPath, "utf8") : "";
+      return { content: [{ type: "text", text: overview }] };
+    }
+  );
+  return server.connect(new StdioServerTransport());
+});
+program.command("sync").description("Synchronize knowledge changed since the last scan").option("--json", "Print machine-readable output").action(async (options) => {
+  try {
+    const result = await syncRepository(process.cwd());
+    if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    else process.stdout.write(`Synchronized ${result.changedFiles.length} changed files; ${result.unchangedFiles} unchanged.
+`);
+  } catch (error) {
+    program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+  }
+});
+program.command("search <query>").description("Search repository knowledge").option("--json", "Print machine-readable output").action(async (query, options) => {
+  try {
+    const results = searchKnowledge(process.cwd(), query);
+    if (options.json) process.stdout.write(`${JSON.stringify(results, null, 2)}
+`);
+    else {
+      for (const result of results) process.stdout.write(`${result.id}	${result.title}
+`);
+      if (results.length === 0) process.stdout.write("No matching knowledge found.\n");
+    }
+  } catch (error) {
+    program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+  }
+});
+program.command("verify").description("Verify extracted knowledge source references").option("--json", "Print machine-readable output").action(async (options) => {
+  try {
+    const result = await verifyKnowledge(process.cwd());
+    if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    else process.stdout.write(`Verified ${result.verified} records; ${result.stale} stale records.
+`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    program.error(message, { exitCode: 1 });
+  }
+});
+program.command("scan").description("Scan repository structure and TypeScript symbols").option("--json", "Print machine-readable output").action(async (options) => {
+  try {
+    const facts = await scanRepository(process.cwd());
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(facts, null, 2)}
+`);
+      return;
+    }
+    process.stdout.write(
+      `Scanned ${facts.inventory.files.length} files; found ${facts.symbols.length} symbols and ${facts.dependencies.length} dependencies.
+`
+    );
+    if (facts.inventory.languages.length === 0) {
+      process.stdout.write("No TypeScript or JavaScript files detected.\n");
+    }
+    if (!options.json && facts.inventory.root) {
+      process.stdout.write("Knowledge extraction index written to .engineering-memory/indexes/extracted-knowledge.json\n");
+    }
+    if (facts.diagnostics.length > 0) {
+      process.stdout.write(`TypeScript diagnostics: ${facts.diagnostics.length}
+`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    program.error(message, { exitCode: 1 });
+  }
+});
+await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,27 @@
-{
-  "name": "engmemory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "engmemory",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "engmemory": "./dist/index.js"
+  },
+  "exports": "./src/index.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@engmemory/core": "workspace:*",
+    "@engmemory/knowledge-retrieval": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.17.3",
+    "commander": "^14.0.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  cleanIndexes,
+  diffKnowledge,
+  doctor,
+  initializeRepository,
+  publishKnowledge,
+  scanRepository,
+  syncRepository,
+  verifyKnowledge,
+} from "@engmemory/core";
+import { searchKnowledge } from "@engmemory/knowledge-retrieval";
+
+const program = new Command();
+
+program
+  .name("engmemory")
+  .description("Persistent engineering knowledge for Git repositories")
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Initialize Engineering Memory in the current Git repository")
+  .option("--json", "Print machine-readable output")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const result = await initializeRepository(process.cwd());
+
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+
+      process.stdout.write(`Initialized Engineering Memory at ${result.repositoryRoot}\n`);
+      if (result.created.length > 0) {
+        process.stdout.write(`Created ${result.created.length} knowledge files.\n`);
+      }
+      if (result.preserved.length > 0) {
+        process.stdout.write(`Preserved ${result.preserved.length} existing knowledge files.\n`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      program.error(message, { exitCode: 1 });
+    }
+  });
+
+program.command("diff").description("Show pending knowledge changes").option("--json").action(async (options: { json?: boolean }) => {
+  const result = await diffKnowledge(process.cwd());
+  if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(result.output || `Pending knowledge files:\n${result.files.map((file) => `  ${file}`).join("\n") || "none"}\n`);
+});
+
+program.command("publish").description("Create a knowledge branch and pull request")
+  .option("--dry-run", "Validate publishing without creating a branch or commit")
+  .option("--branch <name>", "Knowledge branch name")
+  .action(async (options: { dryRun?: boolean; branch?: string }) => {
+    const result = await publishKnowledge(process.cwd(), options);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  });
+
+program.command("doctor").description("Diagnose local Git and GitHub tooling").option("--json").action(async (options: { json?: boolean }) => {
+  const result = await doctor(process.cwd());
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+});
+
+program.command("clean").description("Remove derived knowledge indexes for a rebuild").action(async () => {
+  const removed = await cleanIndexes(process.cwd());
+  process.stdout.write(`Removed derived index entries: ${removed.length}\n`);
+});
+
+program
+  .command("status")
+  .description("Show repository knowledge status")
+  .option("--json", "Print machine-readable output")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const fs = await import("node:fs");
+      const path = await import("node:path");
+      const indexPath = path.join(process.cwd(), ".engineering-memory", "indexes", "extracted-knowledge.json");
+      if (!fs.existsSync(indexPath)) {
+        program.error("Knowledge index not found. Run engmemory scan first.", { exitCode: 1 });
+      }
+      const knowledge = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+      const result = {
+        apis: knowledge.apis?.length ?? 0,
+        databases: knowledge.databases?.length ?? 0,
+        businessRules: knowledge.businessRules?.length ?? 0,
+        technicalRules: knowledge.technicalRules?.length ?? 0,
+      };
+      if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      else process.stdout.write(`APIs: ${result.apis}; databases: ${result.databases}; business rules: ${result.businessRules}; technical rules: ${result.technicalRules}\n`);
+    } catch (error) {
+      program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+    }
+  });
+
+program
+  .command("mcp")
+  .description("Start the local read-only MCP server")
+  .action(() => {
+    const repositoryRoot = process.cwd();
+    const server = new McpServer({
+      name: "engineering-memory",
+      version: "0.1.0",
+    });
+
+    server.registerTool(
+      "search_knowledge",
+      {
+        description: "Search Engineering Memory knowledge in the repository.",
+        inputSchema: {
+          query: z.string().min(1),
+          category: z.string().optional(),
+          status: z.string().optional(),
+        },
+      },
+      async ({ query, category, status }) => ({
+        content: [{
+          type: "text",
+          text: JSON.stringify(searchKnowledge(repositoryRoot, query, { category, status }), null, 2),
+        }],
+      }),
+    );
+
+    server.registerTool(
+      "get_project_overview",
+      {
+        description: "Read the repository Engineering Memory overview.",
+        inputSchema: {},
+      },
+      async () => {
+        const overviewPath = path.join(repositoryRoot, ".engineering-memory", "project", "overview.md");
+        const overview = fs.existsSync(overviewPath) ? fs.readFileSync(overviewPath, "utf8") : "";
+        return { content: [{ type: "text", text: overview }] };
+      },
+    );
+
+    return server.connect(new StdioServerTransport());
+  });
+
+program
+  .command("sync")
+  .description("Synchronize knowledge changed since the last scan")
+  .option("--json", "Print machine-readable output")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const result = await syncRepository(process.cwd());
+      if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      else process.stdout.write(`Synchronized ${result.changedFiles.length} changed files; ${result.unchangedFiles} unchanged.\n`);
+    } catch (error) {
+      program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+    }
+  });
+
+program
+  .command("search <query>")
+  .description("Search repository knowledge")
+  .option("--json", "Print machine-readable output")
+  .action(async (query: string, options: { json?: boolean }) => {
+    try {
+      const results = searchKnowledge(process.cwd(), query);
+      if (options.json) process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+      else {
+        for (const result of results) process.stdout.write(`${result.id}\t${result.title}\n`);
+        if (results.length === 0) process.stdout.write("No matching knowledge found.\n");
+      }
+    } catch (error) {
+      program.error(error instanceof Error ? error.message : String(error), { exitCode: 1 });
+    }
+  });
+
+program
+  .command("verify")
+  .description("Verify extracted knowledge source references")
+  .option("--json", "Print machine-readable output")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const result = await verifyKnowledge(process.cwd());
+      if (options.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      else process.stdout.write(`Verified ${result.verified} records; ${result.stale} stale records.\n`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      program.error(message, { exitCode: 1 });
+    }
+  });
+
+program
+  .command("scan")
+  .description("Scan repository structure and TypeScript symbols")
+  .option("--json", "Print machine-readable output")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const facts = await scanRepository(process.cwd());
+      if (options.json) {
+        process.stdout.write(`${JSON.stringify(facts, null, 2)}\n`);
+        return;
+      }
+      process.stdout.write(
+        `Scanned ${facts.inventory.files.length} files; found ${facts.symbols.length} symbols and ` +
+        `${facts.dependencies.length} dependencies.\n`,
+      );
+      if (facts.inventory.languages.length === 0) {
+        process.stdout.write("No TypeScript or JavaScript files detected.\n");
+      }
+      if (!options.json && facts.inventory.root) {
+        process.stdout.write("Knowledge extraction index written to .engineering-memory/indexes/extracted-knowledge.json\n");
+      }
+      if (facts.diagnostics.length > 0) {
+        process.stdout.write(`TypeScript diagnostics: ${facts.diagnostics.length}\n`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      program.error(message, { exitCode: 1 });
+    }
+  });
+
+await program.parseAsync(process.argv);

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"],
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.