chore: hidden help command

Author: vladfrangu

eslint.config.mjs

@@ -86,4 +86,10 @@ export default [
 			],
 		},
 	},
+	{
+		files: ['features/**/*'],
+		rules: {
+			'import/no-extraneous-dependencies': 'off',
+		},
+	},
 ];

features/help-command.feature.md

@@ -0,0 +1,74 @@
+# Feature: Help command (`apify help`)
+
+- As a CLI user
+- I want to get easy help messages
+
+## Rule: `apify help` prints the whole help message
+
+### Example: call `apify help` with no commands
+
+- When I run anywhere:
+  ```
+  $ apify help
+  ```
+- Then I can read text on stdout:
+  ```
+  https://apify.com/contact
+  ```
+
+### Example: call `actor help` with no commands
+
+- When I run anywhere:
+  ```
+  $ actor help
+  ```
+- Then I can read text on stdout:
+  ```
+  https://apify.com/contact
+  ```
+
+### Example: call `apify help help` prints the main message
+
+- When I run anywhere:
+  ```
+  $ apify help help
+  ```
+- Then I can read text on stdout:
+  ```
+  https://apify.com/contact
+  ```
+
+## Rule: `apify help <command>` prints a command's help message
+
+### Example: `apify help -h`
+
+- When I run anywhere:
+  ```
+  $ apify help -h
+  ```
+- Then I can read text on stdout:
+  ```
+  Prints out help about a command, or all available commands.
+  ```
+
+### Example: `apify help run`
+
+- When I run anywhere:
+  ```
+  $ apify help run
+  ```
+- Then I can read text on stdout:
+  ```
+  Executes Actor locally with simulated Apify environment variables.
+  ```
+
+### Example: `apify run --help` returns the same message as `apify help run`
+
+- When I run anywhere:
+  ```
+  $ apify run --help
+  ```
+- Then I can read text on stdout:
+  ```
+  Executes Actor locally with simulated Apify environment variables.
+  ```

features/test-implementations/0.world.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import type { IWorld } from '@cucumber/cucumber';
 import { Result } from '@sapphire/result';
 import type { ApifyClient } from 'apify-client';
