@mandate.md/cli 0.1.0

package/src/__tests__/login.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('node:fs');
+vi.mock('node:os');
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(os.homedir).mockReturnValue('/home/test');
+  vi.mocked(fs.existsSync).mockReturnValue(false);
+  vi.mocked(fs.mkdirSync).mockReturnValue(undefined);
+  vi.mocked(fs.writeFileSync).mockReturnValue(undefined);
+  vi.mocked(fs.chmodSync).mockReturnValue(undefined);
+});
+
+describe('mandate login', () => {
+  it('registers agent and returns credentials', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 201,
+      json: () => Promise.resolve({
+        agentId: 'uuid-1',
+        runtimeKey: 'mndt_test_abc123xyz',
+        claimUrl: 'https://app.mandate.md/claim/uuid-1',
+        evmAddress: '0x1234567890abcdef1234567890abcdef12345678',
+        chainId: 84532,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve(['login', '--name', 'TestAgent', '--address', '0x1234567890abcdef1234567890abcdef12345678'], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('uuid-1');
+    expect(output).toContain('mndt_test_abc');
+    expect(output).not.toContain('mndt_test_abc123xyz'); // masked
+    expect(fs.writeFileSync).toHaveBeenCalled();
+    expect(fs.chmodSync).toHaveBeenCalledWith(expect.stringContaining('credentials.json'), 0o600);
+
+    vi.unstubAllGlobals();
+  });
+
+  it('passes defaultPolicy when limits provided', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 201,
+      json: () => Promise.resolve({
+        agentId: 'uuid-2',
+        runtimeKey: 'mndt_test_xyz789abc',
+        claimUrl: 'https://app.mandate.md/claim/uuid-2',
+        evmAddress: '0x0000000000000000000000000000000000000000',
+        chainId: 84532,
+      }),
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const { default: cli } = await import('../index.js');
+
+    await cli.serve(['login', '--name', 'LimitAgent', '--per-tx-limit', '100', '--daily-limit', '500'], {
+      stdout() {},
+      exit() {},
+    });
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    expect(body.defaultPolicy.spendLimitPerTxUsd).toBe(100);
+    expect(body.defaultPolicy.spendLimitPerDayUsd).toBe(500);
+
+    vi.unstubAllGlobals();
+  });
+});

package/src/__tests__/status.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('node:fs');
+vi.mock('node:os');
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+
+const CREDS = {
+  runtimeKey: 'mndt_test_abc123',
+  agentId: 'uuid-1',
+  claimUrl: 'http://x',
+  chainId: 84532,
+};
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(os.homedir).mockReturnValue('/home/test');
+  vi.mocked(fs.existsSync).mockReturnValue(true);
+  vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(CREDS));
+});
+
+describe('mandate status', () => {
+  it('returns intent status with CTA for reserved', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        intentId: 'intent-1',
+        status: 'reserved',
+        txHash: null,
+        blockNumber: null,
+        gasUsed: null,
+        amountUsd: null,
+        decodedAction: null,
+        summary: null,
+        blockReason: null,
+        requiresApproval: false,
+        approvalId: null,
+        expiresAt: null,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve(['status', 'intent-1'], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('reserved');
+    expect(output).toContain('mandate event');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('returns confirmed status with no CTA', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        intentId: 'intent-1',
+        status: 'confirmed',
+        txHash: '0xabc',
+        blockNumber: '100',
+        gasUsed: '50000',
+        amountUsd: '10.00',
+        decodedAction: 'transfer',
+        summary: null,
+        blockReason: null,
+        requiresApproval: false,
+        approvalId: null,
+        expiresAt: null,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve(['status', 'intent-1'], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('confirmed');
+    expect(output).toContain('0xabc');
+    // No next step for terminal state
+    expect(output).not.toContain('mandate event');
+    expect(output).not.toContain('mandate approve');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('shows approval CTA for approval_pending', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        intentId: 'intent-2',
+        status: 'approval_pending',
+        txHash: null,
+        blockNumber: null,
+        gasUsed: null,
+        amountUsd: null,
+        decodedAction: null,
+        summary: null,
+        blockReason: null,
+        requiresApproval: true,
+        approvalId: 'appr-1',
+        expiresAt: null,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve(['status', 'intent-2'], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('approval_pending');
+    expect(output).toContain('mandate approve');
+
+    vi.unstubAllGlobals();
+  });
+});

package/src/__tests__/transfer.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { encodeFunctionData, parseAbi } from 'viem';
+
+vi.mock('node:fs');
+vi.mock('node:os');
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+
+const CREDS = {
+  runtimeKey: 'mndt_test_abc123',
+  agentId: 'uuid-1',
+  claimUrl: 'http://x',
+  chainId: 84532,
+};
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(os.homedir).mockReturnValue('/home/test');
+  vi.mocked(fs.existsSync).mockReturnValue(true);
+  vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(CREDS));
+});
+
+describe('mandate transfer', () => {
+  it('encodes ERC20 calldata and validates', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        allowed: true,
+        intentId: 'intent-t1',
+        requiresApproval: false,
+        approvalId: null,
+        blockReason: null,
+      }),
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve([
+      'transfer',
+      '--to', '0x1234567890abcdef1234567890abcdef12345678',
+      '--amount', '10000000',
+      '--token', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--reason', 'Invoice #127',
+      '--nonce', '42',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+    ], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    // Verify the request body has encoded calldata
+    const body = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    expect(body.calldata).toContain('0xa9059cbb'); // transfer selector
+    expect(body.to).toBe('0x036CbD53842c5426634e7929541eC2318f3dCF7e'); // token contract, not recipient
+
+    expect(output).toContain('intent-t1');
+    expect(output).toContain('unsignedTx');
+    expect(output).toContain('calldata');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('returns blocked output on policy violation', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: false,
+      status: 422,
+      json: () => Promise.resolve({
+        blockReason: 'daily_limit_exceeded',
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve([
+      'transfer',
+      '--to', '0x1234567890abcdef1234567890abcdef12345678',
+      '--amount', '99999999999',
+      '--token', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--reason', 'Huge transfer',
+      '--nonce', '1',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+    ], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('POLICY_BLOCKED');
+    expect(output).toContain('daily_limit_exceeded');
+
+    vi.unstubAllGlobals();
+  });
+});

package/src/__tests__/validate.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { computeIntentHash } from '@mandate.md/sdk';
+
+vi.mock('node:fs');
+vi.mock('node:os');
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+
+const CREDS = {
+  runtimeKey: 'mndt_test_abc123',
+  agentId: 'uuid-1',
+  claimUrl: 'http://x',
+  chainId: 84532,
+};
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(os.homedir).mockReturnValue('/home/test');
+  vi.mocked(fs.existsSync).mockReturnValue(true);
+  vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(CREDS));
+});
+
+describe('mandate validate', () => {
+  it('returns ok when policy check passes', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        allowed: true,
+        intentId: 'intent-1',
+        requiresApproval: false,
+        approvalId: null,
+        blockReason: null,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve([
+      'validate',
+      '--to', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--calldata', '0xa9059cbb',
+      '--nonce', '42',
+      '--gas-limit', '90000',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+      '--reason', 'Invoice #127',
+    ], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('intent-1');
+    expect(output).toContain('ok');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('computes intentHash and sends it in request', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        allowed: true,
+        intentId: 'intent-1',
+        requiresApproval: false,
+        approvalId: null,
+        blockReason: null,
+      }),
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const { default: cli } = await import('../index.js');
+
+    await cli.serve([
+      'validate',
+      '--to', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--nonce', '42',
+      '--gas-limit', '90000',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+      '--reason', 'Test',
+    ], {
+      stdout() {},
+      exit() {},
+    });
+
+    const body = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    // Verify intentHash is present and is a hex string
+    expect(body.intentHash).toMatch(/^0x[a-f0-9]{64}$/);
+
+    // Verify it matches what computeIntentHash would produce
+    const expected = computeIntentHash({
+      chainId: 84532,
+      nonce: 42,
+      to: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' as `0x${string}`,
+      calldata: '0x',
+      valueWei: '0',
+      gasLimit: '90000',
+      maxFeePerGas: '1000000000',
+      maxPriorityFeePerGas: '1000000000',
+    });
+    expect(body.intentHash).toBe(expected);
+
+    vi.unstubAllGlobals();
+  });
+
+  it('returns blocked output on PolicyBlockedError', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: false,
+      status: 422,
+      json: () => Promise.resolve({
+        blockReason: 'per_tx_limit_exceeded',
+        blockDetail: '$150 exceeds $100/tx limit',
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve([
+      'validate',
+      '--to', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--nonce', '1',
+      '--gas-limit', '90000',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+      '--reason', 'Big payment',
+    ], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('POLICY_BLOCKED');
+    expect(output).toContain('per_tx_limit_exceeded');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('returns approval required output', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve({
+        allowed: true,
+        intentId: 'intent-2',
+        requiresApproval: true,
+        approvalId: 'approval-1',
+        blockReason: null,
+      }),
+    }));
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    await cli.serve([
+      'validate',
+      '--to', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--nonce', '1',
+      '--gas-limit', '90000',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+      '--reason', 'Big payment needing approval',
+    ], {
+      stdout(s: string) { output += s; },
+      exit() {},
+    });
+
+    expect(output).toContain('requiresApproval');
+    expect(output).toContain('intent-2');
+    expect(output).toContain('approve');
+
+    vi.unstubAllGlobals();
+  });
+
+  it('requires auth middleware (no creds = error)', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+
+    const { default: cli } = await import('../index.js');
+
+    let output = '';
+    let exitCode: number | undefined;
+    await cli.serve([
+      'validate',
+      '--to', '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      '--nonce', '1',
+      '--gas-limit', '90000',
+      '--max-fee-per-gas', '1000000000',
+      '--max-priority-fee-per-gas', '1000000000',
+      '--reason', 'Test',
+    ], {
+      stdout(s: string) { output += s; },
+      exit(code: number) { exitCode = code; },
+    });
+
+    expect(output).toContain('NOT_AUTHENTICATED');
+  });
+});

