@agirails/sdk 2.2.2 → 2.3.0

package/src/cli/commands/diff.ts

@@ -0,0 +1,141 @@
+/**
+ * Diff Command - Compare local AGIRAILS.md with on-chain config
+ *
+ * Shows sync status between local file and AgentRegistry state.
+ * Terraform-style: never auto-overwrites, just shows differences.
+ *
+ * @module cli/commands/diff
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { ethers } from 'ethers';
+import { diff } from '../../config/syncOperations';
+import { getNetwork } from '../../config/networks';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createDiffCommand(): Command {
+  const cmd = new Command('diff')
+    .description('Compare local AGIRAILS.md with on-chain config')
+    .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-a, --address <address>', 'Agent address to compare with')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only sync status')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runDiff(path, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface DiffCommandOptions {
+  network: string;
+  address?: string;
+}
+
+async function runDiff(
+  filePath: string,
+  options: DiffCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  // Determine agent address
+  let agentAddress = options.address;
+  if (!agentAddress) {
+    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
+    if (!privateKey) {
+      output.error('Agent address required. Use --address or set ACTP_PRIVATE_KEY env var.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+    agentAddress = new ethers.Wallet(privateKey).address;
+  }
+
+  const networkConfig = getNetwork(options.network);
+  if (!networkConfig.contracts.agentRegistry) {
+    output.error(`AgentRegistry not deployed on ${options.network}`);
+    process.exit(ExitCode.ERROR);
+  }
+
+  const spinner = output.spinner('Comparing local and on-chain config...');
+
+  try {
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+
+    const result = await diff({
+      path: resolvedPath,
+      agentAddress,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      provider,
+    });
+
+    spinner.stop(true);
+
+    output.result(
+      {
+        status: result.status,
+        inSync: result.inSync,
+        localHash: result.localHash,
+        onChainHash: result.onChainHash,
+        onChainCID: result.onChainCID || null,
+        hasLocalFile: result.hasLocalFile,
+        hasOnChainConfig: result.hasOnChainConfig,
+        network: options.network,
+        agent: agentAddress,
+      },
+      { quietKey: 'status' }
+    );
+
+    output.blank();
+
+    // Human-friendly status messages
+    switch (result.status) {
+      case 'in-sync':
+        output.success('Local and on-chain configs are in sync.');
+        break;
+      case 'local-ahead':
+        output.warning('Local changes not yet published. Run: actp publish');
+        break;
+      case 'remote-ahead':
+        output.warning('On-chain config is newer. Run: actp pull');
+        break;
+      case 'diverged':
+        output.warning('Local and on-chain configs have diverged.');
+        output.print('  Resolve by running: actp publish (to push local) or actp pull --force (to accept remote)');
+        break;
+      case 'no-local':
+        output.info('No local AGIRAILS.md found. Run: actp pull');
+        break;
+      case 'no-remote':
+        output.info('No config published on-chain. Run: actp publish');
+        break;
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

package/src/cli/commands/init.ts

@@ -10,6 +10,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as readline from 'readline';
 import { Command } from 'commander';
 import {
   saveConfig,
@@ -102,10 +103,10 @@ async function runInit(options: InitOptions, output: Output): Promise<void> {
       address = '0x' + crypto.randomBytes(20).toString('hex');
       output.info(`Generated mock address: ${address}`);
     } else {
-      throw new Error(
-        `Address required for ${mode} mode.\n` +
-          'Use --address <your-address> to specify.'
-      );
+      // Generate a real wallet with encrypted keystore
+      const actpDir = getActpDir(projectRoot);
+      fs.mkdirSync(actpDir, { recursive: true });
+      address = await generateWallet(actpDir, output);
     }
   }
 
@@ -177,6 +178,66 @@ async function runInit(options: InitOptions, output: Output): Promise<void> {
   }
 }
 
+// ============================================================================
+// Wallet Generation
+// ============================================================================
+
+async function generateWallet(actpDir: string, output: Output): Promise<string> {
+  const { Wallet } = await import('ethers');
+
+  const wallet = Wallet.createRandom();
+
+  // Get password from env var or interactive prompt
+  let password = process.env.ACTP_KEY_PASSWORD;
+  if (!password) {
+    password = await promptPassword();
+  }
+
+  if (!password || password.length < 8) {
+    throw new Error(
+      'Wallet password required (minimum 8 characters).\n' +
+        'Set ACTP_KEY_PASSWORD env var or enter when prompted.'
+    );
+  }
+
+  // Encrypt with Keystore V3 (scrypt + AES-128-CTR)
+  output.info('Encrypting wallet (this takes a few seconds)...');
+  const keystore = await wallet.encrypt(password);
+
+  // Save with restrictive permissions
+  const keystorePath = path.join(actpDir, 'keystore.json');
+  fs.writeFileSync(keystorePath, keystore, { mode: 0o600 });
+
+  output.success('Key securely saved and encrypted');
+  output.info(`Address: ${wallet.address}`);
+  output.warning('Back up your password — it cannot be recovered.');
+  output.info('');
+  output.info('To start your agent:');
+  output.info('  export ACTP_KEY_PASSWORD="your-password"');
+  output.info('  npx ts-node agent.ts');
+
+  return wallet.address;
+}
+
+async function promptPassword(): Promise<string> {
+  // If not a TTY (e.g. piped or run by agent), skip prompt
+  if (!process.stdin.isTTY) {
+    return '';
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Enter password for wallet encryption (min 8 chars): ', (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
 // ============================================================================
 // Scaffold
 // ============================================================================

package/src/cli/commands/publish.ts

@@ -0,0 +1,209 @@
+/**
+ * Publish Command - Publish AGIRAILS.md config on-chain
+ *
+ * Reads AGIRAILS.md, computes canonical hash, uploads to IPFS,
+ * optionally to Arweave, and records on AgentRegistry.
+ *
+ * @module cli/commands/publish
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { ethers } from 'ethers';
+import { computeConfigHash, parseAgirailsMd, serializeAgirailsMd } from '../../config/agirailsmd';
+import { AgentRegistryClient } from '../../registry/AgentRegistryClient';
+import { FilebaseClient } from '../../storage/FilebaseClient';
+import { ArweaveClient } from '../../storage/ArweaveClient';
+import { getNetwork } from '../../config/networks';
+import { publishAgirailsMd, PENDING_ENDPOINT } from '../../config/publishPipeline';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createPublishCommand(): Command {
+  const cmd = new Command('publish')
+    .description('Publish AGIRAILS.md config on-chain')
+    .argument('[path]', 'Path to AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('--skip-arweave', 'Skip permanent Arweave storage (dev mode)')
+    .option('--dry-run', 'Show what would happen without executing')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Output only the config hash')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runPublish(path, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface PublishCommandOptions {
+  network: string;
+  skipArweave?: boolean;
+  dryRun?: boolean;
+}
+
+async function runPublish(
+  filePath: string,
+  options: PublishCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    output.error(`File not found: ${filePath}`);
+    process.exit(ExitCode.INVALID_INPUT);
+  }
+
+  const spinner = output.spinner('Reading AGIRAILS.md...');
+
+  try {
+    // Read and compute hash
+    const content = readFileSync(resolvedPath, 'utf-8');
+    const { configHash, structuredHash, bodyHash } = computeConfigHash(content);
+
+    if (options.dryRun) {
+      spinner.stop(true);
+
+      output.result(
+        {
+          configHash,
+          structuredHash,
+          bodyHash,
+          path: resolvedPath,
+          network: options.network,
+          dryRun: true,
+        },
+        { quietKey: 'configHash' }
+      );
+
+      output.blank();
+      output.success('Dry run complete. No changes made.');
+      return;
+    }
+
+    // Validate environment
+    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
+    if (!privateKey) {
+      spinner.stop(false);
+      output.error('Private key required. Set ACTP_PRIVATE_KEY or PRIVATE_KEY env var.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+
+    const networkConfig = getNetwork(options.network);
+    if (!networkConfig.contracts.agentRegistry) {
+      spinner.stop(false);
+      output.error(`AgentRegistry not deployed on ${options.network}`);
+      process.exit(ExitCode.ERROR);
+    }
+
+    // Create provider and signer
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+    const signer = new ethers.Wallet(privateKey, provider);
+
+    // Create Filebase client
+    const filebaseAccessKey = process.env.FILEBASE_ACCESS_KEY;
+    const filebaseSecretKey = process.env.FILEBASE_SECRET_KEY;
+    if (!filebaseAccessKey || !filebaseSecretKey) {
+      spinner.stop(false);
+      output.error('Filebase credentials required. Set FILEBASE_ACCESS_KEY and FILEBASE_SECRET_KEY.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+
+    const filebaseClient = new FilebaseClient({
+      accessKey: filebaseAccessKey,
+      secretKey: filebaseSecretKey,
+    });
+
+    // Create Arweave client (optional)
+    let arweaveClient: ArweaveClient | undefined;
+    if (!options.skipArweave) {
+      const arweaveKey = process.env.ARCHIVE_UPLOADER_KEY;
+      if (arweaveKey) {
+        arweaveClient = await ArweaveClient.create({
+          privateKey: arweaveKey,
+          rpcUrl: networkConfig.rpcUrl,
+        });
+      }
+    }
+
+    spinner.stop(true);
+    const publishSpinner = output.spinner('Publishing to IPFS + on-chain...');
+
+    const result = await publishAgirailsMd({
+      path: resolvedPath,
+      network: options.network,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      signer,
+      filebaseClient,
+      arweaveClient,
+      skipArweave: options.skipArweave || !arweaveClient,
+      gasSettings: {
+        maxFeePerGas: networkConfig.gasSettings.maxFeePerGas,
+        maxPriorityFeePerGas: networkConfig.gasSettings.maxPriorityFeePerGas,
+      },
+    });
+
+    publishSpinner.stop(true);
+
+    output.result(
+      {
+        configHash: result.configHash,
+        cid: result.cid,
+        txHash: result.txHash,
+        arweaveTxId: result.arweaveTxId || null,
+        registered: result.registered || false,
+        network: options.network,
+      },
+      { quietKey: 'configHash' }
+    );
+
+    output.blank();
+    if (result.registered) {
+      output.success('Agent registered and config published!');
+    } else {
+      output.success('Config published successfully!');
+    }
+    output.print('');
+    output.print('Next steps:');
+    output.print('  - Verify sync:  actp diff');
+    output.print('  - View on-chain: ' + networkConfig.blockExplorer + '/tx/' + result.txHash);
+
+    // Warn if placeholder endpoint was used during auto-register
+    if (result.registered) {
+      const content = readFileSync(resolvedPath, 'utf-8');
+      const { frontmatter } = parseAgirailsMd(content);
+      if (!frontmatter.endpoint || frontmatter.endpoint === PENDING_ENDPOINT) {
+        output.print('');
+        output.warning('No endpoint in AGIRAILS.md — registered with placeholder URL.');
+        output.print('  Update when your agent is deployed:');
+        output.print('    1. Add "endpoint: https://your-agent.com/webhook" to AGIRAILS.md');
+        output.print('    2. Run: actp publish');
+      }
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

package/src/cli/commands/pull.ts

@@ -0,0 +1,124 @@
+/**
+ * Pull Command - Pull on-chain config to local AGIRAILS.md
+ *
+ * Fetches the published AGIRAILS.md from IPFS (via on-chain CID),
+ * verifies integrity against on-chain hash, and writes locally.
+ * Use --force to overwrite existing file without confirmation.
+ *
+ * @module cli/commands/pull
+ */
+
+import { Command } from 'commander';
+import { Output, ExitCode } from '../utils/output';
+import { mapError } from '../utils/client';
+import { resolve } from 'path';
+import { ethers } from 'ethers';
+import { pull } from '../../config/syncOperations';
+import { getNetwork } from '../../config/networks';
+
+// ============================================================================
+// Command Definition
+// ============================================================================
+
+export function createPullCommand(): Command {
+  const cmd = new Command('pull')
+    .description('Pull on-chain AGIRAILS.md config to local file')
+    .argument('[path]', 'Path to write AGIRAILS.md', './AGIRAILS.md')
+    .option('-n, --network <network>', 'Network (base-sepolia | base-mainnet)', 'base-sepolia')
+    .option('-a, --address <address>', 'Agent address to pull config for')
+    .option('--force', 'Overwrite without confirmation (CI mode)')
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Minimal output')
+    .action(async (path, options) => {
+      const output = new Output(
+        options.json ? 'json' : options.quiet ? 'quiet' : 'human'
+      );
+
+      try {
+        await runPull(path, options, output);
+      } catch (error) {
+        const structuredError = mapError(error);
+        output.errorResult({
+          code: structuredError.code,
+          message: structuredError.message,
+          details: structuredError.details,
+        });
+        process.exit(ExitCode.ERROR);
+      }
+    });
+
+  return cmd;
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+interface PullCommandOptions {
+  network: string;
+  address?: string;
+  force?: boolean;
+}
+
+async function runPull(
+  filePath: string,
+  options: PullCommandOptions,
+  output: Output
+): Promise<void> {
+  const resolvedPath = resolve(filePath);
+
+  // Determine agent address
+  let agentAddress = options.address;
+  if (!agentAddress) {
+    const privateKey = process.env.ACTP_PRIVATE_KEY || process.env.PRIVATE_KEY;
+    if (!privateKey) {
+      output.error('Agent address required. Use --address or set ACTP_PRIVATE_KEY env var.');
+      process.exit(ExitCode.INVALID_INPUT);
+    }
+    agentAddress = new ethers.Wallet(privateKey).address;
+  }
+
+  const networkConfig = getNetwork(options.network);
+  if (!networkConfig.contracts.agentRegistry) {
+    output.error(`AgentRegistry not deployed on ${options.network}`);
+    process.exit(ExitCode.ERROR);
+  }
+
+  const spinner = output.spinner('Pulling config from on-chain...');
+
+  try {
+    const provider = new ethers.JsonRpcProvider(networkConfig.rpcUrl);
+
+    const result = await pull({
+      path: resolvedPath,
+      agentAddress,
+      registryAddress: networkConfig.contracts.agentRegistry,
+      provider,
+      force: options.force,
+    });
+
+    spinner.stop(result.written);
+
+    output.result(
+      {
+        written: result.written,
+        cid: result.cid || null,
+        status: result.status,
+        path: resolvedPath,
+        network: options.network,
+      },
+      { quietKey: 'status' }
+    );
+
+    if (result.written) {
+      output.blank();
+      output.success(`Config pulled and written to ${filePath}`);
+    } else {
+      output.blank();
+      output.info(result.status);
+    }
+  } catch (error) {
+    spinner.stop(false);
+    throw error;
+  }
+}

package/src/cli/index.ts

@@ -48,6 +48,9 @@ import { createWatchCommand } from './commands/watch';
 import { createSimulateCommand } from './commands/simulate';
 import { createBatchCommand } from './commands/batch';
 import { createTimeCommand } from './commands/time';
+import { createPublishCommand } from './commands/publish';
+import { createPullCommand } from './commands/pull';
+import { createDiffCommand } from './commands/diff';
 
 // ============================================================================
 // Program Setup
@@ -92,6 +95,11 @@ program.addCommand(createBatchCommand());
 // Mock mode utilities
 program.addCommand(createTimeCommand());
 
+// Config sync commands (AGIRAILS.md as source of truth)
+program.addCommand(createPublishCommand());
+program.addCommand(createPullCommand());
+program.addCommand(createDiffCommand());
+
 // ============================================================================
 // Error Handling
 // ============================================================================