Release v0.3.8.

Harden npm install behavior by bundling and resolving OpenAPI artifacts across package-consumer contexts, enforce stdio-safe schema logging, and expand contract/integration coverage for install and output safety.

Author: markmhendrickson

frontend/src/components/AppNavigationSidebar.tsx

@@ -199,6 +199,7 @@ export function AppNavigationSidebar({ siteName }: AppNavigationSidebarProps) {
                 <SidebarMenuButton
                   asChild
                   isActive={activeSection === section.id}
+                  tooltip={section.shortLabel}
                   className={sectionLinkClass(activeSection === section.id)}
                 >
                   <a href={`#${section.id}`} onClick={onSectionClick}>

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "neotoma",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "MCP server for structured personal data memory with unified source ingestion",
   "main": "dist/index.js",
   "type": "module",
@@ -134,6 +134,7 @@
   },
   "files": [
     "dist",
+    "openapi.yaml",
     "LICENSE",
     "README.md"
   ],

package.json

@@ -7,6 +7,7 @@
  * 2. Runs npm pack to create the tarball that would be published
  * 3. Installs that tarball in a temporary directory (as a consumer would)
  * 4. Runs the installed binary (npx neotoma --help) to verify it works
+ * 5. Verifies OpenAPI schema can be resolved from installed package (cwd-independent)
  * 5. Cleans up
  *
  * Run before `npm publish` to catch pack/list/postinstall issues.
