feat: implement cli wrapper

packages/cli/.gitignore

@@ -0,0 +1,3 @@
+
+# midscene.js
+midscene_run/

packages/cli/.npmignore

@@ -0,0 +1,45 @@
+.DS_Store
+
+.pnp
+.pnp.js
+.evn.local
+.env.*.local
+.history
+.rts*
+*.log*
+*.pid
+*.pid.*
+*.report
+*.lcov
+lib-cov
+
+doc_build/
+node_modules/
+.npm
+.lock-wscript
+.yarn-integrity
+.node_repl_history
+.nyc_output
+*.tsbuildinfo
+.eslintcache
+.sonarlint
+
+coverage/
+release/
+output/
+output_resource/
+
+.vscode/**/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+**/*/api/typings/auto-generated
+**/*/adapters/**/index.ts
+**/*/adapters/**/index.js
+
+src/
+midscene_run/
+log/
+docs/
+tests/

packages/cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Midscene.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/cli/README.md

@@ -0,0 +1,7 @@
+## Documentation
+
+See https://midscenejs.com/ for details.
+
+## License
+
+Midscene is MIT licensed.

packages/cli/bin/midscene

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/lib/index.js');

packages/cli/modern.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig, moduleTools } from '@modern-js/module-tools';
+
+export default defineConfig({
+  plugins: [moduleTools()],
+  buildPreset: 'npm-library',
+  buildConfig: {
+    platform: 'node',
+    input: {
+      index: 'src/index.ts',
+    },
+    // input: ['src/utils.ts', 'src/index.ts', 'src/image/index.ts'],
+    externals: ['node:buffer'],
+    target: 'es2017',
+  },
+});

packages/cli/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@midscene/cli",
+  "description": "Cli for Midscene.js",
+  "version": "0.1.0",
+  "jsnext:source": "./src/index.ts",
+  "main": "./dist/lib/index.js",
+  "bin": {
+    "midscene": "./bin/midscene",
+    "mid": "./bin/midscene"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build",
+    "build:watch": "modern build -w",
+    "new": "modern new",
+    "upgrade": "modern upgrade",
+    "test": "vitest --run",
+    "test:all": "AITEST=true vitest --run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@midscene/web": "workspace:*",
+    "ora-classic": "5.4.2",
+    "puppeteer": "^22.8.0",
+    "yargs": "17.7.2"
+  },
+  "devDependencies": {
+    "@modern-js/module-tools": "^2.56.1",
+    "@types/node": "^18.0.0",
+    "@types/yargs": "17.0.32",
+    "typescript": "~5.0.4",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT"
+}

packages/cli/src/args.ts

@@ -0,0 +1,42 @@
+export type ArgumentValueType = string | boolean | number;
+
+export interface Argument {
+  name: string;
+  value: ArgumentValueType;
+}
+
+export function parse(args: string[]): Argument[] {
+  const orderedArgs: Argument[] = [];
+  args.forEach((arg, index) => {
+    if (arg.startsWith('--')) {
+      const key = arg.substring(2);
+      let value: ArgumentValueType =
+        args[index + 1] && !args[index + 1].startsWith('--')
+          ? args[index + 1]
+          : true;
+
+      if (typeof value === 'string' && /^\d+$/.test(value)) {
+        value = Number.parseInt(value, 10);
+      }
+      orderedArgs.push({ name: key, value });
+    }
+  });
+
+  return orderedArgs;
+}
+
+export function findOnlyItemInArgs(
+  args: Argument[],
+  name: string,
+): ArgumentValueType {
+  const found = args.filter((arg) => arg.name === name);
+  if (found.length === 0) {
+    return false;
+  }
+
+  if (found.length > 1) {
+    throw new Error(`Multiple values found for ${name}`);
+  }
+
+  return found[0].value;
+}

packages/cli/src/index.ts

