Introduce a CLI

bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

bin/dev.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+
+// eslint-disable-next-line n/shebang
+import { execute } from '@oclif/core'
+
+await execute({ development: true, dir: import.meta.url })

bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from '@oclif/core'
+
+await execute({ dir: import.meta.url })

package.json

@@ -1,14 +1,14 @@
 {
   "name": "@publicodes/tools",
   "version": "1.2.5",
-  "description": "A set of utility functions to build tools around Publicodes models",
+  "description": "A CLI tool for Publicodes",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsup",
     "watch": "tsup --watch",
     "clean": "rm -rf dist docs",
-    "test": "jest",
+    "test": "vitest --globals",
     "docs": "typedoc",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
@@ -39,7 +39,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "bin"
   ],
   "repository": {
     "type": "git",
@@ -55,31 +56,39 @@
   ],
   "author": "Emile Rolley <[email protected]>",
   "license": "MIT",
+  "bin": {
+    "publicodes": "./bin/run.js"
+  },
   "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "@oclif/core": "^4.0.23",
     "@types/node": "^18.11.18",
+    "chalk": "^5.3.0",
     "glob": "^10.4.1",
     "path": "^0.12.7",
     "publicodes": "^1.3.3",
     "yaml": "^2.4.5"
   },
   "devDependencies": {
+    "@oclif/test": "^4.0.9",
     "@types/jest": "^29.2.5",
     "docdash": "^2.0.1",
-    "jest": "^29.4.1",
     "prettier": "^3.0.0",
     "ts-jest": "^29.0.4",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.2",
     "typedoc": "^0.24.8",
     "typedoc-plugin-export-functions": "^1.0.0",
-    "typescript": "^4.9.4"
+    "typescript": "^4.9.4",
+    "vitest": "^2.1.1"
   },
   "tsup": {
     "entry": [
       "src/index.ts",
       "src/optims/index.ts",
       "src/compilation/index.ts",
-      "src/migration/index.ts"
+      "src/migration/index.ts",
+      "src/commands"
     ],
     "format": [
       "cjs",
@@ -90,6 +99,12 @@
     "clean": true,
     "cjsInterop": true
   },
+  "oclif": {
+    "bin": "publicodes",
+    "commands": "./dist/commands",
+    "dirname": "publicodes",
+    "topicSeparator": ":"
+  },
   "publishConfig": {
     "access": "public"
   }

src/commands/init.ts

@@ -0,0 +1,83 @@
+import { Args, Command, Flags, ux } from '@oclif/core'
+import { exec } from 'node:child_process'
+import * as p from '@clack/prompts'
+import chalk from 'chalk'
+import fs from 'fs'
+import path from 'path'
+import { basePackageJson, getPackageJson, PackageJson } from '../utils/pjson'
+
+export default class Init extends Command {
+  static override args = {}
+
+  static override description = 'initialize a new project'
+
+  static override examples = ['<%= command.id %>']
+
+  static override flags = {}
+
+  public async run(): Promise<void> {
+    p.intro(chalk.bgHex('#2975d1')(' publicodes init '))
+
+    const pjson = getPackageJson()
+
+    if (pjson) {
+      p.log.info(`Updating existing ${chalk.bold('package.json')} file`)
+      updatePackageJson(pjson)
+    } else {
+      p.log.step(`Creating a new ${chalk.bold('package.json')} file`)
+      const pjson = await askPackageJsonInfo()
+      updatePackageJson(pjson)
+    }
+
+    p.outro('🚀 publicodes is ready to use!')
+  }
+}
+
+function updatePackageJson(pjson: PackageJson): void {
+  const packageJsonPath = path.join(process.cwd(), 'package.json')
+  const fullPjson = { ...basePackageJson, ...pjson }
+  try {
+    fs.writeFileSync(packageJsonPath, JSON.stringify(fullPjson, null, 2))
+    p.log.success(`${chalk.bold('package.json')} file written`)
+  } catch (error) {
+    p.cancel(
+      `An error occurred while writing the ${chalk.magenta('package.json')} file`,
+    )
+    process.exit(1)
+  }
+}
+
+function askPackageJsonInfo(): Promise<PackageJson> {
+  const currentDir = path.basename(process.cwd())
+
+  return p.group(
+    {
+      name: () =>
+        p.text({
+          message: 'Name',
+          defaultValue: currentDir,
+          placeholder: currentDir,
+        }),
+      description: () => p.text({ message: 'Description', defaultValue: '' }),
+      version: () =>
+        p.text({
+          message: 'Version',
+          defaultValue: '1.0.0',
+          placeholder: '1.0.0',
+        }),
+      author: () => p.text({ message: 'Author', defaultValue: '' }),
+      license: () =>
+        p.text({
+          message: 'License',
+          defaultValue: 'MIT',
+          placeholder: 'MIT',
+        }),
+    },
+    {
+      onCancel: () => {
+        p.cancel('init cancelled')
+        process.exit(1)
+      },
+    },
+  )
+}

src/utils/pjson.ts

@@ -0,0 +1,47 @@
+import fs from 'fs'
+
+export type PackageJson = {
+  name: string
+  version: string
+  description: string
+  main?: string
+  type?: string
+  types?: string
+  files?: string[]
+  repository?: {
+    url: string
+    type: string
+  }
+  author: string
+  license: string
+  scripts?: {
+    [key: string]: string
+  }
+  peerDependencies?: {
+    [key: string]: string
+  }
+}
+
+export const basePackageJson: PackageJson = {
+  name: '',
+  version: '1.0.0',
+  description: '',
+  author: '',
+  type: 'module',
+  main: 'dist/index.js',
+  types: 'dist/index.d.ts',
+  license: 'MIT',
+  files: ['dist'],
+  peerDependencies: {
+    // TODO: how to get the latest version of publicodes?
+    publicodes: '^1.5.1',
+  },
+}
+
+export function getPackageJson(): PackageJson | undefined {
+  try {
+    return JSON.parse(fs.readFileSync('package.json', 'utf8'))
+  } catch (error) {
+    return undefined
+  }
+}

test/cli-utils.ts

@@ -0,0 +1,98 @@
+import {
+  ExecException,
+  execSync,
+  ExecSyncOptionsWithBufferEncoding,
+} from 'child_process'
+import path, { join } from 'path'
+import fs, { mkdtempSync } from 'fs'
+import os from 'os'
+
+export type ExecError = ExecException & { stderr: string; stdout: string }
+
+export type ExecOptions = ExecSyncOptionsWithBufferEncoding & {
+  silent?: boolean
+}
+
+export type ExecResult = {
+  code: number
+  stdout?: string
+  stderr?: string
+  error?: ExecError
+}
+
+const TEST_DATA_DIR = path.join(process.cwd(), 'test', 'commands-data')
+
+/**
+ * Utility test class to execute the CLI command
+ */
+export class CLIExecutor {
+  private binPath: string
+
+  constructor() {
+    const curentDir = process.cwd()
+    this.binPath =
+      process.platform === 'win32'
+        ? path.join(curentDir, 'bin', 'dev.cmd')
+        : path.join(curentDir, 'bin', 'dev.js')
+  }
+
+  public execCommand(cmd: string, options?: ExecOptions): Promise<ExecResult> {
+    const silent = options?.silent ?? true
+    const command = `${this.binPath} ${cmd}`
+    const cwd = process.cwd()
+
+    return new Promise((resolve) => {
+      if (silent) {
+        try {
+          const r = execSync(command, { ...options, stdio: 'pipe', cwd })
+          const stdout = r.toString()
+
+          resolve({ code: 0, stdout })
+        } catch (error) {
+          const err = error as ExecError
+          console.log(error)
+
+          resolve({
+            code: 1,
+            error: err,
+            stdout: err.stdout?.toString() ?? '',
+            stderr: err.stderr?.toString() ?? '',
+          })
+        }
+      } else {
+        execSync(command, { ...options, stdio: 'inherit', cwd })
+        resolve({ code: 0 })
+      }
+    })
+  }
+}
+
+// On macOS, os.tmpdir() is not a real path:
+// https://github.com/nodejs/node/issues/11422
+const TMP_DIR = fs.realpathSync(os.tmpdir())
+
+export async function runInDir(
+  dir: 'tmp' | string,
+  fn: () => Promise<void>,
+): Promise<void> {
+  const baseCwd = process.cwd()
+  const ctd =
+    dir === 'tmp'
+      ? mkdtempSync(path.join(TMP_DIR, 'publicodes-cli-test-'))
+      : path.join(TEST_DATA_DIR, dir)
+
+  if (!fs.existsSync(ctd)) {
+    fs.mkdirSync(ctd, { recursive: true })
+  }
+
+  process.chdir(ctd)
+
+  try {
+    await fn()
+  } finally {
+    process.chdir(baseCwd)
+    if (dir === 'tmp' && fs.existsSync(ctd)) {
+      fs.rmSync(ctd, { recursive: true })
+    }
+  }
+}

test/commands-data/yarn-init/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "yarn-init",
+  "version": "1.0.0",
+  "description": "",
+  "author": "",
+  "type": "module",
+  "main": "index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "publicodes": "^1.5.1"
+  }
+}