package/src/commands/activate.ts

@@ -0,0 +1,41 @@
+import { z } from 'incur';
+import { updateCredentials } from '../credentials.js';
+import type { CommandDef } from './types.js';
+
+export const activateCommand: CommandDef = {
+  description: 'Set EVM address after registration',
+  args: z.object({
+    address: z.string().describe('EVM address (0x...)'),
+  }),
+  examples: [
+    { args: { address: '0x1234567890abcdef1234567890abcdef12345678' }, description: 'Set wallet address' },
+  ],
+  async run(c: any) {
+    const { address } = c.args;
+    const client = c.var.client;
+
+    const res = await fetch(`${c.var.credentials.baseUrl ?? 'https://app.mandate.md'}/api/activate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${c.var.credentials.runtimeKey}`,
+      },
+      body: JSON.stringify({ evmAddress: address }),
+    });
+
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      return c.error({ code: 'ACTIVATE_FAILED', message: data.message ?? 'Activation failed' });
+    }
+
+    const data = await res.json();
+    updateCredentials({ evmAddress: data.evmAddress });
+
+    return {
+      activated: true,
+      evmAddress: data.evmAddress,
+      onboardingUrl: data.onboardingUrl,
+      next: 'Run: mandate validate (start validating transactions)',
+    };
+  },
+};

