@neus/sdk 1.2.0 → 1.2.2

package/cli-commands.js

@@ -0,0 +1,75 @@
+/**
+ * NEUS CLI command strings — SSOT for docs, MCP context, product UI, and skills.
+ *
+ * Pattern (industry default):
+ * - Install once: `npm i -g @neus/sdk`
+ * - Daily use: `neus <command>` (short)
+ * - Zero-install try: `npx @neus/sdk <command>` (no global install)
+ */
+
+export const NEUS_PKG = '@neus/sdk';
+
+/** Recommended one-time install for builders using the CLI regularly. */
+export const NEUS_INSTALL_CLI = `npm i -g ${NEUS_PKG}`;
+
+/** Zero-install prefix — works without global install. */
+export const NEUS_NPX = `npx ${NEUS_PKG}`;
+
+/** Short commands (after `NEUS_INSTALL_CLI`). */
+export const NEUS_SETUP_CLI = 'neus setup';
+export const NEUS_AUTH_CLI = 'neus auth';
+export const NEUS_CHECK_CLI = 'neus check';
+export const NEUS_DOCTOR_CLI = 'neus doctor --live';
+export const NEUS_EXAMPLES_CLI = 'neus examples';
+
+/** One-shot copy-paste (no global install required). */
+export const NEUS_SETUP_NPX = `${NEUS_NPX} setup`;
+export const NEUS_AUTH_NPX = `${NEUS_NPX} auth`;
+export const NEUS_CHECK_NPX = `${NEUS_NPX} check`;
+export const NEUS_DOCTOR_NPX = `${NEUS_NPX} doctor --live`;
+export const NEUS_EXAMPLES_NPX = `${NEUS_NPX} examples`;
+
+/**
+ * @param {string} agentId
+ * @param {'cursor' | 'claude' | 'codex'} [host]
+ */
+export function neusMountApply(agentId, host = 'cursor') {
+  const id = String(agentId || '').trim();
+  return `neus mount ${id} --apply ${host}`;
+}
+
+/**
+ * @param {string} agentId
+ * @param {'cursor' | 'claude' | 'codex'} [host]
+ */
+export function neusMountApplyNpx(agentId, host = 'cursor') {
+  const id = String(agentId || '').trim();
+  return `${NEUS_NPX} mount ${id} --apply ${host}`;
+}
+
+/** Docs / landing quick start (installed path). */
+export const NEUS_QUICKSTART_INSTALLED = `${NEUS_INSTALL_CLI}
+${NEUS_SETUP_CLI}
+${NEUS_AUTH_CLI}`;
+
+/** Docs quick try (zero-install). */
+export const NEUS_QUICKSTART_NPX = NEUS_SETUP_NPX;
+
+/** Per-repo agent bind (after auth on the machine). */
+export const NEUS_MOUNT_WORKFLOW = `${NEUS_AUTH_CLI}
+neus mount <agentId> --apply cursor
+${NEUS_DOCTOR_CLI}`;
+
+/**
+ * @param {string} subcommand
+ */
+export function neusCmd(subcommand) {
+  return `neus ${String(subcommand || '').trim()}`;
+}
+
+/**
+ * @param {string} subcommand
+ */
+export function neusNpx(subcommand) {
+  return `${NEUS_NPX} ${String(subcommand || '').trim()}`;
+}

package/index.js

@@ -72,16 +72,7 @@ export {
   evaluateMountFileHealth
 } from './runtime-mount.js';
 