@@ -81,6 +82,12 @@ function main() {
     console.log("\nStep 4: Verifying installed binary...");
     run("npx neotoma --help", { cwd: tmpDir });
 
+    console.log("\nStep 5: Verifying OpenAPI schema resolution from installed package...");
+    run(
+      `node --input-type=module -e "import { resolveOpenApiPath } from 'neotoma/dist/shared/openapi_file.js'; const p = resolveOpenApiPath(); if (!p.endsWith('openapi.yaml')) { throw new Error('Unexpected OpenAPI path: ' + p); } console.log(p);"`,
+      { cwd: tmpDir }
+    );
+
     console.log("\nSimulate install passed. Package would install and run correctly.");
   } finally {
     if (tmpDir && fs.existsSync(tmpDir)) {

scripts/simulate_npm_install.js

@@ -65,6 +65,7 @@ import {
   prepareEntitySnapshotWithEmbedding,
   upsertEntitySnapshotWithEmbedding,
 } from "./services/entity_snapshot_embedding.js";
+import { readOpenApiFile } from "./shared/openapi_file.js";
 // import { setupDocumentationRoutes } from "./routes/documentation.js";
 
 type ErrorEnvelope = {
@@ -4390,8 +4391,7 @@ app.post("/health_check_snapshots", async (req, res) => {
 // Conversational interactions should be externalized to MCP-compatible agents per architecture
 
 app.get("/openapi.yaml", (req, res) => {
-  const openApiPath = path.join(process.cwd(), "openapi.yaml");
-  const openApiContent = fs.readFileSync(openApiPath, "utf-8");
+  const openApiContent = readOpenApiFile();
   const spec = yaml.load(openApiContent) as { servers?: Array<{ url: string; description?: string }> };
   const baseUrl = (config.apiBase || "").replace(/\/$/, "");
   if (spec.servers?.length && baseUrl) {

src/actions.ts

@@ -11559,19 +11559,38 @@ export type InitContextStatus = {
 export async function getInitContextStatus(
   repoRoot: string | null
 ): Promise<InitContextStatus | null> {
-  const envTarget: "project" | "user" = repoRoot ? "project" : "user";
-  const envPath = repoRoot ? path.join(repoRoot, ".env") : USER_ENV_PATH;
+  let effectiveRepoRoot: string | null = repoRoot;
+  let envTarget: "project" | "user" = effectiveRepoRoot ? "project" : "user";
+  let envPath = effectiveRepoRoot ? path.join(effectiveRepoRoot, ".env") : USER_ENV_PATH;
+
+  // In package-consumer repos (not source checkouts), `init` can target cwd when
+  // neotoma is installed as a dependency. Mirror that resolution here so plain
+  // `npx neotoma` recognizes prior init in the same project.
+  if (!effectiveRepoRoot) {
+    const cwd = process.cwd();
+    if (await detectInstalledNeotomaPackage(cwd)) {
+      const packageEnvPath = path.join(cwd, ".env");
+      if (await pathExists(packageEnvPath)) {
+        effectiveRepoRoot = cwd;
+        envTarget = "project";
+        envPath = packageEnvPath;
+      }
+    }
+  }
+
   const envFileExists = await pathExists(envPath);
   const homeDir = process.env.HOME || process.env.USERPROFILE || ".";
-  const defaultDataDir = repoRoot ? path.join(repoRoot, "data") : path.join(homeDir, "neotoma", "data");
+  const defaultDataDir = effectiveRepoRoot
+    ? path.join(effectiveRepoRoot, "data")
+    : path.join(homeDir, "neotoma", "data");
   let dataDir: string;
   if (envFileExists) {
     const envVars = await readEnvFileVars(envPath);
     const configured = envVars.NEOTOMA_DATA_DIR?.trim();
     dataDir = configured
       ? path.isAbsolute(configured)
         ? configured
-        : path.resolve(repoRoot ?? process.cwd(), configured)
+        : path.resolve(effectiveRepoRoot ?? process.cwd(), configured)
       : defaultDataDir;
   } else {
     dataDir = defaultDataDir;

src/cli/index.ts

@@ -15,6 +15,10 @@ import { dirname, join } from "path";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+function logSchemaRegistryInfo(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
 export interface ConverterDefinition {
   from: "number" | "string" | "boolean" | "array" | "object";
   to: "string" | "number" | "date" | "boolean" | "array" | "object";
@@ -398,7 +402,7 @@ export class SchemaRegistryService {
     for (const field of options.fields_to_add || []) {
       // Skip if field already exists
       if (mergedFields[field.field_name]) {
-        console.log(
+        logSchemaRegistryInfo(
           `[SCHEMA_REGISTRY] Field ${field.field_name} already exists in schema, skipping`,
         );
         continue;
@@ -447,13 +451,13 @@ export class SchemaRegistryService {
       await this.activate(options.entity_type, newVersion);
     }
 
-    console.log(
+    logSchemaRegistryInfo(
       `[SCHEMA_REGISTRY] Incrementally updated schema for ${options.entity_type} to version ${newVersion}`,
     );
 
     // 7. Migrate raw_fragments if requested (historical data backfill only)
     if (options.migrate_existing) {
-      console.log(
+      logSchemaRegistryInfo(
         `[SCHEMA_REGISTRY] Migrating existing raw_fragments for ${options.entity_type}`,
       );
       const fieldNamesToMigrate = [
@@ -485,7 +489,7 @@ export class SchemaRegistryService {
     const BATCH_SIZE = 100; // Smaller batch size for safety
     let totalMigrated = 0;
 
-    console.log(
+    logSchemaRegistryInfo(
       `[SCHEMA_REGISTRY] Starting migration for fields: ${options.field_names.join(", ")}`,
     );
 
@@ -525,7 +529,7 @@ export class SchemaRegistryService {
           continue; // No more fragments to migrate
         }
 
-        console.log(
+        logSchemaRegistryInfo(
           `[SCHEMA_REGISTRY] Processing batch of ${fragments.length} fragments for field ${fieldName}`,
         );
 
@@ -638,7 +642,7 @@ export class SchemaRegistryService {
               }
             } else {
               totalMigrated += Object.keys(promotedFields).length;
-              console.log(
+              logSchemaRegistryInfo(
                 `[SCHEMA_REGISTRY] Migrated ${Object.keys(promotedFields).length} fields for entity ${entityId}`,
               );
 
@@ -706,7 +710,7 @@ export class SchemaRegistryService {
       }
     }
 
-    console.log(
+    logSchemaRegistryInfo(
       `[SCHEMA_REGISTRY] Migration complete. Total fragments processed: ${totalMigrated}`,
     );
 

src/services/schema_registry.ts

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const OPENAPI_FILENAME = "openapi.yaml";
+
+function getPackageRootFromModule(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(moduleDir, "..", "..");
+}
+
+export function resolveOpenApiPath(): string {
+  const fromEnv = process.env.NEOTOMA_OPENAPI_PATH?.trim();
+  const candidates = [
+    fromEnv || "",
+    join(getPackageRootFromModule(), OPENAPI_FILENAME),
+    join(process.cwd(), OPENAPI_FILENAME),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `OpenAPI schema not found. Tried: ${candidates.join(", ")}`
+  );
+}
+
+export function readOpenApiFile(): string {
+  return readFileSync(resolveOpenApiPath(), "utf-8");
+}

src/shared/openapi_file.ts

@@ -1,7 +1,6 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import yaml from "js-yaml";
 import { MCP_TOOL_TO_OPERATION_ID, OPENAPI_OPERATION_MAPPINGS } from "./contract_mappings.js";
+import { readOpenApiFile } from "./openapi_file.js";
 
 type OpenApiSchema = Record<string, unknown>;
 
@@ -33,8 +32,7 @@ function loadOpenApiSpec(): OpenApiSpec {
   if (cachedSpec) {
     return cachedSpec;
   }
-  const openApiPath = join(process.cwd(), "openapi.yaml");
-  const raw = readFileSync(openApiPath, "utf-8");
+  const raw = readOpenApiFile();
   cachedSpec = yaml.load(raw) as OpenApiSpec;
   return cachedSpec;
 }

src/shared/openapi_schema.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+describe("MCP stdio output safety", () => {
+  it("avoids console.log in schema registry to prevent stdout protocol noise", () => {
+    const schemaRegistryPath = resolve(process.cwd(), "src/services/schema_registry.ts");
+    const source = readFileSync(schemaRegistryPath, "utf8");
+    expect(source.includes("console.log(")).toBe(false);
+  });
+});