test/commands/base.test.ts

@@ -0,0 +1,13 @@
+import { CLIExecutor, runInDir } from '../cli-utils'
+
+describe('publicodes --help', () => {
+  it('should list all available commands', async () => {
+    const cli = new CLIExecutor()
+
+    runInDir('tmp', async () => {
+      const { stdout } = await cli.execCommand('--help')
+
+      expect(stdout).toContain('init  initialize a new project')
+    })
+  })
+})

test/commands/init.test.ts

@@ -0,0 +1,31 @@
+import { execSync } from 'child_process'
+import { CLIExecutor, runInDir } from '../cli-utils'
+import fs from 'fs'
+
+describe('publicodes init', () => {
+  it('should update existing package.json', async () => {
+    const cli = new CLIExecutor()
+
+    runInDir('tmp', async () => {
+      execSync('yarn init -y')
+      const { stdout } = await cli.execCommand('init')
+
+      expect(stdout).toContain('existing package.json file')
+      expect(stdout).toContain('package.json file written')
+      expect(stdout).toContain('🚀 publicodes is ready to use!')
+      const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf-8'))
+      expect(packageJson).toMatchObject({
+        type: 'module',
+        main: 'dist/index.js',
+        types: 'dist/index.d.ts',
+        files: ['dist'],
+        peerDependencies: {
+          publicodes: '^1.5.1',
+        },
+        devDependencies: {
+          '@publicodes/tools': '^1.5.1',
+        },
+      })
+    })
+  })
+})