@neus/sdk 1.0.6 → 1.0.8

package/README.md

@@ -10,29 +10,6 @@
 npm install @neus/sdk
 ```
 
-## One-command onboarding
-
-```bash
-npx -y -p @neus/sdk neus init
-```
-
-Configures supported MCP clients automatically. By default the command installs NEUS into user-level Claude Code, Cursor, and VS Code MCP config when those clients are detected.
-
-## CLI
-
-```bash
-# Autopilot setup for detected clients
-npx -y -p @neus/sdk neus init
-
-# Enable personal account tools such as neus_me and private reads
-npx -y -p @neus/sdk neus auth --access-key <npk_...>
-
-# Inspect current NEUS MCP setup
-npx -y -p @neus/sdk neus status --json
-```
-
-Use `neus init --project` when you want shared repo config instead of personal user-scope setup. Access keys stay user-scope only so secrets do not land in checked-in config.
-
 ## Minimal working example
 
 ```javascript

package/SECURITY.md

@@ -1,38 +1,38 @@
-# NEUS SDK security notes
-
-Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose them to clients, or store them in analytics.
-
-## Authentication model
-
-- **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
-- **Proof lookups by `proofId`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
-- **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
-
-## Do not
-
-- Do not treat proof signatures as bearer tokens (they are request-bound).
-- Do not embed API keys in browser apps. Keep API keys server-side only.
-- Do not log or persist proof signatures, API keys, or third-party auth credentials (if your integration uses them).
-
-## Privacy defaults
-
-**`client.verify()`** defaults to **private**.
-
-**`VerifyGate`** create mode also defaults to **private**.
-
-Use public visibility only when you intentionally need proof reuse without owner-authenticated access:
-
-- unlisted public: `privacyLevel: 'public'`, `publicDisplay: false`
-- listed public: `privacyLevel: 'public'`, `publicDisplay: true`
-
-Do not treat unlisted public proofs as secret.
-
-`storeOriginalContent` is an advanced storage control. Most integrations should leave the default as-is.
-
-Controls:
-
-- `privacyLevel` - private by default; switch to public only for intentional public reuse
-- `publicDisplay` - discovery vs unlisted
-- `storeOriginalContent` - advanced content-storage control
-
-Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.
+# NEUS SDK security notes
+
+Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose them to clients, or store them in analytics.
+
+## Authentication model
+
+- **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
+- **Proof lookups by `proofId`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
+- **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
+
+## Do not
+
+- Do not treat proof signatures as bearer tokens (they are request-bound).
+- Do not embed API keys in browser apps. Keep API keys server-side only.
+- Do not log or persist proof signatures, API keys, or third-party auth credentials (if your integration uses them).
+
+## Privacy defaults
+
+**`client.verify()`** defaults to **private**.
+
+**`VerifyGate`** create mode also defaults to **private**.
+
+Use public visibility only when you intentionally need proof reuse without owner-authenticated access:
+
+- unlisted public: `privacyLevel: 'public'`, `publicDisplay: false`
+- listed public: `privacyLevel: 'public'`, `publicDisplay: true`
+
+Do not treat unlisted public proofs as secret.
+
+`storeOriginalContent` is an advanced storage control. Most integrations should leave the default as-is.
+
+Controls:
+
+- `privacyLevel` - private by default; switch to public only for intentional public reuse
+- `publicDisplay` - discovery vs unlisted
+- `storeOriginalContent` - advanced content-storage control
+
+Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.

package/cli/neus.mjs

