enigma-memory 0.1.12 → 0.1.13

package/apps/cli/bin/enigma.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { createHash } from 'node:crypto';
 import { createServer as createHttpServer } from 'node:http';
-import { realpathSync } from 'node:fs';
-import { access, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { constants as fsConstants, realpathSync } from 'node:fs';
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createVault, remember, recall, updateMemory, deleteMemory, exportBundle } from '../../../packages/vault/src/index.js';
@@ -574,6 +574,86 @@ function minimumNodeMajor(range) {
   return match ? Number(match[1]) : 0;
 }
 
+function npmUserAgentCheck(userAgent = process.env.npm_config_user_agent) {
+  const raw = typeof userAgent === 'string' ? userAgent.trim() : '';
+  const npmToken = raw.split(/\s+/).find((token) => token.startsWith('npm/'));
+  const version = npmToken ? npmToken.slice(4) : null;
+  return {
+    ok: true,
+    detected: version !== null,
+    name: version === null ? null : 'npm',
+    version,
+    source: version === null ? null : 'npm_config_user_agent',
+  };
+}
+
+async function statIfExists(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+async function nearestExistingAncestor(path) {
+  let current = resolve(path);
+  for (;;) {
+    const stats = await statIfExists(current);
+    if (stats !== null) return { path: current, stats };
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function publicParentDisplay(path, label) {
+  const value = String(path);
+  if (/^<[^>]+>$/.test(value)) return `<${label}>`;
+  const parent = dirname(value);
+  return parent === '' ? '.' : publicPathDisplay(parent, label);
+}
+
+async function writableVaultPathCheck(bundleInput, displayInput = bundleInput) {
+  const bundlePath = resolve(String(bundleInput));
+  const parentPath = dirname(bundlePath);
+  const targetStats = await statIfExists(bundlePath);
+  const nearest = await nearestExistingAncestor(parentPath);
+  let ok = false;
+  let reason = null;
+  let parentExists = false;
+  let nearestExistingParent = null;
+  if (targetStats?.isDirectory()) {
+    reason = 'target_is_directory';
+  } else if (nearest === null) {
+    reason = 'no_existing_parent';
+  } else if (!nearest.stats.isDirectory()) {
+    reason = 'nearest_parent_not_directory';
+    nearestExistingParent = '<existing-parent-path>';
+  } else {
+    parentExists = nearest.path === parentPath;
+    nearestExistingParent = parentExists ? publicParentDisplay(displayInput, 'bundle-dir') : '<existing-parent-dir>';
+    try {
+      await access(nearest.path, fsConstants.W_OK);
+      ok = true;
+    } catch {
+      reason = 'parent_not_writable';
+    }
+  }
+  return {
+    ok,
+    path: publicPathDisplay(displayInput, 'bundle-path'),
+    parent: publicParentDisplay(displayInput, 'bundle-dir'),
+    parent_exists: parentExists,
+    nearest_existing_parent: nearestExistingParent,
+    target_exists: targetStats !== null,
+    target_is_directory: targetStats?.isDirectory() === true,
+    writable: ok,
+    reason,
+    hint: ok ? null : 'Choose a writable --bundle path or create a writable parent directory.',
+  };
+}
+
 async function schemaFiles() {
   return (await readdir(SPECS_URL)).filter((name) => name.endsWith('.schema.json')).sort();
 }
@@ -908,10 +988,19 @@ function setupNextCommands(bundleInput, exportDisplay, clients, writeConnectors)
     `enigma context --bundle ${commandPath(bundleInput)} --query "project context"`,
     `enigma verify --export ${commandPath(exportDisplay)}`,
   ];
-  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)}`);
+  if (!writeConnectors) commands.push(`enigma connect ${primaryClient} --bundle ${commandPath(bundleInput)} --dry-run`);
   return commands;
 }
 
+function doctorNextCommands(bundleDisplay, client) {
+  const clientId = client ?? DEFAULT_SETUP_CLIENTS[0];
+  return [
+    `enigma setup --bundle ${commandPath(bundleDisplay)}`,
+    `enigma doctor --bundle ${commandPath(bundleDisplay)} --client ${clientId}`,
+    `enigma connect ${clientId} --bundle ${commandPath(bundleDisplay)}`,
+  ];
+}
+
 async function setupDoctorChecks(flags, artifacts, clients, displays) {
   const packageJson = await readPackageJson();
   const requiredNodeMajor = minimumNodeMajor(packageJson.engines?.node);
@@ -938,12 +1027,15 @@ async function setupDoctorChecks(flags, artifacts, clients, displays) {
     const doctor = await doctorConnectors({ ...connectorBaseOptions, clientId: client });
     connectorClients.push(...doctor.clients);
   }
+  const vaultPath = await writableVaultPathCheck(artifacts.bundlePath, displays.bundle);
   const checks = {
     node: {
       ok: requiredNodeMajor === 0 || currentNodeMajor >= requiredNodeMajor,
       current: process.versions.node,
       required: packageJson.engines?.node ?? null,
     },
+    npm: npmUserAgentCheck(),
+    vault_path: vaultPath,
     package_bins: {
       ok: binEntries.every((entry) => entry.declared && entry.exists),
       required: REQUIRED_PACKAGE_BINS,
@@ -1531,7 +1623,7 @@ function testDriveNextCommands(bundleDisplay, crossModelReportDisplay) {
     `enigma status --bundle ${quotedBundle}`,
     `enigma search --bundle ${quotedBundle} --query "local proof bundle"`,
     `enigma demo cross-model --bundle ${quotedBundle} --out ${quotedReport}`,
-    'node scripts/run-memory-benchmarks.mjs',
+    'enigma setup --overwrite',
   ];
 }
 
@@ -1736,7 +1828,7 @@ export async function testDriveCommand(flags, io) {
     out_dir: outDirInput,
     bundle: bundleInput,
     install_command: `npm install -g ${packageJson.name ?? 'enigma-memory'}`,
-    release_target: '0.1.12',
+    release_target: '0.1.13',
     artifacts_written: !dryRun,
     client_configs_written: false,
     client_config_write_required: false,
@@ -1842,10 +1934,11 @@ export async function doctorCommand(flags, io) {
     };
   }));
   const schemas = await schemaFiles();
+  const bundleInput = pathFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE);
   const selectedClient = getFlag(flags, ['client']);
   const doctorOptions = selectedClient && selectedClient !== true
-    ? { ...connectorOptions(flags), clientId: String(selectedClient) }
-    : { ...connectorOptions(flags), clientId: undefined };
+    ? { ...connectorOptions(flags), clientId: String(selectedClient), redactPaths: true }
+    : { ...connectorOptions(flags), clientId: undefined, redactPaths: true };
   const connectorDoctor = await doctorConnectors(doctorOptions);
   const profile = getClientProfile(String(selectedClient && selectedClient !== true ? selectedClient : 'generic-mcp'), connectorOptions(flags));
   const checks = {
@@ -1854,6 +1947,7 @@ export async function doctorCommand(flags, io) {
       current: process.versions.node,
       required: packageJson.engines?.node ?? null,
     },
+    npm: npmUserAgentCheck(),
     package_bins: {
       ok: binEntries.every((entry) => entry.declared && entry.exists),
       required: REQUIRED_PACKAGE_BINS,
@@ -1864,8 +1958,9 @@ export async function doctorCommand(flags, io) {
     bundle_default_path: {
       ok: DEFAULT_BUNDLE === '.enigma/bundle.json',
       path: DEFAULT_BUNDLE,
-      resolved: resolve(String(getFlag(flags, ['bundle', 'file'], DEFAULT_BUNDLE))),
+      resolved: publicPathDisplay(resolve(bundleInput), 'bundle-path'),
     },
+    vault_path: await writableVaultPathCheck(resolve(bundleInput), publicPathDisplay(bundleInput, 'bundle-path')),
     schemas: {
       ok: schemas.length > 0,
       count: schemas.length,
@@ -1883,11 +1978,14 @@ export async function doctorCommand(flags, io) {
     ok,
     node: checks.node,
     package_bins: checks.package_bins,
+    npm: checks.npm,
+    vault_path: checks.vault_path,
     bundle_default_path: checks.bundle_default_path,
     schema_count: checks.schemas.count,
     schemas: checks.schemas,
     mcp_command_name: checks.mcp_command_name.command,
     connectors: checks.connectors,
+    next_commands: doctorNextCommands(checks.vault_path.path, String(selectedClient && selectedClient !== true ? selectedClient : 'generic-mcp')),
     checks,
   }, io);
   return ok ? 0 : 1;

package/docs/benchmark-attestation-network.md

@@ -169,7 +169,7 @@ Minimum public-safe attestation skeleton:
   "track": "public_practice",
   "program": {
     "name": "enigma_benchmark_attestation_network",
-    "version": "0.1.12",
+    "version": "0.1.13",
     "policy_ref": "sha256:policy-root"
   },
   "run": {
@@ -177,7 +177,7 @@ Minimum public-safe attestation skeleton:
     "nonce": "sha256:run-nonce-commitment",
     "status": "completed",
     "runner_ref": "sha256:runner-root",
-    "package_ref": "npm:enigma-memory@0.1.12",
+    "package_ref": "npm:enigma-memory@0.1.13",
     "adapter_ref": "local:enigma-relevance",
     "environment_ref": "sha256:environment-summary-root"
   },

package/docs/benchmark-reproducibility.md

@@ -4,7 +4,7 @@ This guide explains how to reproduce the current local Enigma memory benchmark,
 
 ## What is reproducible today
 
-The current planned package is `enigma-memory@0.1.12`. Two benchmark paths are reproducible without provider credentials:
+The current planned package is `enigma-memory@0.1.13`. Two benchmark paths are reproducible without provider credentials:
 
 1. The local deterministic memory suite, available through the package script and the script file it wraps:
 
@@ -64,7 +64,7 @@ Do not commit downloaded files or raw benchmark conversations. The package `.git
 
 ## Reproduce and save local fixture JSON
 