-export {
-  MOUNT_MANIFEST_RELATIVE,
-  sanitizeAgentIdForFilename,
-  bundleToCursorRules,
-  bundleToClaudeMd,
-  bundleToCodexJson,
-  readMountManifest,
-  writeMountManifest,
-  applyRuntimeBundle
-} from './runtime-adapters.js';
+// Node-only adapters (fs/path): import `@neus/sdk/runtime-adapters` — not re-exported here (Next/webpack safe).
 
 export {
   SDKError,

package/mcp-hosts.js

@@ -57,11 +57,36 @@ export const IDE_HOST_BRAND_LOGOS = {
 };
 
 /**
+ * Build the MCP HTTP server config for an IDE/client.
+ *
+ * Two paths, one session model — same NEUS Profile/Account either way:
+ *
+ * - `npk_…` Profile access keys are durable (never expire). Written as a static
+ *   `Authorization: Bearer npk_…` header. Used for operator IDEs, servers, CI,
+ *   and automation where browser OAuth is unavailable.
+ * - OAuth (default for Cursor, VS Code, Claude Code, Codex): we return a URL-only
+ *   config (no `headers`). The IDE MCP client discovers OAuth metadata from the
+ *   server's `401 + WWW-Authenticate` challenge, then runs its own DCR + PKCE +
+ *   silent-refresh lifecycle (matching Linear, GitHub, Notion). The access token
+ *   is a short-lived JWT refreshed silently by the host for up to 30 days via the
+ *   `offline_access` refresh token — the session is long-lived, the access token
+ *   is not
+ *
+ * A raw OAuth access token (JWT) is never written as a static Bearer header: IDE
+ * MCP clients cannot refresh a static header, and writing one would create a
+ * session that dies when the access token expires. URL-only config is the correct
+ * OAuth path and is what `neus setup`/`neus auth` produce for browser-OAuth clients.
+ *
  * @param {string | null | undefined} accessKey
  * @returns {{ type: 'http'; url: string; headers?: { Authorization: string } }}
  */
 export function buildNeusMcpHttpConfig(accessKey) {
   const key = String(accessKey || '').trim();
+  // OAuth access tokens are JWTs (three dot-separated base64url segments). Never write
+  // them as a static Bearer header — return URL-only so the IDE runs OAuth itself.
+  if (key && !key.startsWith('npk_') && key.split('.').length === 3) {
+    return { type: 'http', url: NEUS_MCP_URL };
+  }
   return {
     type: 'http',
     url: NEUS_MCP_URL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neus/sdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "NEUS makes trust portable across the internet — so people, apps, and AI agents can prove what is real before access, payout, or execution.",
   "bin": {
     "neus": "cli/neus.mjs"
@@ -141,6 +141,7 @@
   },
   "files": [
     "cli/neus.mjs",
+    "cli-commands.js",
     "mcp-hosts.js",
     "index.js",
     "client.js",
@@ -148,6 +149,8 @@
     "errors.js",
     "gates.js",
     "sponsor.js",
+    "runtime-mount.js",
+    "runtime-adapters.js",
     "cjs/**",
     "widgets.cjs",
     "types.d.ts",

package/runtime-adapters.js

@@ -0,0 +1,214 @@
+/**
+ * Runtime Mount adapters — apply proof-backed bundles to host workspaces.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { RUNTIME_MOUNT_SCHEMA } from './runtime-mount.js';
+
+export const MOUNT_MANIFEST_RELATIVE = path.join('.neus', 'mount.json');
+
+/**
+ * @param {string} agentId
+ */
+export function sanitizeAgentIdForFilename(agentId) {
+  return String(agentId || 'agent')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'agent';
+}
+
+/**
+ * @param {import('./runtime-mount.js').RuntimeBundle} bundle
+ */
+export function bundleToCursorRules(bundle) {
+  const id = bundle.identity.agentId;
+  const label = bundle.identity.agentLabel || id;
+  const skillsBlock = (bundle.identity.skills || [])
+    .map(skill => {
+      if (typeof skill === 'string') return `- ${skill}`;
+      const labelText = skill.label || skill.id || 'skill';
+      const kind = skill.kind || 'skill';
+      const provider = skill.provider ? ` / ${skill.provider}` : '';
+      return `- ${labelText} (${kind}${provider})`;
+    })
+    .join('\n');
+
+  const denied = (bundle.enforce.deniedActions || []).map(action => `- ${action}`).join('\n');
+  const capabilities = (bundle.identity.capabilities || []).map(cap => `- ${cap}`).join('\n');
+  const services = (bundle.identity.services || [])
+    .map(svc => `- ${svc.name}: ${svc.endpoint}${svc.version ? ` (v${svc.version})` : ''}`)
+    .join('\n');
+
+  return `---
+description: NEUS proof-backed agent — ${label}
+globs:
+alwaysApply: true
+---
+
+# NEUS Agent — ${label}
+
+You are **${label}** (\`${id}\`). This project mounted trust context from NEUS.
+
+## Identity
+${bundle.identity.description || bundle.identity.instructions || 'Follow the agent instructions below.'}
+
+## Instructions
+${bundle.identity.instructions || 'Use NEUS MCP for trust checks before sensitive actions.'}
+
+## Capabilities
+${capabilities || '- General purpose'}
+
+## Skills
+${skillsBlock || '- None configured'}
+
+## Services
+${services || '- None configured'}
+
+## Scoped policy
+${denied ? `Denied actions (do not perform without new approval):\n${denied}` : '- Follow delegation on file via NEUS MCP.'}
+
+## Trust workflow
+1. Call \`neus_context\` once per session when NEUS MCP is available.
+2. Trust before action: \`neus_proofs_check\` then \`neus_verify_or_guide\`.
+3. Do not invent qHashes, wallets, or receipt fields.
+4. Summarize NEUS outcomes as Trust Result — never dump raw tool JSON.
+
+## Proof references
+- Identity: ${bundle.trust.identityProofUrl}
+${bundle.trust.delegationProofUrl ? `- Delegation: ${bundle.trust.delegationProofUrl}` : '- Delegation: not on file — call `neus_agent_link` before acting as this agent.'}
+`;
+}
+
+/**
+ * @param {import('./runtime-mount.js').RuntimeBundle} bundle
+ */
+export function bundleToClaudeMd(bundle) {
+  const id = bundle.identity.agentId;
+  const label = bundle.identity.agentLabel || id;
+  return `# NEUS Agent — ${label}
+
+Mounted from NEUS Runtime Mount (\`${RUNTIME_MOUNT_SCHEMA}\`).
+
+## Identity
+- **Agent ID:** ${id}
+- **Label:** ${label}
+
+## Description
+${bundle.identity.description || 'Proof-backed agent on NEUS Network.'}
+
+## Instructions
+${bundle.identity.instructions || 'Use NEUS MCP before sensitive actions.'}
+
+## Trust receipts
+- Identity: \`${bundle.trust.identityQHash}\` — ${bundle.trust.identityProofUrl}
+${bundle.trust.delegationQHash ? `- Delegation: \`${bundle.trust.delegationQHash}\` — ${bundle.trust.delegationProofUrl}` : ''}
+
+## Policy
+- Do not invent qHashes or verifier outcomes.
+- Call \`neus_context\` once; use profile context when signed in.
+`;
+}
+
+/**
+ * @param {import('./runtime-mount.js').RuntimeBundle} bundle
+ */
+export function bundleToCodexJson(bundle) {
+  return JSON.stringify(
+    {
+      schema: RUNTIME_MOUNT_SCHEMA,
+      name: bundle.identity.agentLabel,
+      agentId: bundle.identity.agentId,
+      agentWallet: bundle.identity.agentWallet,
+      description: bundle.identity.description,
+      instructions: bundle.identity.instructions,
+      capabilities: bundle.identity.capabilities,
+      skills: bundle.identity.skills,
+      services: bundle.identity.services,
+      effectiveRuntime: bundle.effectiveRuntime,
+      enforce: bundle.enforce,
+      trust: bundle.trust,
+      mountedAt: bundle.mountedAt
+    },
+    null,
+    2
+  );
+}
+
+/**
+ * @param {string} cwd
+ */
+export function readMountManifest(cwd) {
+  const manifestPath = path.join(cwd, MOUNT_MANIFEST_RELATIVE);
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return parsed?.schema === RUNTIME_MOUNT_SCHEMA ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {import('./runtime-mount.js').RuntimeBundle} bundle
+ * @param {string} cwd
+ */
+export function writeMountManifest(bundle, cwd) {
+  const dir = path.join(cwd, '.neus');
+  fs.mkdirSync(dir, { recursive: true });
+  const manifestPath = path.join(dir, 'mount.json');
+  fs.writeFileSync(manifestPath, `${JSON.stringify(bundle, null, 2)}\n`, 'utf8');
+  return manifestPath;
+}
+
+/**
+ * @param {'cursor' | 'claude' | 'codex'} flavor
+ * @param {import('./runtime-mount.js').RuntimeBundle} bundle
+ * @param {string} cwd
+ * @param {{ dryRun?: boolean }} [options]
+ */
+export function applyRuntimeBundle(flavor, bundle, cwd, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const safeId = sanitizeAgentIdForFilename(bundle.identity.agentId);
+  const written = [];
+
+  const manifestPath = dryRun
+    ? path.join(cwd, MOUNT_MANIFEST_RELATIVE)
+    : writeMountManifest(bundle, cwd);
+  written.push(manifestPath);
+
+  if (flavor === 'cursor') {
+    const rulesDir = path.join(cwd, '.cursor', 'rules');
+    const rulesPath = path.join(rulesDir, `neus-agent-${safeId}.mdc`);
+    if (!dryRun) {
+      fs.mkdirSync(rulesDir, { recursive: true });
+      fs.writeFileSync(rulesPath, bundleToCursorRules(bundle), 'utf8');
+    }
+    written.push(rulesPath);
+    return { flavor, written, primary: rulesPath, manifestPath };
+  }
+
+  if (flavor === 'claude') {
+    const claudePath = path.join(cwd, '.claude', 'NEUS_AGENT.md');
+    if (!dryRun) {
+      fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
+      fs.writeFileSync(claudePath, bundleToClaudeMd(bundle), 'utf8');
+    }
+    written.push(claudePath);
+    return { flavor, written, primary: claudePath, manifestPath };
+  }
+
+  if (flavor === 'codex') {
+    const codexPath = path.join(cwd, '.neus', `codex-agent-${safeId}.json`);
+    if (!dryRun) {
+      fs.mkdirSync(path.join(cwd, '.neus'), { recursive: true });
+      fs.writeFileSync(codexPath, bundleToCodexJson(bundle), 'utf8');
+    }
+    written.push(codexPath);
+    return { flavor, written, primary: codexPath, manifestPath };
+  }
+
+  throw new Error(`Unsupported runtime adapter: ${flavor}`);
+}