spaps 0.9.0 → 0.9.1

package/src/handlers.js

@@ -509,9 +509,16 @@ function createHandlers(version, logo) {
     },
     doctor: async ({ options }) => {
       const { runDoctor } = loadDoctor();
-      await runDoctor({ port: options.port || DEFAULT_PORT, stripe: options.stripe || null, json: options.json });
+      await runDoctor({
+        port: options.port || DEFAULT_PORT,
+        serverUrl: options.serverUrl || null,
+        origin: options.origin || null,
+        stripe: options.stripe || null,
+        json: options.json,
+      });
     },
     test: verifyHandler,
+    auth: async (...args) => loadAuthCommandHandlers().authHandler(...args),
     login: async (...args) => loadAuthCommandHandlers().loginHandler(...args),
     logout: async (...args) => loadAuthCommandHandlers().logoutHandler(...args),
     whoami: async (...args) => loadAuthCommandHandlers().whoamiHandler(...args),
@@ -522,6 +529,11 @@ function createHandlers(version, logo) {
     policy: policyHandler,
     webhook: webhookHandler,
     'issue-reports': issueReportsHandler,
+    access: capabilityHandler,
+    journey: capabilityHandler,
+    graph: capabilityHandler,
+    explain: capabilityHandler,
+    contract: capabilityHandler,
   };
 }
 
@@ -593,6 +605,250 @@ function assignIfDefined(target, key, value) {
   }
 }
 