package/src/commands/approve.ts

@@ -0,0 +1,39 @@
+import { z } from 'incur';
+import type { CommandDef } from './types.js';
+
+export const approveCommand: CommandDef = {
+  description: 'Wait for owner approval on a pending intent',
+  args: z.object({
+    intentId: z.string().describe('Intent ID awaiting approval'),
+  }),
+  options: z.object({
+    timeout: z.number().optional().describe('Timeout in seconds (default: 3600)'),
+  }),
+  examples: [
+    { args: { intentId: 'uuid-1' }, description: 'Wait for approval' },
+  ],
+  async run(c: any) {
+    const client = c.var.client;
+    const timeoutMs = (c.options.timeout ?? 3600) * 1000;
+
+    const status = await client.waitForApproval(c.args.intentId, {
+      timeoutMs,
+      onPoll: () => {},
+    });
+
+    if (status.status === 'approved' || status.status === 'confirmed') {
+      return {
+        status: 'approved',
+        intentId: c.args.intentId,
+        feedback: '\u2705 Approved \u2014 ready to broadcast',
+        next: `Run: mandate event ${c.args.intentId} --tx-hash 0x...`,
+      };
+    }
+
+    return {
+      status: status.status,
+      intentId: c.args.intentId,
+      feedback: `Intent ended with status: ${status.status}`,
+    };
+  },
+};

package/src/commands/event.ts