@@ -24,9 +24,17 @@ function jsonStringify(value) {
 
 function readJsonFile(targetPath, fallback) {
   if (!fileExists(targetPath)) return fallback;
-  const raw = fs.readFileSync(targetPath, 'utf8');
-  const parsed = JSON.parse(raw);
-  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+  const raw = fs.readFileSync(targetPath, 'utf8').trim();
+  if (!raw) return fallback;
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid JSON in ${targetPath}`);
+    }
+    throw error;
+  }
 }
 
 function writeJsonFile(targetPath, nextValue, dryRun) {
@@ -306,6 +314,7 @@ function installCursor(scope, accessKey, dryRun, cwd) {
     targetPath,
     backupPath: writeResult.backupPath,
     dryRun,
+    error: null,
   };
 }
 
@@ -329,6 +338,7 @@ function installVsCode(scope, accessKey, dryRun, cwd) {
     targetPath,
     backupPath: writeResult.backupPath,
     dryRun,
+    error: null,
   };
 }
 
@@ -352,6 +362,7 @@ function installClaudeProject(scope, accessKey, dryRun, cwd) {
     targetPath,
     backupPath: writeResult.backupPath,
     dryRun,
+    error: null,
   };
 }
 
@@ -387,6 +398,7 @@ function installClaudeUser(scope, accessKey, dryRun, cwd) {
     targetPath: '~/.claude.json',
     backupPath: null,
     dryRun,
+    error: null,
   };
 }
 
@@ -407,7 +419,7 @@ function installClient(client, scope, accessKey, dryRun, cwd) {
 function inspectCursor(scope, cwd) {
   const targetPath = cursorConfigPath(scope, cwd);
   if (!fileExists(targetPath)) {
-    return { client: 'cursor', scope, configured: false, authConfigured: false, targetPath };
+    return { client: 'cursor', scope, configured: false, authConfigured: false, targetPath, error: null };
   }
   const doc = readJsonFile(targetPath, {});
   const server = doc.mcpServers?.[NEUS_SERVER_NAME];
@@ -417,13 +429,14 @@ function inspectCursor(scope, cwd) {
     configured: Boolean(server && server.url === NEUS_MCP_URL),
     authConfigured: Boolean(server?.headers?.Authorization),
     targetPath,
+    error: null,
   };
 }
 
 function inspectVsCode(scope, cwd) {
   const targetPath = vscodeConfigPath(scope, cwd);
   if (!fileExists(targetPath)) {
-    return { client: 'vscode', scope, configured: false, authConfigured: false, targetPath };
+    return { client: 'vscode', scope, configured: false, authConfigured: false, targetPath, error: null };
   }
   const doc = readJsonFile(targetPath, {});
   const server = doc.servers?.[NEUS_SERVER_NAME];
@@ -433,6 +446,7 @@ function inspectVsCode(scope, cwd) {
     configured: Boolean(server && server.url === NEUS_MCP_URL),
     authConfigured: Boolean(server?.headers?.Authorization),
     targetPath,
+    error: null,
   };
 }
 
@@ -440,7 +454,7 @@ function inspectClaude(scope, cwd) {
   if (scope === 'project') {
     const targetPath = claudeProjectConfigPath(cwd);
     if (!fileExists(targetPath)) {
-      return { client: 'claude', scope, configured: false, authConfigured: false, targetPath };
+      return { client: 'claude', scope, configured: false, authConfigured: false, targetPath, error: null };
     }
     const doc = readJsonFile(targetPath, {});
     const server = doc.mcpServers?.[NEUS_SERVER_NAME];
@@ -450,11 +464,12 @@ function inspectClaude(scope, cwd) {
       configured: Boolean(server && server.url === NEUS_MCP_URL),
       authConfigured: Boolean(server?.headers?.Authorization),
       targetPath,
+      error: null,
     };
   }
 
   if (!commandExists('claude')) {
-    return { client: 'claude', scope, configured: false, authConfigured: null, targetPath: '~/.claude.json' };
+    return { client: 'claude', scope, configured: false, authConfigured: null, targetPath: '~/.claude.json', error: null };
   }
 
   const result = runCommand('claude', ['mcp', 'list'], cwd, true);
@@ -465,6 +480,7 @@ function inspectClaude(scope, cwd) {
     configured,
     authConfigured: null,
     targetPath: '~/.claude.json',
+    error: null,
   };
 }
 
@@ -479,9 +495,47 @@ function printJson(payload) {
   process.stdout.write(jsonStringify(payload));
 }
 
+function clientTargetPath(client, scope, cwd) {
+  if (client === 'cursor') return cursorConfigPath(scope, cwd);
+  if (client === 'vscode') return vscodeConfigPath(scope, cwd);
+  if (client === 'claude') {
+    return scope === 'project' ? claudeProjectConfigPath(cwd) : '~/.claude.json';
+  }
+  return null;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error || 'Unknown error');
+}
+
+function buildClientFailure(client, scope, cwd, dryRun, error) {
+  return {
+    client,
+    scope,
+    configured: false,
+    authConfigured: false,
+    changed: false,
+    targetPath: clientTargetPath(client, scope, cwd),
+    backupPath: null,
+    dryRun,
+    error: errorMessage(error),
+  };
+}
+
+function runClientOperations(clients, scope, cwd, dryRun, runner) {
+  return clients.map((client) => {
+    try {
+      return runner(client);
+    } catch (error) {
+      return buildClientFailure(client, scope, cwd, dryRun, error);
+    }
+  });
+}
+
 function printResultSummary(command, scope, results, accessKey) {
   const changedCount = results.filter((result) => result.changed).length;
-  const configuredClients = results.map((result) => result.client).join(', ');
+  const configuredClients = results.filter((result) => result.configured).map((result) => result.client).join(', ');
+  const failures = results.filter((result) => result.error);
   const lines = [
     `NEUS ${command} completed for ${results.length} client${results.length === 1 ? '' : 's'} in ${scope} scope.`,
     `Configured: ${configuredClients || 'none'}.`,
@@ -501,6 +555,9 @@ function printResultSummary(command, scope, results, accessKey) {
     const enabled = results.filter((result) => result.configured).map((result) => result.client);
     lines.push(`Active: ${enabled.length > 0 ? enabled.join(', ') : 'none'}.`);
   }
+  if (failures.length > 0) {
+    lines.push(`Issues: ${failures.map((result) => `${result.client}: ${result.error}`).join(' | ')}`);
+  }
 
   process.stdout.write(`${lines.join('\n')}\n`);
 }
@@ -508,11 +565,18 @@ function printResultSummary(command, scope, results, accessKey) {
 function runInit(options) {
   const scope = resolveScope(options);
   ensureSafeAuth('init', scope, options.accessKey);
+  const cwd = process.cwd();
 
   const clients = resolveClients(scope, options.clients);
   ensureClientSelection(scope, clients);
 
-  const results = clients.map((client) => installClient(client, scope, options.accessKey, options.dryRun, process.cwd()));
+  const results = runClientOperations(
+    clients,
+    scope,
+    cwd,
+    options.dryRun,
+    (client) => installClient(client, scope, options.accessKey, options.dryRun, cwd),
+  );
   const payload = {
     command: 'init',
     scope,
@@ -520,18 +584,24 @@ function runInit(options) {
     clients,
     accessKeyConfigured: Boolean(options.accessKey),
     results,
+    hasErrors: results.some((result) => result.error),
   };
 
   if (options.json) {
     printJson(payload);
-    return;
+  } else {
+    printResultSummary('init', scope, results, options.accessKey);
+  }
+
+  if (payload.hasErrors) {
+    process.exitCode = 1;
   }
-  printResultSummary('init', scope, results, options.accessKey);
 }
 
 function runAuth(options) {
   const scope = resolveScope(options);
   ensureSafeAuth('auth', scope, options.accessKey);
+  const cwd = process.cwd();
   if (!options.accessKey) {
     throw new Error(`Missing access key. Create one at ${NEUS_ACCESS_KEYS_URL} and rerun neus auth --access-key <npk_...>.`);
   }
@@ -539,32 +609,47 @@ function runAuth(options) {
   const clients = resolveClients(scope, options.clients);
   ensureClientSelection(scope, clients);
 
-  const results = clients.map((client) => installClient(client, scope, options.accessKey, options.dryRun, process.cwd()));
+  const results = runClientOperations(
+    clients,
+    scope,
+    cwd,
+    options.dryRun,
+    (client) => installClient(client, scope, options.accessKey, options.dryRun, cwd),
+  );
   const payload = {
     command: 'auth',
     scope,
     clients,
     accessKeyConfigured: true,
     results,
+    hasErrors: results.some((result) => result.error),
   };
 
   if (options.json) {
     printJson(payload);
-    return;
+  } else {
+    printResultSummary('auth', scope, results, options.accessKey);
+  }
+
+  if (payload.hasErrors) {
+    process.exitCode = 1;
   }
-  printResultSummary('auth', scope, results, options.accessKey);
 }
 
 function runStatus(options) {
   const scope = resolveScope(options);
+  const cwd = process.cwd();
   const clients = resolveClients(scope, options.clients);
   ensureClientSelection(scope, clients);
 
-  const inspected = clients.map((client) => inspectClient(client, scope, process.cwd()));
+  const inspected = runClientOperations(clients, scope, cwd, options.dryRun, (client) =>
+    inspectClient(client, scope, cwd),
+  );
   const payload = {
     command: 'status',
     scope,
     clients: inspected,
+    hasErrors: inspected.some((result) => result.error),
   };
 
   if (options.json) {