Skip to content

Commit 10cebee

Browse files
alexcos20alexcos20
authored
Merge pull request #140 from oceanprotocol/ai/add_copilot_instructions
add copilot instructions
2 parents f893c48 + 9f2ae24 commit 10cebee

1 file changed

Lines changed: 255 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Copilot Instructions for Ocean CLI
2+
3+
## Project Overview
4+
5+
Ocean CLI is a TypeScript-based command-line tool for interacting with Ocean Network, using Ocean Protocol's JavaScript library ([Ocean-Js](https://github.com/oceanprotocol/ocean.js)). It enables users to privately and securely publish, consume, and run compute operations.
6+
7+
**Key Features:**
8+
- Publish data services (downloadable files or compute-to-data)
9+
- Edit existing assets
10+
- Consume data services and download data
11+
- Compute-to-data operations on public datasets
12+
- Manage access control with access lists
13+
- Handle escrow payments for compute jobs
14+
- Manage authentication with token generation
15+
16+
## Project Structure
17+
18+
```
19+
src/
20+
├── cli.ts # CLI entry point and command setup
21+
├── commands.ts # Command implementations
22+
├── helpers.ts # Utility helper functions
23+
├── index.ts # Package exports
24+
├── interactiveFlow.ts # Interactive user flow handlers
25+
├── publishAsset.ts # Asset publishing logic
26+
test/ # Test suite (Mocha + Chai)
27+
metadata/ # Sample metadata files for testing
28+
```
29+
30+
## Technology Stack
31+
32+
- **Language:** TypeScript 5.x
33+
- **Runtime:** Node.js (ES2020 module)
34+
- **Testing:** Mocha + Chai
35+
- **Linting:** ESLint with TypeScript support
36+
- **Formatting:** Prettier
37+
- **CLI Framework:** Commander.js
38+
- **Crypto:** ethers.js, Ethereum wallet support
39+
- **Ocean Protocol:** @oceanprotocol/lib, @oceanprotocol/ddo-js
40+
41+
## Code Style & Conventions
42+
43+
### TypeScript Configuration
44+
- **Target:** ES2020
45+
- **Module:** ES2020
46+
- **Strict Mode:** Enabled
47+
- **Module Resolution:** Node
48+
- **Source Maps:** Enabled for debugging
49+
50+
### Coding Standards
51+
52+
1. **Imports & Exports:**
53+
- Use ES6 module syntax: `import`/`export`
54+
- Group imports: external libs, then internal modules
55+
- Use named imports when possible
56+
- Explicitly use `.js` extension for relative imports (ESM compatibility)
57+
58+
```typescript
59+
import { Command } from 'commander';
60+
import { Commands } from './commands.js';
61+
import chalk from 'chalk';
62+
```
63+
64+
2. **Formatting:**
65+
- Use Prettier for code formatting
66+
- Line length: Follow Prettier defaults
67+
- Indentation: 2 spaces
68+
- Semicolons: Always include
69+
- Quotes: Single quotes preferred
70+
71+
3. **Naming Conventions:**
72+
- Classes/Types: PascalCase
73+
- Functions/Variables: camelCase
74+
- Constants: UPPER_SNAKE_CASE
75+
- Private methods: Prefix with `_`
76+
77+
4. **Async/Await:**
78+
- Prefer async/await over Promise.then()
79+
- Use try/catch for error handling
80+
- Always return promises from async functions
81+
82+
5. **Type Safety:**
83+
- Always provide explicit type annotations for function parameters and return types
84+
- Avoid `any` type; use `unknown` if necessary
85+
- Use interfaces for object types
86+
- Leverage TypeScript strict mode
87+
88+
```typescript
89+
async function initializeSigner(): Promise<{ signer: Signer; chainId: number }> {
90+
// implementation
91+
}
92+
```
93+
94+
6. **Error Handling:**
95+
- Use chalk library for colored console output
96+
- Use `process.exit(code)` for CLI exit codes
97+
- Provide meaningful error messages to users
98+
99+
```typescript
100+
console.error(chalk.red("Error message"));
101+
process.exit(1);
102+
```
103+
104+
## Environment Variables
105+
106+
Required:
107+
- `PRIVATE_KEY` or `MNEMONIC`: Wallet credentials
108+
- `RPC`: RPC endpoint URL
109+
- `NODE_URL`: Ocean Node URL for indexing
110+
111+
Optional:
112+
- `ADDRESS_FILE`: Path to custom smart contract addresses
113+
- `INDEXING_MAX_RETRIES`: Max retries for asset indexing (default: 100)
114+
115+
## Build & Development
116+
117+
### Commands
118+
```bash
119+
npm install # Install dependencies
120+
npm run build # Build TypeScript (clean + compile)
121+
npm run lint # Run ESLint
122+
npm run lint:fix # Auto-fix linting issues
123+
npm run format # Format code with Prettier
124+
npm run cli # Run CLI interactively
125+
npm run test # Run full test suite (lint + tests)
126+
npm run test:system # Run system tests only
127+
```
128+
129+
### Development Workflow
130+
1. Make changes in `src/`
131+
2. Run `npm run lint:fix` to auto-fix style issues
132+
3. Run `npm run test` before committing
133+
4. Build with `npm run build` to verify TypeScript compilation
134+
135+
## Testing
136+
137+
- **Framework:** Mocha with Chai assertions
138+
- **Location:** `test/` directory
139+
- **Naming:** `*.test.ts` files
140+
- **Test Configuration:** `test/.mocharc.json`
141+
- **Node Environment:** Tests run with `NODE_OPTIONS='--experimental-require-module'`
142+
143+
### Test Categories
144+
- `accessList.test.ts` - Access list functionality
145+
- `consumeFlow.test.ts` - Data consumption workflow
146+
- `escrow.test.ts` - Escrow payment handling
147+
- `http.test.ts` - HTTP operations
148+
- `paidComputeFlow.test.ts` - Paid compute workflows
149+
- `setup.test.ts` - Setup and initialization
150+
- `util.ts` - Test utilities
151+
152+
### Sample Metadata
153+
See `metadata/` directory for example asset configurations:
154+
- JavaScript algorithms
155+
- IPFS-hosted algorithms
156+
- Python algorithms
157+
- Compute datasets
158+
- Download datasets
159+
160+
## ESLint Rules
161+
162+
- `@typescript-eslint/no-explicit-any`: Warn (avoid `any` types)
163+
- Recommended ESLint rules enabled
164+
- TypeScript ESLint recommended config applied
165+
- Prettier integration enabled
166+
167+
## Dependencies Overview
168+
169+
**Key Runtime Dependencies:**
170+
- `@oceanprotocol/lib` - Core Ocean Protocol functionality
171+
- `@oceanprotocol/ddo-js` - Decentralized Data Objects
172+
- `@oceanprotocol/contracts` - Smart contract interfaces
173+
- `ethers` - Ethereum Web3 library
174+
- `commander` - CLI argument parsing
175+
- `chalk` - Colored console output
176+
177+
## Current Branch Context
178+
179+
- **Current Branch:** security/add_n8n_workflow
180+
- **Default Branch:** main
181+
- **Main Purpose:** Security improvements with n8n workflow integration
182+
183+
## Best Practices
184+
185+
1. **CLI Design:**
186+
- Use Commander.js for consistent command structure
187+
- Provide clear help text for all commands
188+
- Use interactive prompts for complex flows
189+
- Show progress for long-running operations
190+
191+
2. **Wallet Management:**
192+
- Support both private key and mnemonic imports
193+
- Validate environment variables at startup
194+
- Use ethers.js for all cryptographic operations
195+
- Never log or expose private keys
196+
197+
3. **Error Messages:**
198+
- Use `chalk.red()` for errors
199+
- Include actionable error messages
200+
- Exit with appropriate status codes (0 = success, 1 = error)
201+
202+
4. **Code Organization:**
203+
- Keep CLI setup in `cli.ts`
204+
- Separate command logic into `commands.ts`
205+
- Share utilities in `helpers.ts`
206+
- Use modular flows for complex operations
207+
208+
5. **Documentation:**
209+
- Include JSDoc comments for exported functions
210+
- Document complex algorithms and workflows
211+
- Keep README.md updated with usage examples
212+
213+
## Common Patterns
214+
215+
### Interactive Flows
216+
Use `readline/promises` for user input in interactive flows:
217+
```typescript
218+
import { createInterface } from 'readline/promises';
219+
import { stdin as input, stdout as output } from 'node:process';
220+
221+
const rl = createInterface({ input, output });
222+
const answer = await rl.question('Prompt: ');
223+
```
224+
225+
### Logging with Colors
226+
```typescript
227+
import chalk from 'chalk';
228+
229+
console.log(chalk.green('Success'));
230+
console.error(chalk.red('Error'));
231+
console.log(chalk.yellow('Warning'));
232+
console.log(chalk.blue('Info'));
233+
```
234+
235+
### Type-Safe Conversions
236+
```typescript
237+
import { toBoolean } from './helpers.js';
238+
import { unitsToAmount } from '@oceanprotocol/lib';
239+
```
240+
241+
## Before Committing
242+
243+
- [ ] Run `npm run test` - all tests pass
244+
- [ ] Run `npm run lint:fix` - no linting errors
245+
- [ ] Check TypeScript compilation: `npm run build`
246+
- [ ] Verify no console.log statements left (except intentional logging)
247+
- [ ] Update README.md if adding new features
248+
- [ ] Add/update tests for new functionality
249+
250+
## Related Documentation
251+
252+
- [Ocean Protocol](https://oceanprotocol.com)
253+
- [ocean.js Documentation](https://github.com/oceanprotocol/ocean.js)
254+
- [Commander.js Guide](https://github.com/tj/commander.js)
255+
- [ethers.js Documentation](https://docs.ethers.org/)

0 commit comments

Comments
 (0)