feat: builds namespace

package.json

@@ -66,12 +66,15 @@
         "@oclif/core": "~4.0.17",
         "@oclif/plugin-help": "~6.2.8",
         "@root/walk": "~1.1.0",
+        "@sapphire/duration": "^1.1.2",
+        "@sapphire/timestamp": "^1.0.3",
         "adm-zip": "~0.5.15",
         "ajv": "~8.17.1",
         "apify-client": "~2.9.4",
         "archiver": "~7.0.1",
         "axios": "~1.7.3",
         "chalk": "~5.3.0",
+        "cli-table": "^0.3.11",
         "computer-name": "~0.1.0",
         "configparser": "~0.3.10",
         "cors": "~2.8.5",
@@ -109,6 +112,7 @@
         "@types/adm-zip": "^0.5.5",
         "@types/archiver": "^6.0.2",
         "@types/chai": "^4.3.17",
+        "@types/cli-table": "^0",
         "@types/cors": "^2.8.17",
         "@types/express": "^4.17.21",
         "@types/inquirer": "^9.0.7",

src/commands/builds/create.ts

@@ -0,0 +1,149 @@
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+
+import { ApifyCommand } from '../../lib/apify_command.js';
+import { resolveActorContext } from '../../lib/commands/resolve-actor-context.js';
+import { error, simpleLog } from '../../lib/outputs.js';
+import { getLoggedClientOrThrow, objectGroupBy, outputJobLog, TimestampFormatter } from '../../lib/utils.js';
+
+export class BuildsCreateCommand extends ApifyCommand<typeof BuildsCreateCommand> {
+	static override description = 'Creates a new build of the Actor.';
+
+	static override flags = {
+		actor: Flags.string({
+			description:
+				'Optional Actor ID or Name to trigger a build for. By default, it will use the Actor from the current directory',
+		}),
+		tag: Flags.string({
+			description: 'Build tag to be applied to the successful Actor build. By default, this is "latest"',
+		}),
+		version: Flags.string({
+			description:
+				'Optional Actor Version to build. By default, this will be inferred from the tag, but this flag is required when multiple versions have the same tag.',
+			required: false,
+		}),
+		log: Flags.boolean({
+			description: 'Whether to print out the build log after the build is triggered.',
+		}),
+	};
+
+	static override enableJsonFlag = true;
+
+	async run() {
+		const { actor, tag, version, json, log } = this.flags;
+
+		const client = await getLoggedClientOrThrow();
+
+		const ctx = await resolveActorContext({ providedActorNameOrId: actor, client });
+
+		if (!ctx) {
+			error({
+				message:
+					'Unable to detect what Actor to list the builds for. Please run this command in an Actor directory, or specify the Actor ID by running this command with "--actor=<id>"',
+			});
+
+			return;
+		}
+
+		const actorInfo = (await client.actor(ctx.id).get())!;
+
+		const versionsByBuildTag = objectGroupBy(
+			actorInfo.versions,
+			(actorVersion) => actorVersion.buildTag ?? 'latest',
+		);
+
+		const taggedVersions = versionsByBuildTag[tag ?? 'latest'];
+		const specificVersionExists = actorInfo.versions.find((v) => v.versionNumber === version);
+
+		let selectedVersion: string | undefined;
+		let actualTag = tag;
+
+		// --version takes precedence over tagged versions (but if --tag is also specified, it will be checked again)
+		if (specificVersionExists) {
+			// The API doesn't really care if the tag you use for a version is correct or not, just that the version exists. This means you CAN have two separate versions with the same tag
+			// but only the latest one that gets built will have the tag.
+			// The *console* lets you pick a version to build. Multiple versions can have the same default tag, ergo what was written above.
+			// The API *does* also let you tag any existing version with whatever you want. This is where we diverge, and follow semi-console-like behavior. Effectively, this one if check prevents you from doing
+			// "--version 0.1 --tag not_actually_the_tag", even if that is technically perfectly valid. Future reader of this code, if this is not wanted, nuke the if check.
+
+			// This ensures that a --tag and --version match the version and tag the platform knows about
+			// but only when --tag is provided
+			if (tag && (!taggedVersions || !taggedVersions.some((v) => v.versionNumber === version))) {
+				error({
+					message: `The Actor Version "${version}" does not have the tag "${tag}".`,
+				});
+
+				return;
+			}
+
+			selectedVersion = version!;
+			actualTag = specificVersionExists.buildTag ?? 'latest';
+		} else if (taggedVersions) {
+			selectedVersion = taggedVersions[0].versionNumber!;
+			actualTag = tag ?? 'latest';
+
+			if (taggedVersions.length > 1) {
+				if (!version) {
+					error({
+						message: `Multiple Actor versions with the tag "${tag}" found. Please specify the version number using the "--version" flag.\n  Available versions for this tag: ${taggedVersions.map((v) => chalk.yellow(v.versionNumber)).join(', ')}`,
+					});
+
+					return;
+				}
+
+				// On second run, it will call the upper if check
+			}
+		}
+
+		if (!selectedVersion) {
+			error({
+				message: `No Actor versions with the tag "${tag}" found. You can push a new version with this tag by using "apify push --build-tag=${tag}"`,
+			});
+
+			return;
+		}
+
+		const build = await client.actor(ctx.id).build(selectedVersion, { tag });
+
+		if (json) {
+			return build;
+		}
+
+		const message: string[] = [
+			`${chalk.yellow('Actor')}: ${actorInfo?.username ? `${actorInfo.username}/` : ''}${actorInfo?.name ?? 'unknown-actor'} (${chalk.gray(build.actId)})`,
+			`  ${chalk.yellow('Version')}: ${selectedVersion} (tagged with ${chalk.yellow(actualTag)})`,
+			'',
+			`${chalk.greenBright('Build Started')} (ID: ${chalk.gray(build.id)})`,
+			`  ${chalk.yellow('Build Number')}: ${build.buildNumber} (will get tagged once finished)`,
+			`  ${chalk.yellow('Started')}: ${TimestampFormatter.display(build.startedAt)}`,
+			'',
+		];
+
+		const url = `https://console.apify.com/actors/${build.actId}/builds/${build.buildNumber}`;
+		const viewMessage = `${chalk.blue('View in Apify Console')}: ${url}`;
+
+		simpleLog({
+			message: message.join('\n'),
+		});
+
+		if (log) {
+			try {
+				await outputJobLog(build);
+			} catch (err) {
+				// This should never happen...
+				error({ message: `Failed to print log for build with ID "${build.id}": ${(err as Error).message}` });
+			}
+
+			// Print out an empty line
+			simpleLog({
+				message: '',
+			});
+		}
+
+		simpleLog({
+			message: viewMessage,
+		});
+
+		return undefined;
+	}
+}