-import { type Options, type ExecaError, type Result as ExecaResult, execaNode } from 'execa';
+import { type ExecaError, execaNode, type Options, type Result as ExecaResult } from 'execa';
 
 type DynamicOptions = {
 	-readonly [P in keyof Options]: Options[P];
@@ -49,8 +49,8 @@ export interface TestWorld<Parameters = unknown[]> extends IWorld<Parameters> {
  */
 export const ProjectRoot = new URL('../../', import.meta.url);
 
-export const DevRunFile = new URL('./src/entrypoints/apify.ts', ProjectRoot);
-
+export const ApifyDevRunFile = new URL('./src/entrypoints/apify.ts', ProjectRoot);
+export const ActorDevRunFile = new URL('./src/entrypoints/actor.ts', ProjectRoot);
 export const TestTmpRoot = new URL('./test/tmp/', ProjectRoot);
 
 await mkdir(TestTmpRoot, { recursive: true });
@@ -80,18 +80,20 @@ export async function executeCommand({
 	// step 1: get the first element, and make sure it starts with `apify`
 	const [command] = commandToRun;
 
-	if (!command.startsWith('apify')) {
+	if (!command.startsWith('apify') && !command.startsWith('actor')) {
 		// TODO: maybe try to parse these commands out and provide stdin that way, but for now, its better to get the writer to use the existing rules
 		if (command.startsWith('echo') || command.startsWith('jo')) {
 			throw new RangeError(
 				`When writing a test case, please use the "given the following input provided via standard input" rule for providing standard input to the command you're testing.\nReceived: ${command}`,
 			);
 		}
 
-		throw new RangeError(`Command must start with 'apify', received: ${command}`);
+		throw new RangeError(`Command must start with 'apify' or 'actor', received: ${command}`);
 	}
 
-	const cleanCommand = command.replace(/^apify/, '').trim();
+	const devRunFile = command.startsWith('apify') ? ApifyDevRunFile : ActorDevRunFile;
+
+	const cleanCommand = command.replace(/^apify|actor/, '').trim();
 
 	const options: DynamicOptions = {
 		cwd,
@@ -138,7 +140,7 @@ export async function executeCommand({
 	>(async () => {
 		const process = execaNode(
 			tsxCli,
-			[fileURLToPath(DevRunFile), ...commandArguments],
+			[fileURLToPath(devRunFile), ...commandArguments],
 			options as { cwd: typeof cwd; input: typeof stdin },
 		);
 

features/test-implementations/1.setup.ts

@@ -4,6 +4,7 @@ import { readFile, rm, writeFile } from 'node:fs/promises';
 import { AfterAll, Given, setDefaultTimeout } from '@cucumber/cucumber';
 import { ApifyClient } from 'apify-client';
 
+import { getApifyClientOptions } from '../../src/lib/utils.js';
 import {
 	assertWorldIsLoggedIn,
 	assertWorldIsValid,
@@ -12,7 +13,6 @@ import {
 	TestTmpRoot,
 	type TestWorld,
 } from './0.world';
-import { getApifyClientOptions } from '../../src/lib/utils';
 
 setDefaultTimeout(20_000);
 
@@ -230,7 +230,6 @@ Given<TestWorld>(/the local actor is pushed to the Apify platform/i, { timeout:
 	const extraEnv: Record<string, string> = {};
 
 	if (this.authStatePath) {
-		// eslint-disable-next-line no-underscore-dangle
 		extraEnv.__APIFY_INTERNAL_TEST_AUTH_PATH__ = this.authStatePath;
 	}
 

features/test-implementations/2.execution.ts

@@ -10,6 +10,51 @@ import {
 	type TestWorld,
 } from './0.world';
 
+When<TestWorld>(/i run anywhere:?$/i, async function (commandBlock: string) {
+	if (typeof commandBlock !== 'string') {
+		throw new TypeError('When using the `I run anywhere` step, you must provide a text block containing a command');
+	}
+
+	const extraEnv: Record<string, string> = {};
+
+	if (this.authStatePath) {
+		extraEnv.__APIFY_INTERNAL_TEST_AUTH_PATH__ = this.authStatePath;
+	}
+
+	const result = await executeCommand({
+		rawCommand: commandBlock,
+		env: extraEnv,
+	});
+
+	if (result.isOk()) {
+		const value = result.unwrap();
+
+		if (this.testResults) {
+			console.error(`\n  Warning: Overwriting existing test results: ${JSON.stringify(this.testResults)}`);
+		}
+
+		this.testResults = {
+			exitCode: value.exitCode!,
+			stderr: value.stderr,
+			stdout: value.stdout,
+			runResults: null,
+		};
+	} else {
+		const error = result.unwrapErr();
+
+		if (this.testResults) {
+			console.error(`\n  Warning: Overwriting existing test results: ${JSON.stringify(this.testResults)}`);
+		}
+
+		this.testResults = {
+			exitCode: error.exitCode!,
+			stderr: error.stderr,
+			stdout: error.stdout,
+			runResults: null,
+		};
+	}
+});
+
 When<TestWorld>(/i run:?$/i, async function (commandBlock: string) {
 	assertWorldIsValid(this);
 
@@ -20,7 +65,6 @@ When<TestWorld>(/i run:?$/i, async function (commandBlock: string) {
 	const extraEnv: Record<string, string> = {};
 
 	if (this.authStatePath) {
-		// eslint-disable-next-line no-underscore-dangle
 		extraEnv.__APIFY_INTERNAL_TEST_AUTH_PATH__ = this.authStatePath;
 	}
 
@@ -103,7 +147,6 @@ When<TestWorld>(/i run with captured data/i, async function (commandBlock: strin
 	const extraEnv: Record<string, string> = {};
 
 	if (this.authStatePath) {
-		// eslint-disable-next-line no-underscore-dangle
 		extraEnv.__APIFY_INTERNAL_TEST_AUTH_PATH__ = this.authStatePath;
 	}
 

features/test-implementations/3.results.ts

@@ -77,7 +77,6 @@ Then<TestWorld>(/i don't see any node\.js exception/i, function () {
 });
 
 Then<TestWorld>(/i can read text on stderr/i, function (expectedStdout: string) {
-	assertWorldIsValid(this);
 	assertWorldHasRanCommand(this);
 
 	if (typeof expectedStdout !== 'string') {
@@ -87,9 +86,16 @@ Then<TestWorld>(/i can read text on stderr/i, function (expectedStdout: string)
 	}
 
 	const lowercasedResult = this.testResults.stderr.toLowerCase();
-	const lowercasedExpected = replaceMatchersInString(expectedStdout, {
-		testActorName: this.testActor.name,
-	}).toLowerCase();
+
+	let lowercasedExpected = expectedStdout;
+
+	if (this.testActor) {
+		lowercasedExpected = replaceMatchersInString(lowercasedExpected, {
+			testActorName: this.testActor.name,
+		});
+	}
+
+	lowercasedExpected = lowercasedExpected.toLowerCase();
 
 	strictEqual(
 		lowercasedResult.includes(lowercasedExpected),
@@ -99,7 +105,6 @@ Then<TestWorld>(/i can read text on stderr/i, function (expectedStdout: string)
 });
 
 Then<TestWorld>(/i can read text on stdout/i, function (expectedStdout: string) {
-	assertWorldIsValid(this);
 	assertWorldHasRanCommand(this);
 
 	if (typeof expectedStdout !== 'string') {
@@ -109,9 +114,16 @@ Then<TestWorld>(/i can read text on stdout/i, function (expectedStdout: string)
 	}
 
 	const lowercasedResult = this.testResults.stdout.toLowerCase();
-	const lowercasedExpected = replaceMatchersInString(expectedStdout, {
-		testActorName: this.testActor.name,
-	}).toLowerCase();
+
+	let lowercasedExpected = expectedStdout;
+
+	if (this.testActor) {
+		lowercasedExpected = replaceMatchersInString(lowercasedExpected, {
+			testActorName: this.testActor.name,
+		});
+	}
+
+	lowercasedExpected = lowercasedExpected.toLowerCase();
 
 	strictEqual(
 		lowercasedResult.includes(lowercasedExpected),

package.json

@@ -6,12 +6,13 @@
     "types": "./dist/index.d.ts",
     "type": "module",
     "scripts": {
-        "dev": "tsx ./src/entrypoints/apify.ts",
+        "dev:apify": "tsx ./src/entrypoints/apify.ts",
+        "dev:actor": "tsx ./src/entrypoints/actor.ts",
         "test": "vitest run",
         "test-python": "vitest run -t '.*\\[python\\]'",
         "test:cucumber": "cross-env NODE_OPTIONS=\"--import tsx\" cucumber-js",
-        "lint": "eslint src test scripts --ext .ts,.cjs,.mjs",
-        "lint:fix": "eslint src test scripts --fix --ext .ts,.cjs,.mjs",
+        "lint": "eslint src test scripts features --ext .ts,.cjs,.mjs",
+        "lint:fix": "eslint src test scripts features --fix --ext .ts,.cjs,.mjs",
         "format": "biome format . && prettier --check \"**/*.{md,yml,yaml}\"",
         "format:fix": "biome format --write . && prettier --write \"**/*.{md,yml,yaml}\"",
         "clean": "rimraf dist",
@@ -69,6 +70,7 @@
         "@sapphire/duration": "^1.1.2",
         "@sapphire/result": "^2.7.2",
         "@sapphire/timestamp": "^1.0.3",
+        "@skyra/jaro-winkler": "^1.1.1",
         "adm-zip": "~0.5.15",
         "ajv": "~8.17.1",
         "apify-client": "^2.11.0",

src/commands/_register.ts

@@ -1,12 +1,19 @@
 import type { BuiltApifyCommand } from '../lib/command-framework/apify-command.js';
 import { ActorIndexCommand } from './actor/_index.js';
+import { ActorChargeCommand } from './actor/charge.js';
+import { ActorGetInputCommand } from './actor/get-input.js';
+import { ActorGetPublicUrlCommand } from './actor/get-public-url.js';
+import { ActorGetValueCommand } from './actor/get-value.js';
+import { ActorPushDataCommand } from './actor/push-data.js';
+import { ActorSetValueCommand } from './actor/set-value.js';
 import { ActorsIndexCommand } from './actors/_index.js';
 import { BuildsIndexCommand } from './builds/_index.js';
 import { TopLevelCallCommand } from './call.js';
 import { CheckVersionCommand } from './check-version.js';
 import { CreateCommand } from './create.js';
 import { DatasetsIndexCommand } from './datasets/_index.js';
 import { EditInputSchemaCommand } from './edit-input-schema.js';
+import { HelpCommand } from './help.js';
 import { InfoCommand } from './info.js';
 import { InitCommand } from './init.js';
 import { WrapScrapyCommand } from './init-wrap-scrapy.js';
@@ -47,8 +54,16 @@ export const apifyCommands = [
 	ToplevelPushCommand,
 	RunCommand,
 	ValidateInputSchemaCommand,
+	HelpCommand,
 ] as const satisfies (typeof BuiltApifyCommand)[];
 
-export const actorCommands: (typeof BuiltApifyCommand)[] = [
+export const actorCommands = [
 	//
-];
+	ActorSetValueCommand,
+	ActorPushDataCommand,
+	ActorGetValueCommand,
+	ActorGetPublicUrlCommand,
+	ActorGetInputCommand,
+	ActorChargeCommand,
+	HelpCommand,
+] as const satisfies (typeof BuiltApifyCommand)[];