-1. Use a clean checkout containing `enigma-memory@0.1.12`.
+1. Use a clean checkout containing `enigma-memory@0.1.13`.
 2. From a repository root that contains `enigma/package.json`, enter the package directory:
 
    ```sh
@@ -130,7 +130,7 @@ Public sharing should include the generated benchmark report JSON and generated
 
 ## Proof-network benchmark attestations
 
-For the planned 0.1.12 proof-network layer, benchmark results should be represented as a public-safe local attestation rather than by publishing raw benchmark inputs. The attestation JSON uses `schema: "enigma.proof_network.benchmark_attestation.v1"` and may be bundled in `enigma.proof_network.packet.v1` for review. The benchmark attestation flow is local planning only: it does not submit transactions, and generated artifacts must keep `transaction_submitted: false` and `raw_memory_on_chain: false`.
+For the planned 0.1.13 proof-network layer, benchmark results should be represented as a public-safe local attestation rather than by publishing raw benchmark inputs. The attestation JSON uses `schema: "enigma.proof_network.benchmark_attestation.v1"` and may be bundled in `enigma.proof_network.packet.v1` for review. The benchmark attestation flow is local planning only: it does not submit transactions, and generated artifacts must keep `transaction_submitted: false` and `raw_memory_on_chain: false`.
 
 Hash the generated benchmark report and companion dataset manifest, then attest only the hashes, schema names, dataset refs, runner refs, package refs, aggregate metric names/values copied from the report, record counts, top-k/sample bounds, timestamps, and signatures or signer refs needed for review. The public artifact must not contain raw dataset rows, raw conversations, prompts, private questions, private answers, provider responses, embeddings, credentials, tenant names, account ids, local absolute paths, or unpublished benchmark scores.
 
@@ -139,7 +139,7 @@ Use a `sha256:<hex>` commitment for the report and manifest. If the CLI derives
 After running one of the benchmark commands above and confirming the report is public-safe, create a local planning attestation with placeholder hashes and metric values replaced from the generated report and manifest:
 
 ```sh
-enigma chain attest --report-file .enigma/standard-memory-benchmark-sample.json --dataset-ref "sha256:<public-dataset-or-manifest-hash>" --runner-ref "run-standard-memory-benchmarks.mjs@<reviewed-revision>" --package-ref "enigma-memory@0.1.12" --score "retrieval_evidence_proxy=<value-copied-from-report>" --out .enigma/standard-memory-benchmark-attestation.json
+enigma chain attest --report-file .enigma/standard-memory-benchmark-sample.json --dataset-ref "sha256:<public-dataset-or-manifest-hash>" --runner-ref "run-standard-memory-benchmarks.mjs@<reviewed-revision>" --package-ref "enigma-memory@0.1.13" --score "retrieval_evidence_proxy=<value-copied-from-report>" --out .enigma/standard-memory-benchmark-attestation.json
 enigma chain verify --file .enigma/standard-memory-benchmark-attestation.json
 ```