+function splitCsv(raw) {
+  if (!raw) return [];
+  return String(raw)
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function extractErrorObject(result) {
+  const candidates = [result?.raw, result?.data];
+  for (const candidate of candidates) {
+    if (!candidate || typeof candidate !== 'object') continue;
+    if (candidate.error && typeof candidate.error === 'object') return candidate.error;
+    if (typeof candidate.code === 'string' || typeof candidate.message === 'string') {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function extractErrorMessage(result) {
+  const error = extractErrorObject(result);
+  return (
+    error?.message ||
+    result?.data?.detail ||
+    (result?.status ? `HTTP ${result.status}` : 'Request failed')
+  );
+}
+
+function extractErrorCode(result) {
+  const error = extractErrorObject(result);
+  return error?.code || (result?.status ? `http_${result.status}` : 'request_failed');
+}
+
+function extractRequestId(result) {
+  const raw = result?.raw;
+  if (!raw || typeof raw !== 'object') return null;
+  return raw.request_id || raw.metadata?.request_id || null;
+}
+
+function extractSources(data) {
+  if (Array.isArray(data?.sources)) return data.sources;
+  if (Array.isArray(data?.decision?.sources)) return data.decision.sources;
+  return [];
+}
+
+function normalizeDiagnostic(item, fallbackStatus = null) {
+  const diagnostic = {
+    code: item?.code || (fallbackStatus ? `http_${fallbackStatus}` : 'request_failed'),
+    message: item?.message || 'Request failed',
+    status: item?.status ?? fallbackStatus,
+  };
+  assignIfDefined(diagnostic, 'details', item?.details);
+  return diagnostic;
+}
+
+function extractPayloadDiagnostics(result) {
+  const raw = result?.raw;
+  if (Array.isArray(raw?.diagnostics)) {
+    return raw.diagnostics.map((item) => normalizeDiagnostic(item, result?.status || null));
+  }
+  return [];
+}
+
+function extractRemediations(data) {
+  const actions = Array.isArray(data?.next_actions) ? data.next_actions : [];
+  return actions.map((action) => {
+    const remediation = {
+      kind: action.kind,
+      label: action.label || null,
+      method: action.method || null,
+      path: action.path || null,
+      cli: action.cli || null,
+      requires: Array.isArray(action.requires) ? action.requires : [],
+    };
+    assignIfDefined(remediation, 'command_template', action.command_template);
+    assignIfDefined(remediation, 'safe_to_execute', action.safe_to_execute);
+    assignIfDefined(remediation, 'operator_gate_required', action.operator_gate_required);
+    return remediation;
+  });
+}
+
+function normalizeRemediation(item) {
+  const remediation = {
+    kind: item.kind,
+    label: item.label || null,
+    method: item.method || null,
+    path: item.path || null,
+    cli: item.cli || null,
+    requires: Array.isArray(item.requires) ? item.requires : [],
+  };
+  assignIfDefined(remediation, 'details', item.details);
+  assignIfDefined(remediation, 'command_template', item.command_template);
+  assignIfDefined(remediation, 'safe_to_execute', item.safe_to_execute);
+  assignIfDefined(remediation, 'operator_gate_required', item.operator_gate_required);
+  return remediation;
+}
+
+function extractPayloadRemediations(result) {
+  const raw = result?.raw;
+  if (!Array.isArray(raw?.remediations)) return [];
+  return raw.remediations
+    .filter((item) => item && typeof item === 'object' && item.kind)
+    .map((item) => normalizeRemediation(item));
+}
+
+function capabilityEnvelope({ command, result, data = null, success = null, diagnostics = [] }) {
+  const resolvedData = data === null && result ? result.data : data;
+  const ok = success === null ? Boolean(result?.ok) : Boolean(success);
+  const envelopeDiagnostics = Array.isArray(diagnostics) ? diagnostics.slice() : [];
+  envelopeDiagnostics.push(...extractPayloadDiagnostics(result));
+  if (result && !result.ok) {
+    const hasServerDiagnostic = envelopeDiagnostics.length > 0;
+    if (!hasServerDiagnostic) {
+      const error = extractErrorObject(result);
+      const diagnostic = {
+        code: extractErrorCode(result),
+        message: extractErrorMessage(result),
+        status: result.status || null,
+      };
+      assignIfDefined(diagnostic, 'details', error?.details);
+      envelopeDiagnostics.push(diagnostic);
+    }
+  }
+  const payloadRemediations = extractPayloadRemediations(result);
+  const envelope = {
+    schema_version: 'spaps.cli.capability.v1',
+    command,
+    success: ok,
+    status: result?.status || null,
+    data: resolvedData,
+    diagnostics: envelopeDiagnostics,
+    remediations: payloadRemediations.length ? payloadRemediations : extractRemediations(resolvedData),
+    sources: extractSources(resolvedData),
+  };
+  assignIfDefined(envelope, 'request_id', extractRequestId(result));
+  assignIfDefined(envelope, 'timestamp', result?.raw?.timestamp);
+  return envelope;
+}
+
+function emitCapability({ command, result, isJson, exitCodeOnFailure = 10 }) {
+  if (isJson) {
+    console.log(JSON.stringify(capabilityEnvelope({ command, result }), null, 2));
+  } else if (!result.ok) {
+    console.error(`\u2717 ${command}: ${extractErrorMessage(result)}`);
+  } else {
+    const data = result.data || {};
+    if (typeof data.allowed === 'boolean') {
+      console.log(`${command}: ${data.allowed ? 'allowed' : data.outcome || 'not allowed'}`);
+      (data.reasons || []).forEach((reason) => {
+        console.log(`  - ${reason.message || reason.code}`);
+      });
+    } else if (typeof data.status === 'string' && typeof data.allowed === 'boolean') {
+      console.log(`${command}: ${data.status}`);
+    } else {
+      console.log(JSON.stringify(data, null, 2));
+    }
+  }
+  if (!result.ok) {
+    process.exitCode = exitCodeOnFailure;
+  }
+}
+
+function emitCapabilityError({ command, err, isJson, exitCode = 10 }) {
+  const message = err && err.message ? err.message : String(err);
+  const code = err && err.code ? err.code : 'ERROR';
+  if (isJson) {
+    console.log(JSON.stringify({
+      schema_version: 'spaps.cli.capability.v1',
+      command,
+      success: false,
+      status: err?.status || null,
+      data: null,
+      diagnostics: [{ code, message, status: err?.status || null }],
+      remediations: code === 'NOT_AUTHENTICATED' || code === 'SESSION_EXPIRED'
+        ? [{ kind: 'authenticate', label: 'Run spaps login', cli: 'spaps login', requires: ['operator'] }]
+        : [],
+      sources: [],
+    }, null, 2));
+  } else {
+    const hint = code === 'NOT_AUTHENTICATED' || code === 'SESSION_EXPIRED'
+      ? ' (run `spaps login` first)'
+      : '';
+    console.error(`\u2717 ${command}: ${message}${hint}`);
+  }
+  process.exitCode = exitCode;
+}
+
+function buildAccessDecisionPayload(options, prefix) {
+  if (!requireOption(options.action, `${prefix}: --action is required`)) return null;
+  if (!requireOption(options.resourceType, `${prefix}: --resource-type is required`)) return null;
+  if (!requireOption(options.resourceRef, `${prefix}: --resource-ref is required`)) return null;
+
+  const context = parseJsonFlag(options.context, `${prefix}: --context`);
+  if (!context.ok) return null;
+  const policyContext = parseJsonFlag(options.policyContext, `${prefix}: --policy-context`);
+  if (!policyContext.ok) return null;
+  const usageDimensions = parseJsonFlag(options.usageDimensions, `${prefix}: --usage-dimensions`);
+  if (!usageDimensions.ok) return null;
+  const authenticated = parseBooleanFlag(options.authenticated, `${prefix}: --authenticated`);
+  if (!authenticated.ok) return null;
+
+  const actor = {
+    actor_type: options.actorType || 'user',
+  };
+  assignIfDefined(actor, 'actor_ref', options.actorRef);
+  assignIfDefined(actor, 'user_id', options.userId);
+  assignIfDefined(actor, 'email', options.email);
+  assignIfDefined(actor, 'agent_id', options.agentId);
+  assignIfDefined(actor, 'authenticated', authenticated.value);
+
+  const resource = {
+    resource_type: options.resourceType,
+    resource_ref: options.resourceRef,
+  };
+  assignIfDefined(resource, 'resource_id', options.resourceId);
+  assignIfDefined(resource, 'resource_key', options.resourceKey);
+
+  const controls = {
+    approval_required: Boolean(options.approvalRequired),
+    authority_scope: options.authorityScope || 'application',
+  };
+  assignIfDefined(controls, 'entitlement_key', options.entitlementKey);
+  assignIfDefined(controls, 'entitlement_resource_type', options.entitlementResourceType);
+  assignIfDefined(controls, 'entitlement_resource_id', options.entitlementResourceId);
+  assignIfDefined(controls, 'policy_name', options.policyName);
+  assignIfDefined(controls, 'policy_context', policyContext.value);
+  assignIfDefined(controls, 'usage_feature_key', options.usageFeatureKey);
+  assignIfDefined(controls, 'usage_dimensions', usageDimensions.value);
+  assignIfDefined(controls, 'x402_resource_key', options.x402ResourceKey);
+  assignIfDefined(controls, 'approval_id', options.approvalId);
+
+  const payload = {
+    actor,
+    action: options.action,
+    resource,
+    controls,
+    context: context.value || {},
+  };
+  assignIfDefined(payload, 'idempotency_key', options.idempotencyKey);
+  assignIfDefined(payload, 'correlation_id', options.correlationId);
+  return payload;
+}
+
 async function dayrateHandler({ options }) {
   const { callEndpoint, emit, emitAuthError } = loadDomainCli();
   const isJson = Boolean(options.json);
@@ -983,4 +1239,137 @@ async function issueReportsHandler({ options }) {
   }
 }
 
+async function capabilityHandler({ name, options }) {
+  const { callEndpoint } = loadDomainCli();
+  const isJson = Boolean(options.json);
+  const command = name === 'access'
+    ? `access.${options.subcommand || 'unknown'}`
+    : name === 'journey'
+      ? `journey.${options.subcommand || 'unknown'}`
+      : name === 'graph'
+        ? `graph.${options.subcommand || 'unknown'}`
+        : name;
+
+  try {
+    if (name === 'access') {
+      if (options.subcommand !== 'check') {
+        console.error('access: unknown subcommand. Supported: check');
+        process.exitCode = 2;
+        return;
+      }
+      const body = buildAccessDecisionPayload(options, 'access check');
+      if (!body) return;
+      const result = await callEndpoint({
+        options,
+        method: 'POST',
+        path: '/api/access/decide',
+        body,
+      });
+      emitCapability({ command, result, isJson, exitCodeOnFailure: 10 });
+      return;
+    }
+
+    if (name === 'journey') {
+      if (options.subcommand !== 'run') {
+        console.error('journey: unknown subcommand. Supported: run');
+        process.exitCode = 2;
+        return;
+      }
+      const access = buildAccessDecisionPayload(options, 'journey run');
+      if (!access) return;
+      const operatorLabels = splitCsv(options.operatorLabels)
+        .filter((label) => label.toLowerCase() !== 'operator-gated');
+      const body = {
+        access,
+        include_command_templates: Boolean(options.includeCommandTemplates),
+        operator_labels: operatorLabels,
+        environment: options.environment || 'production',
+      };
+      const result = await callEndpoint({
+        options,
+        method: 'POST',
+        path: '/api/actions/prepare',
+        body,
+      });
+      emitCapability({ command, result, isJson, exitCodeOnFailure: 30 });
+      return;
+    }
+
+    if (name === 'graph') {
+      let result;
+      if (options.subcommand === 'nodes') {
+        const query = {};
+        assignIfDefined(query, 'node_type', options.nodeType);
+        assignIfDefined(query, 'status', options.status);
+        assignIfDefined(query, 'q', options.query);
+        assignIfDefined(query, 'cursor', options.cursor);
+        assignIfDefined(query, 'limit', options.limit);
+        assignIfDefined(query, 'application_id', options.applicationId);
+        result = await callEndpoint({ options, method: 'GET', path: '/api/graph/nodes', query });
+      } else if (options.subcommand === 'paths') {
+        const query = {
+          from_node_key: options.fromNodeKey,
+          to_node_key: options.toNodeKey,
+        };
+        assignIfDefined(query, 'max_depth', options.maxDepth);
+        assignIfDefined(query, 'limit', options.limit);
+        assignIfDefined(query, 'include_stale', options.includeStale);
+        assignIfDefined(query, 'application_id', options.applicationId);
+        result = await callEndpoint({ options, method: 'GET', path: '/api/graph/paths', query });
+      } else if (options.subcommand === 'impact') {
+        const query = {
+          node_key: options.nodeKey,
+        };
+        assignIfDefined(query, 'max_depth', options.maxDepth);
+        assignIfDefined(query, 'limit', options.limit);
+        assignIfDefined(query, 'include_stale', options.includeStale);
+        assignIfDefined(query, 'application_id', options.applicationId);
+        result = await callEndpoint({ options, method: 'GET', path: '/api/graph/impact', query });
+      } else if (options.subcommand === 'refresh') {
+        const query = {};
+        assignIfDefined(query, 'application_id', options.applicationId);
+        assignIfDefined(query, 'correlation_id', options.correlationId);
+        result = await callEndpoint({ options, method: 'POST', path: '/api/graph/refresh', query });
+      } else {
+        console.error('graph: unknown subcommand. Supported: nodes, paths, impact, refresh');
+        process.exitCode = 2;
+        return;
+      }
+      emitCapability({ command, result, isJson, exitCodeOnFailure: 10 });
+      return;
+    }
+
+    if (name === 'explain') {
+      if (!requireOption(options.decisionId, 'explain: <decision-id> is required')) return;
+      const result = await callEndpoint({
+        options,
+        method: 'GET',
+        path: `/api/graph/explain/${encodeURIComponent(options.decisionId)}`,
+      });
+      emitCapability({ command, result, isJson, exitCodeOnFailure: 10 });
+      return;
+    }
+
+    if (name === 'contract') {
+      const result = await callEndpoint({
+        options,
+        method: 'GET',
+        path: '/api/contract',
+      });
+      emitCapability({ command, result, isJson, exitCodeOnFailure: 20 });
+      return;
+    }
+
+    console.error('capability: unsupported command');
+    process.exitCode = 2;
+  } catch (err) {
+    emitCapabilityError({
+      command,
+      err,
+      isJson,
+      exitCode: name === 'contract' ? 20 : name === 'journey' ? 30 : 10,
+    });
+  }
+}
+
 module.exports = { createHandlers };

package/src/help-system.js

@@ -236,7 +236,7 @@ const HELP_TREE = {
 SPAPS (Sweet Potato Authentication & Payment Service) provides:
 
 1. **Authentication**: Email/password, magic links, and wallet-based auth
-2. **Payments**: Stripe subscriptions and wallet-based payments
+2. **Payments**: Stripe subscriptions and x402 paid-resource receipts
 3. **Local Development**: Zero-config local mode with auto-auth
 4. **Type Safety**: Full TypeScript support with generated types
 5. **Multi-tenant**: API key-based app isolation