src/commands/builds/index.ts

@@ -0,0 +1,9 @@
+import { ApifyCommand } from '../../lib/apify_command.js';
+
+export class ActorIndexCommand extends ApifyCommand<typeof ActorIndexCommand> {
+	static override description = 'Commands are designed to be used with Actor Builds.';
+
+	async run() {
+		await this.printHelp();
+	}
+}

src/commands/builds/info.ts

@@ -0,0 +1,100 @@
+import { Args } from '@oclif/core';
+import chalk from 'chalk';
+
+import { ApifyCommand } from '../../lib/apify_command.js';
+import { prettyPrintBytes } from '../../lib/commands/pretty-print-bytes.js';
+import { prettyPrintStatus } from '../../lib/commands/pretty-print-status.js';
+import { error, simpleLog } from '../../lib/outputs.js';
+import { DurationFormatter, getLoggedClientOrThrow, TimestampFormatter } from '../../lib/utils.js';
+
+export class BuildInfoCommand extends ApifyCommand<typeof BuildInfoCommand> {
+	static override description = 'Prints information about a specific build';
+
+	static override args = {
+		buildId: Args.string({
+			required: true,
+			description: 'The build id to get information about',
+		}),
+	};
+
+	static override enableJsonFlag = true;
+
+	async run() {
+		const { buildId } = this.args;
+
+		const apifyClient = await getLoggedClientOrThrow();
+
+		const build = await apifyClient.build(buildId).get();
+
+		if (!build) {
+			error({ message: `Build with ID "${buildId}" was not found on your account` });
+			return;
+		}
+
+		// JSON output -> return the object (which is handled by oclif)
+		if (this.flags.json) {
+			return build;
+		}
+
+		const actor = await apifyClient.actor(build.actId).get();
+
+		let buildTag: string | undefined;
+
+		if (actor?.taggedBuilds) {
+			for (const [tag, buildData] of Object.entries(actor.taggedBuilds)) {
+				if (buildData.buildId === build.id) {
+					buildTag = tag;
+					break;
+				}
+			}
+		}
+
+		const exitCode = Reflect.get(build, 'exitCode') as number | undefined;
+
+		const message: string[] = [
+			//
+			`${chalk.yellow('Actor')}: ${actor?.username ? `${actor.username}/` : ''}${actor?.name ?? 'unknown-actor'} (${chalk.gray(build.actId)})`,
+			'',
+			`${chalk.yellow('Build Information')} (ID: ${chalk.gray(build.id)})`,
+			`  ${chalk.yellow('Build Number')}: ${build.buildNumber}${buildTag ? ` (tagged as ${chalk.yellow(buildTag)})` : ''}`,
+			// exitCode is also not typed...
+			`  ${chalk.yellow('Status')}: ${prettyPrintStatus(build.status)}${typeof exitCode !== 'undefined' ? ` (exit code: ${chalk.gray(exitCode)})` : ''}`,
+			`  ${chalk.yellow('Started')}: ${TimestampFormatter.display(build.startedAt)}`,
+		];
+
+		if (build.finishedAt) {
+			message.push(
+				`  ${chalk.yellow('Finished')}: ${TimestampFormatter.display(build.finishedAt)} (took ${chalk.gray(DurationFormatter.format(build.stats?.durationMillis ?? 0))})`,
+			);
+		} else {
+			const diff = Date.now() - build.startedAt.getTime();
+			message.push(
+				`  ${chalk.yellow('Finished')}: ${chalk.gray(`Running for ${DurationFormatter.format(diff)}`)}`,
+			);
+		}
+
+		if (build.stats?.computeUnits) {
+			// Platform shows 3 decimal places, so shall we
+			message.push(`  ${chalk.yellow('Compute Units')}: ${build.stats.computeUnits.toFixed(3)}`);
+		}
+
+		// Untyped field again 😢
+		const dockerImageSize = Reflect.get(build.stats ?? {}, 'imageSizeBytes') as number | undefined;
+
+		if (dockerImageSize) {
+			message.push(`  ${chalk.yellow('Docker Image Size')}: ${prettyPrintBytes(dockerImageSize)}`);
+		}
+
+		message.push(`  ${chalk.yellow('Origin')}: ${build.meta.origin ?? 'UNKNOWN'}`);
+
+		message.push('');
+
+		const url = `https://console.apify.com/actors/${build.actId}/builds/${build.buildNumber}`;
+
+		message.push(`${chalk.blue('View in Apify Console')}: ${url}`);
+
+		simpleLog({ message: message.join('\n') });
+
+		return undefined;
+	}
+}

src/commands/builds/log.ts

@@ -0,0 +1,38 @@
+import { Args } from '@oclif/core';
+
+import { ApifyCommand } from '../../lib/apify_command.js';
+import { error, info } from '../../lib/outputs.js';
+import { getLoggedClientOrThrow, outputJobLog } from '../../lib/utils.js';
+
+export class BuildLogCommand extends ApifyCommand<typeof BuildLogCommand> {
+	static override description = 'Prints the log of a specific build';
+
+	static override args = {
+		buildId: Args.string({
+			required: true,
+			description: 'The build id to get the log from',
+		}),
+	};
+
+	async run() {
+		const { buildId } = this.args;
+
+		const apifyClient = await getLoggedClientOrThrow();
+
+		const build = await apifyClient.build(buildId).get();
+
+		if (!build) {
+			error({ message: `Build with ID "${buildId}" was not found on your account` });
+			return;
+		}
+
+		info({ message: `Log for build with ID "${buildId}":\n` });
+
+		try {
+			await outputJobLog(build);
+		} catch (err) {
+			// This should never happen...
+			error({ message: `Failed to get log for build with ID "${buildId}": ${(err as Error).message}` });
+		}
+	}
+}