@@ -0,0 +1,25 @@
+import { z } from 'incur';
+import type { CommandDef } from './types.js';
+
+export const eventCommand: CommandDef = {
+  description: 'Post txHash after signing and broadcasting',
+  args: z.object({
+    intentId: z.string().describe('Intent ID from validate'),
+  }),
+  options: z.object({
+    txHash: z.string().describe('Transaction hash (0x...)'),
+  }),
+  examples: [
+    { args: { intentId: 'uuid-1' }, options: { txHash: '0xabc123' }, description: 'Post transaction hash' },
+  ],
+  async run(c: any) {
+    const client = c.var.client;
+    await client.postEvent(c.args.intentId, c.options.txHash as `0x${string}`);
+
+    return {
+      posted: true,
+      intentId: c.args.intentId,
+      next: `Run: mandate status ${c.args.intentId}`,
+    };
+  },
+};

package/src/commands/login.ts

@@ -0,0 +1,55 @@
+import { z } from 'incur';
+import { MandateClient } from '@mandate.md/sdk';
+import { saveCredentials } from '../credentials.js';
+import type { CommandDef } from './types.js';
+
+export const loginCommand: CommandDef = {
+  description: 'Register a new agent and store credentials',
+  options: z.object({
+    name: z.string().describe('Agent name'),
+    address: z.string().optional().describe('EVM address (0x...)'),
+    perTxLimit: z.number().optional().describe('Per-transaction USD limit'),
+    dailyLimit: z.number().optional().describe('Daily USD limit'),
+    baseUrl: z.string().optional().describe('Mandate API base URL'),
+    chainId: z.number().optional().describe('Chain ID (default: 84532)'),
+  }),
+  alias: { perTxLimit: 'p', dailyLimit: 'd' },
+  examples: [
+    { options: { name: 'MyAgent', address: '0x1234567890abcdef1234567890abcdef12345678' }, description: 'Register with address' },
+    { options: { name: 'MyAgent' }, description: 'Register without address (set later via activate)' },
+  ],
+  async run(c: any) {
+    const { name, address, perTxLimit, dailyLimit, baseUrl, chainId } = c.options;
+
+    const defaultPolicy: Record<string, number> = {};
+    if (perTxLimit !== undefined) defaultPolicy.spendLimitPerTxUsd = perTxLimit;
+    if (dailyLimit !== undefined) defaultPolicy.spendLimitPerDayUsd = dailyLimit;
+
+    const result = await MandateClient.register({
+      name,
+      evmAddress: (address ?? '0x0000000000000000000000000000000000000000') as `0x${string}`,
+      chainId: chainId ?? 84532,
+      defaultPolicy: Object.keys(defaultPolicy).length ? defaultPolicy : undefined,
+      baseUrl,
+    });
+
+    saveCredentials({
+      runtimeKey: result.runtimeKey,
+      agentId: result.agentId,
+      claimUrl: result.claimUrl,
+      evmAddress: result.evmAddress,
+      chainId: result.chainId,
+      baseUrl,
+    });
+
+    const masked = result.runtimeKey.slice(0, 14) + '...' + result.runtimeKey.slice(-3);
+
+    return {
+      agentId: result.agentId,
+      runtimeKey: masked,
+      claimUrl: result.claimUrl,
+      evmAddress: result.evmAddress || undefined,
+      next: 'Run: mandate whoami (verify) or mandate validate (first tx)',
+    };
+  },
+};

package/src/commands/status.ts

@@ -0,0 +1,28 @@
+import { z } from 'incur';
+import type { CommandDef } from './types.js';
+
+const CTA: Record<string, string> = {
+  reserved: 'Run: mandate event <intentId> --tx-hash 0x...',
+  approval_pending: 'Run: mandate approve <intentId>',
+  broadcasted: 'Run: mandate status <intentId> (poll again)',
+};
+
+export const statusCommand: CommandDef = {
+  description: 'Check intent state',
+  args: z.object({
+    intentId: z.string().describe('Intent ID'),
+  }),
+  examples: [
+    { args: { intentId: 'uuid-1' }, description: 'Check status of an intent' },
+  ],
+  async run(c: any) {
+    const client = c.var.client;
+    const status = await client.getStatus(c.args.intentId);
+
+    const result: Record<string, unknown> = { ...status };
+    const cta = CTA[status.status];
+    if (cta) result.next = cta;
+
+    return result;
+  },
+};