From 17cde9c5dde15c451b73e3bc43bf674d99a2c768 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 23 Sep 2025 12:59:29 +0000 Subject: [PATCH 1/4] Initial plan From 6ef2835bb84cbc94b554d16f91769aa6c42c3fd1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 23 Sep 2025 13:08:18 +0000 Subject: [PATCH 2/4] Add agents.md file adapted from cursor rules Co-authored-by: vladfrangu <17960496+vladfrangu@users.noreply.github.com> --- agents.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 00000000..03344ab5 --- /dev/null +++ b/agents.md @@ -0,0 +1,122 @@ +# Apify CLI - AI Agent Instructions + +This file contains instructions for AI agents working on the Apify CLI project to understand the codebase structure, conventions, and best practices. + +## Project Overview + +The Apify CLI is a command-line interface that helps developers create, develop, build, and run Apify Actors, and manage the Apify cloud platform. It's built with TypeScript and uses a modular command framework. + +## Command Development Guidelines + +When creating new CLI commands, follow these guidelines: + +### Command Structure + +- **Base Class**: All commands must extend `ApifyCommand` from `src/lib/command-framework/apify-command.ts` + - Import: `import { ApifyCommand } from '../lib/command-framework/apify-command.js'` + - Do NOT use `BuiltApifyCommand` class + +- **Arguments**: Import from `src/lib/command-framework/args.ts` + - Import: `import { Args } from '../lib/command-framework/args.js'` + - Usage example: `Args.string()` + +- **Flags**: Import from `src/lib/command-framework/flags.ts` + - Import: `import { Flags } from '../lib/command-framework/flags.js'` + - Usage example: `Flags.string()` + +### Naming Conventions + +- Command names must be lowercase +- Use dashes for separators (NOT spaces, NOT underscores) +- Example: `my-command`, `validate-schema`, `push-data` + +### Command Class Template + +```typescript +export class MyCommandCommand extends ApifyCommand { + static override name = "my-command" as const; + + static override description = "Description of what this command does"; + + static override examples = [ + "$ apify my-command", + "$ apify my-command --flag value" + ]; + + static override args = { + // Define arguments here using Args.* + }; + + static override flags = { + // Define flags here using Flags.* + }; + + async run() { + // Command logic implementation + } +} +``` + +### Command Registration + +After creating a command: + +1. **For general Apify commands**: Add to the end of the `apifyCommands` array in `src/commands/_register.ts` +2. **For Actor-specific commands**: Add to the `actorCommands` array in `src/commands/_register.ts` + +### Reference Examples + +Study these existing commands for patterns and best practices: + +- `src/commands/validate-schema.ts` - Simple command with validation +- `src/commands/cli-management/upgrade.ts` - Command with flags and external API calls +- `src/commands/_register.ts` - Command registration patterns + +### File Organization + +- Commands are organized in `src/commands/` directory +- Group related commands in subdirectories (e.g., `cli-management/`, `actor-management/`) +- Use descriptive filenames that match the command name + +## Code Style and Conventions + +### TypeScript Guidelines + +- Always mark class properties as `static override` when extending base classes +- Use proper type annotations and generics +- Follow the existing import patterns and module structure + +### Error Handling + +- Use appropriate error codes from `src/lib/consts.ts` +- Provide helpful error messages to users +- Handle edge cases gracefully + +### Configuration + +- Actor configuration uses `.actor/actor.json` (new format) +- Legacy `apify.json` is deprecated but may need migration support +- Reference constants from `src/lib/consts.ts` for file paths and configurations + +## Testing + +- Write tests for new commands following existing patterns in the `test/` directory +- Use the testing utilities and setup from the project +- Test both success and error scenarios + +## Development Workflow + +1. Install dependencies: `yarn install` +2. Run in development mode: `yarn dev:apify` or `yarn dev:actor` +3. Lint code: `yarn lint` or `yarn lint:fix` +4. Format code: `yarn format` or `yarn format:fix` +5. Build project: `yarn build` +6. Run tests: `yarn test:local` or `yarn test:all` + +## Important Notes + +- Always prompt users for required information if not provided +- Follow the established patterns for command structure and organization +- When in doubt about command type (apify vs actor), ask for clarification +- Maintain backward compatibility when possible +- Update documentation when adding new commands \ No newline at end of file From 7beaa7d9fb78554c52410a9a3d54461318daeffc Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Tue, 23 Sep 2025 16:15:42 +0300 Subject: [PATCH 3/4] Revise command examples and documentation guidelines Removed examples section and updated documentation notes. --- agents.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/agents.md b/agents.md index 03344ab5..437e8a98 100644 --- a/agents.md +++ b/agents.md @@ -38,11 +38,6 @@ export class MyCommandCommand extends ApifyCommand { static override description = "Description of what this command does"; - static override examples = [ - "$ apify my-command", - "$ apify my-command --flag value" - ]; - static override args = { // Define arguments here using Args.* }; @@ -88,7 +83,7 @@ Study these existing commands for patterns and best practices: ### Error Handling -- Use appropriate error codes from `src/lib/consts.ts` +- Use appropriate exit error codes from `src/lib/consts.ts` - Provide helpful error messages to users - Handle edge cases gracefully @@ -107,11 +102,10 @@ Study these existing commands for patterns and best practices: ## Development Workflow 1. Install dependencies: `yarn install` -2. Run in development mode: `yarn dev:apify` or `yarn dev:actor` -3. Lint code: `yarn lint` or `yarn lint:fix` -4. Format code: `yarn format` or `yarn format:fix` -5. Build project: `yarn build` -6. Run tests: `yarn test:local` or `yarn test:all` +2. Lint code: `yarn lint` or `yarn lint:fix` +3. Format code: `yarn format` or `yarn format:fix` +4. Build project: `yarn build` +5. Run tests: `yarn test:local` or `yarn test:all` ## Important Notes @@ -119,4 +113,4 @@ Study these existing commands for patterns and best practices: - Follow the established patterns for command structure and organization - When in doubt about command type (apify vs actor), ask for clarification - Maintain backward compatibility when possible -- Update documentation when adding new commands \ No newline at end of file +- Do NOT override the documentation when adding new commands, as it is automatically generated From 58d59f8d683cabe4f3958c9c02f3e9474b8928da Mon Sep 17 00:00:00 2001 From: Vlad Frangu Date: Thu, 25 Sep 2025 12:36:33 +0300 Subject: [PATCH 4/4] chore: tweaks --- agents.md | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/agents.md b/agents.md index 437e8a98..4916199a 100644 --- a/agents.md +++ b/agents.md @@ -4,7 +4,7 @@ This file contains instructions for AI agents working on the Apify CLI project t ## Project Overview -The Apify CLI is a command-line interface that helps developers create, develop, build, and run Apify Actors, and manage the Apify cloud platform. It's built with TypeScript and uses a modular command framework. +The Apify CLI is a command-line interface that helps developers create, develop, build, and run Apify Actors, and manage their Actors on the Apify cloud platform. It's built with TypeScript and uses a modular command framework. ## Command Development Guidelines @@ -34,21 +34,21 @@ When creating new CLI commands, follow these guidelines: ```typescript export class MyCommandCommand extends ApifyCommand { - static override name = "my-command" as const; - - static override description = "Description of what this command does"; - - static override args = { - // Define arguments here using Args.* - }; - - static override flags = { - // Define flags here using Flags.* - }; - - async run() { - // Command logic implementation - } + static override name = "my-command" as const; + + static override description = "Description of what this command does"; + + static override args = { + // Define arguments here using Args.* + }; + + static override flags = { + // Define flags here using Flags.* + }; + + async run() { + // Command logic implementation + } } ``` @@ -83,14 +83,13 @@ Study these existing commands for patterns and best practices: ### Error Handling -- Use appropriate exit error codes from `src/lib/consts.ts` +- Use appropriate exit error codes from `src/lib/consts.ts` - Provide helpful error messages to users - Handle edge cases gracefully ### Configuration - Actor configuration uses `.actor/actor.json` (new format) -- Legacy `apify.json` is deprecated but may need migration support - Reference constants from `src/lib/consts.ts` for file paths and configurations ## Testing @@ -105,7 +104,7 @@ Study these existing commands for patterns and best practices: 2. Lint code: `yarn lint` or `yarn lint:fix` 3. Format code: `yarn format` or `yarn format:fix` 4. Build project: `yarn build` -5. Run tests: `yarn test:local` or `yarn test:all` +5. Run tests: `yarn test:local` ## Important Notes