@paylobster/cli 4.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,368 @@
+# Contributing to PayLobster CLI
+
+Thank you for your interest in contributing to the PayLobster CLI! This document provides guidelines and instructions for contributors.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- npm or yarn
+- TypeScript knowledge
+- Basic understanding of blockchain/Web3
+
+### Clone and Install
+
+```bash
+git clone https://github.com/itsGustav/Pay-Lobster.git
+cd Pay-Lobster/cli
+npm install
+```
+
+### Development Workflow
+
+```bash
+# Build the project
+npm run build
+
+# Run without building (using tsx)
+npm run dev -- status
+
+# Link for local testing
+npm run link
+
+# Run tests
+npm test
+
+# Watch mode for tests
+npm test -- --watch
+```
+
+## Project Structure
+
+```
+cli/
+├── bin/
+│   └── plob.ts           # Executable entry point
+├── src/
+│   ├── index.ts          # Main CLI setup
+│   ├── commands/         # Command implementations
+│   │   ├── auth.ts
+│   │   ├── config.ts
+│   │   ├── escrow.ts
+│   │   ├── mandate.ts
+│   │   ├── pay.ts
+│   │   ├── register.ts
+│   │   ├── reputation.ts
+│   │   └── status.ts
+│   ├── lib/              # Shared utilities
+│   │   ├── config.ts     # Config management
+│   │   ├── contracts.ts  # Contract interactions
+│   │   ├── display.ts    # Output formatting
+│   │   ├── types.ts      # TypeScript types
+│   │   └── wallet.ts     # Wallet management
+│   └── __tests__/        # Unit tests
+└── package.json
+```
+
+## Adding a New Command
+
+### 1. Create Command File
+
+Create `src/commands/mycommand.ts`:
+
+```typescript
+import { Command } from 'commander';
+import { success, error, outputJSON } from '../lib/display';
+import type { OutputOptions } from '../lib/types';
+
+export function createMyCommand(): Command {
+  const cmd = new Command('mycommand')
+    .description('Description of your command');
+
+  cmd
+    .option('--required <value>', 'Required option')
+    .option('--json', 'Output as JSON')
+    .action(async (options: { required: string } & OutputOptions) => {
+      try {
+        // Your logic here
+        const result = { success: true };
+
+        if (outputJSON(result, options)) {
+          return;
+        }
+
+        success('Command completed!');
+      } catch (err) {
+        error(`Failed: ${err}`);
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}
+```
+
+### 2. Register in Main CLI
+
+Edit `src/index.ts`:
+
+```typescript
+import { createMyCommand } from './commands/mycommand';
+
+// ... existing code ...
+
+program.addCommand(createMyCommand());
+```
+
+### 3. Add Tests
+
+Create `src/__tests__/mycommand.test.ts`:
+
+```typescript
+import { describe, test, expect } from '@jest/globals';
+import { createMyCommand } from '../commands/mycommand';
+
+describe('mycommand', () => {
+  test('command is registered', () => {
+    const cmd = createMyCommand();
+    expect(cmd.name()).toBe('mycommand');
+  });
+});
+```
+
+## Adding Contract Interactions
+
+### 1. Add ABI
+
+In `src/lib/contracts.ts`, add the contract ABI:
+
+```typescript
+const MY_CONTRACT_ABI = [
+  {
+    inputs: [{ name: 'param', type: 'string' }],
+    name: 'myFunction',
+    outputs: [{ name: 'result', type: 'uint256' }],
+    stateMutability: 'view',
+    type: 'function',
+  },
+] as const;
+```
+
+### 2. Add Helper Function
+
+```typescript
+export async function callMyContract(param: string): Promise<bigint> {
+  const config = loadConfig();
+  const publicClient = getPublicClient(config.network);
+  const contracts = getContracts(config.network);
+
+  const result = await publicClient.readContract({
+    address: contracts.MY_CONTRACT,
+    abi: MY_CONTRACT_ABI,
+    functionName: 'myFunction',
+    args: [param],
+  });
+
+  return result;
+}
+```
+
+### 3. Add Contract Address
+
+Update `getContracts()` function to include your contract address.
+
+## Code Style Guidelines
+
+### TypeScript
+
+- Use strict TypeScript (`strict: true`)
+- Prefer `async/await` over callbacks
+- Use `const` for immutable values
+- Type all function parameters and returns
+
+### Error Handling
+
+```typescript
+// ✅ Good: Proper error handling
+try {
+  const result = await someOperation();
+  success('Operation succeeded');
+} catch (err) {
+  error(`Operation failed: ${err}`);
+  process.exit(1);
+}
+
+// ❌ Bad: Swallowing errors
+try {
+  await someOperation();
+} catch (err) {
+  // Silent failure
+}
+```
+
+### User Output
+
+```typescript
+// ✅ Good: Support both pretty and JSON output
+if (outputJSON(data, options)) {
+  return;
+}
+success('Pretty output for humans');
+
+// ❌ Bad: Only one output format
+console.log(data);
+```
+
+### Exit Codes
+
+- `0`: Success
+- `1`: General error
+- Never use other codes
+
+## Testing Guidelines
+
+### Unit Tests
+
+Test pure functions and utilities:
+
+```typescript
+describe('formatAddress', () => {
+  test('shortens address correctly', () => {
+    const address = '0x1234567890123456789012345678901234567890';
+    const result = formatAddress(address);
+    expect(result).toBe('0x1234...7890');
+  });
+});
+```
+
+### Integration Tests
+
+For commands that interact with blockchain, mock the responses:
+
+```typescript
+jest.mock('../lib/contracts', () => ({
+  getBalance: jest.fn().mockResolvedValue({
+    usdc: BigInt('1000000'),
+    eth: BigInt('1000000000000000000'),
+  }),
+}));
+```
+
+### Manual Testing
+
+Before submitting:
+
+1. Test on Sepolia testnet
+2. Try all command variations
+3. Test error cases (invalid input, insufficient balance, etc.)
+4. Verify `--json` output for all commands
+5. Check exit codes
+
+## Commit Guidelines
+
+Follow conventional commits:
+
+```
+feat: add mandate revoke command
+fix: correct USDC balance formatting
+docs: update README with new examples
+test: add tests for escrow commands
+refactor: simplify wallet loading logic
+chore: update dependencies
+```
+
+## Pull Request Process
+
+1. **Fork and Branch**
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make Changes**
+   - Write clean, documented code
+   - Add tests
+   - Update README if needed
+
+3. **Test Thoroughly**
+   ```bash
+   npm test
+   npm run build
+   npm run link
+   plob mycommand --test
+   ```
+
+4. **Commit**
+   ```bash
+   git add .
+   git commit -m "feat: add my feature"
+   ```
+
+5. **Push and PR**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+   Then create a Pull Request on GitHub
+
+6. **PR Checklist**
+   - [ ] Tests pass
+   - [ ] Code builds without errors
+   - [ ] README updated (if applicable)
+   - [ ] Examples added (if new feature)
+   - [ ] Tested on Sepolia testnet
+   - [ ] JSON output works
+   - [ ] Error messages are clear
+
+## Areas for Contribution
+
+### High Priority
+
+- [ ] Mandate contract integration (full implementation)
+- [ ] Service discovery commands (search, compare)
+- [ ] A2A messaging support
+- [ ] Batch operations (bulk escrow creation/release)
+- [ ] Improved keystore encryption
+- [ ] Hardware wallet support (Ledger, Trezor)
+
+### Medium Priority
+
+- [ ] Transaction history viewer
+- [ ] Gas estimation and optimization
+- [ ] Multi-signature wallet support
+- [ ] Dispute resolution commands
+- [ ] Notification system (webhooks, email)
+- [ ] Shell completion (bash, zsh, fish)
+
+### Low Priority / Nice-to-Have
+
+- [ ] TUI (Terminal UI) mode
+- [ ] Interactive prompts for all commands
+- [ ] CSV export for transactions
+- [ ] Reputation analytics/charts
+- [ ] Integration with popular agent frameworks
+- [ ] Docker image
+
+## Code Review Process
+
+All PRs require:
+
+1. Code review from at least one maintainer
+2. All tests passing
+3. No TypeScript errors
+4. Documentation updated
+
+Typical review time: 2-5 business days
+
+## Questions?
+
+- Open an issue on GitHub
+- Join our Discord: https://discord.gg/paylobster
+- Email: dev@paylobster.com
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to PayLobster! 🦞