@@ -0,0 +1,194 @@
+import { PuppeteerAgent } from '@midscene/web';
+import puppeteer from 'puppeteer';
+import { type ArgumentValueType, findOnlyItemInArgs, parse } from './args';
+import assert from 'node:assert';
+import ora from 'ora-classic';
+import { writeFileSync } from 'node:fs';
+
+let spinner: ora.Ora | undefined;
+const stepString = (name: string, param?: string) => {
+  const paramStr = name === 'sleep' ? `${param}ms` : param;
+  return `${name}\n  ${paramStr ? `${paramStr}` : ''}`;
+};
+
+const printStep = (name: string, param?: string) => {
+  if (spinner) {
+    spinner.stop();
+  }
+  console.log(`- ${stepString(name, param)}`);
+};
+
+const updateSpin = (text: string) => {
+  if (!spinner) {
+    spinner = ora(text);
+    spinner.start();
+  } else {
+    spinner.text = text;
+    spinner.start();
+  }
+};
+
+const preferenceArgs = {
+  url: 'url',
+  headed: 'headed',
+  viewportWidth: 'viewport-width',
+  viewportHeight: 'viewport-height',
+  viewportScale: 'viewport-scale',
+  useragent: 'user-agent',
+  // preferCache: 'prefer-cache',
+  // cookieJar: 'cookie-jar',
+};
+
+const actionArgs = {
+  action: 'action',
+  assert: 'assert',
+  queryOutput: 'query-output',
+  query: 'query',
+  sleep: 'sleep',
+};
+
+const defaultUA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36';
+
+const welcome = '\nWelcome to @midscene/cli\n';
+console.log(welcome);
+
+const args = parse(process.argv);
+
+// check each arg is either in the preferenceArgs or actionArgs
+args.forEach((arg) => {
+  assert(
+    Object.values(preferenceArgs).includes(arg.name) ||
+      Object.values(actionArgs).includes(arg.name),
+    `Unknown argument: ${arg.name}`,
+  );
+});
+
+// prepare the viewport config
+const preferHeaded = findOnlyItemInArgs(args, preferenceArgs.headed);
+const userExpectWidth = findOnlyItemInArgs(args, preferenceArgs.viewportWidth);
+const userExpectHeight = findOnlyItemInArgs(
+  args,
+  preferenceArgs.viewportHeight,
+);
+const userExpectDpr = findOnlyItemInArgs(args, preferenceArgs.viewportScale);
+const viewportConfig = {
+  width: typeof userExpectWidth === 'number' ? userExpectWidth : 1280,
+  height: typeof userExpectHeight === 'number' ? userExpectHeight : 1280,
+  deviceScaleFactor: typeof userExpectDpr === 'number' ? userExpectDpr : 1,
+};
+const url = findOnlyItemInArgs(args, preferenceArgs.url);
+assert(url, 'URL is required');
+assert(typeof url === 'string', 'URL must be a string');
+
+const preferredUA = findOnlyItemInArgs(args, preferenceArgs.useragent);
+const ua = typeof preferredUA === 'string' ? preferredUA : defaultUA;
+
+printStep(preferenceArgs.url, url);
+printStep(preferenceArgs.useragent, ua);
+printStep('viewport', JSON.stringify(viewportConfig));
+if (preferHeaded) {
+  printStep(preferenceArgs.headed, 'true');
+}
+
+Promise.resolve(
+  (async () => {
+    updateSpin(stepString('launch', 'puppeteer'));
+    const browser = await puppeteer.launch({
+      headless: !preferHeaded,
+    });
+
+    const page = await browser.newPage();
+    await page.setUserAgent(ua);
+
+    await page.setViewport(viewportConfig);
+
+    updateSpin(stepString('launch', url));
+    await page.goto(url);
+    updateSpin(stepString('waitForNetworkIdle', url));
+    await page.waitForNetworkIdle();
+    printStep('launched', url);
+
+    const agent = new PuppeteerAgent(page);
+
+    let errorWhenRunning: Error | undefined;
+    let argName: string;
+    let argValue: ArgumentValueType;
+    try {
+      let index = 0;
+      let outputPath: string | undefined;
+      while (index <= args.length - 1) {
+        const arg = args[index];
+        argName = arg.name;
+        argValue = arg.value;
+        const ifShouldUpdateSpin = Object.keys(actionArgs).includes(argName);
+        if (ifShouldUpdateSpin) {
+          updateSpin(stepString(argName, String(argValue)));
+        }
+        switch (argName) {
+          case actionArgs.action: {
+            const param = arg.value;
+            assert(param, 'missing action');
+            assert(typeof param === 'string', 'action must be a string');
+            await agent.aiAction(param);
+            printStep(argName, String(argValue));
+            break;
+          }
+          case actionArgs.assert: {
+            const param = arg.value;
+            assert(param, 'missing assert');
+            assert(typeof param === 'string', 'assert must be a string');
+            await agent.aiAssert(param);
+            printStep(argName, String(argValue));
+            break;
+          }
+          case actionArgs.queryOutput: {
+            const param = arg.value;
+            assert(param, 'missing query-output');
+            assert(typeof param === 'string', 'query-output must be a string');
+            outputPath = param;
+            printStep(argName, String(argValue));
+            break;
+          }
+          case actionArgs.query: {
+            const param = arg.value;
+            assert(param, 'missing query');
+            assert(typeof param === 'string', 'query must be a string');
+            const value = await agent.aiQuery(param);
+            printStep(argName, String(argValue));
+            printStep('answer', value);
+            if (outputPath) {
+              writeFileSync(
+                outputPath,
+                typeof value === 'object'
+                  ? JSON.stringify(value, null, 2)
+                  : value,
+              );
+            }
+            break;
+          }
+          case actionArgs.sleep: {
+            const param = arg.value;
+            if (!param) break;
+            assert(typeof param === 'number', 'sleep must be a number');
+            await new Promise((resolve) => setTimeout(resolve, param));
+            printStep(argName, String(argValue));
+            break;
+          }
+        }
+        index += 1;
+      }
+    } catch (e: any) {
+      printStep(`${argName!} - Failed`, String(argValue!));
+      printStep('Error', e.message);
+      errorWhenRunning = e;
+    }
+
+    await browser.close();
+    process.exit(errorWhenRunning ? 1 : 0);
+  })(),
+);
+
+// TODO: print report
+// TODO: --help
+// TODO: --version