govon 0.1.0 → 1.1.0

package/README.md

@@ -2,44 +2,44 @@
 
 npm wrapper for the [GovOn](https://github.com/umyunsang/GovOn) CLI.
 
-GovOn은 행정 지원 및 민원 처리 워크플로우를 위한 셸 퍼스트 로컬 에이전트 런타임입니다.
+GovOn is a shell-first local agent runtime for administrative support and civil complaint processing workflows.
 
-## 요구 사항
+## Requirements
 
-- **Node.js** 18 이상
-- **Python** 3.10 이상
-- **pip** (Python 패키지 관리자)
+- **Node.js** 18 or later
+- **Python** 3.10 or later
+- **pip** (Python package manager)
 
-## 설치
+## Installation
 
 ```bash
 npm install -g govon
 ```
 
-설치 후 Python 환경이 자동으로 확인됩니다.  
-`govon` Python 패키지가 설치되어 있지 않다면 아래 명령어로 설치하세요.
+After installation the Python environment is automatically verified.  
+If the `govon` Python package is not installed, install it with:
 
 ```bash
 pip install govon
 ```
 
-## 사용법
+## Usage
 
 ```bash
 govon --help
 ```
 
-## 동작 방식
+## How It Works
 
-이 패키지는 Python CLI(`govon`)를 감싸는 thin wrapper입니다.
+This package is a thin wrapper around the Python CLI (`govon`).
 
-1. `govon` 명령어 실행 시 Python 3.10+ 설치 여부를 확인합니다.
-2. `govon` CLI(`pip install govon`)가 설치되어 있는지 확인합니다.
-3. 조건이 충족되면 `child_process.spawn`을 통해 Python CLI에 실행을 위임합니다.
-4. 미충족 시 명확한 설치 안내 메시지를 출력하고 종료합니다.
+1. When the `govon` command is run, it checks whether Python 3.10+ is installed.
+2. It verifies that the `govon` CLI (`pip install govon`) is installed.
+3. If all conditions are met, execution is delegated to the Python CLI via `child_process.spawn`.
+4. If conditions are not met, a clear installation guide message is printed and the process exits.
 
-> Python 자동 설치는 보안 및 권한 이슈로 지원하지 않습니다.
+> Automatic Python installation is not supported due to security and permission concerns.
 
-## 라이선스
+## License
 
 MIT

package/bin/govon.js

@@ -6,18 +6,18 @@ const { printEnvironmentStatus, isGovonInstalled } = require('../lib/python-chec
 
 const args = process.argv.slice(2);
 
-// postinstall 또는 직접 호출 시 환경 점검만 수행하고 종료
+// On postinstall or direct invocation with --check-install, only run environment check and exit
 if (args[0] === '--check-install') {
   const ok = printEnvironmentStatus();
   process.exit(ok ? 0 : 1);
 }
 
-// 실제 CLI 실행 경로: 환경이 올바르지 않으면 안내 메시지를 출력하고 종료
+// Actual CLI execution path: if environment is not valid, print guidance and exit
 if (!printEnvironmentStatus()) {
   process.exit(1);
 }
 
-// govon CLI를 실제로 실행
+// Launch the govon CLI
 const child = spawn('govon', args, {
   stdio: 'inherit',
   shell: false,
@@ -28,13 +28,13 @@ child.on('error', (err) => {
     console.error(
       [
         '',
-        '  [govon] govon 명령어를 실행할 수 없습니다.',
-        '  pip install govon 으로 설치되었는지 확인하세요.',
+        '  [govon] Unable to execute the govon command.',
+        '  Please verify it is installed via: pip install govon',
         '',
       ].join('\n')
     );
   } else {
-    console.error(`[govon] 실행 오류: ${err.message}`);
+    console.error(`[govon] Execution error: ${err.message}`);
   }
   process.exit(1);
 });

package/lib/python-check.js

@@ -1,19 +1,21 @@
 'use strict';
 
 const { execSync, spawnSync } = require('child_process');
+const { realpathSync } = require('fs');
+const path = require('path');
 
 const MIN_PYTHON_MAJOR = 3;
 const MIN_PYTHON_MINOR = 10;
 
 /**
- * Python 실행 파일 후보 목록 (우선순위 순)
+ * List of Python executable candidates in priority order
  */
 const PYTHON_CANDIDATES = ['python3', 'python'];
 
 /**
- * 주어진 python 실행 파일의 버전을 반환합니다.
- * 실행 불가능하거나 파싱 실패 시 null을 반환합니다.
- * @param {string} cmd - 실행할 python 명령어
+ * Returns the version of the given Python executable.
+ * Returns null if the executable cannot be run or version parsing fails.
+ * @param {string} cmd - Python command to execute
  * @returns {{ major: number, minor: number } | null}
  */
 function getPythonVersion(cmd) {
@@ -21,7 +23,7 @@ function getPythonVersion(cmd) {
     const result = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 5000 });
     if (result.status !== 0 || result.error) return null;
 
-    // "Python 3.11.4" 또는 stderr에 출력될 수 있음 (Python 2)
+    // Output may appear as "Python 3.11.4" or on stderr (Python 2)
     const output = (result.stdout || result.stderr || '').trim();
     const match = output.match(/Python\s+(\d+)\.(\d+)/i);
     if (!match) return null;
@@ -33,7 +35,7 @@ function getPythonVersion(cmd) {
 }
 
 /**
- * 시스템에서 사용 가능한 Python 3.10+ 실행 파일을 찾습니다.
+ * Finds a Python 3.10+ executable available on the system.
  * @returns {{ cmd: string, major: number, minor: number } | null}
  */
 function findPython() {
@@ -51,22 +53,29 @@ function findPython() {
 }
 
 /**
- * `govon` CLI가 PATH에 설치되어 있는지 확인합니다.
- * npm의 govon.js wrapper가 아닌 Python의 govon binary를 찾습니다.
+ * Checks whether the `govon` CLI is installed in PATH.
+ * Looks for the Python govon binary, not the npm govon.js wrapper.
  * @returns {boolean}
  */
 function isGovonInstalled() {
   try {
-    // which/where로 govon 경로를 확인하여 Python binary인지 검증
+    // Verify govon path via which/where to confirm it is a Python binary
     const whichCmd = process.platform === 'win32' ? 'where' : 'which';
     const which = spawnSync(whichCmd, ['govon'], { encoding: 'utf8', timeout: 5000 });
     if (which.error || which.status !== 0) return false;
 
     const govonPath = (which.stdout || '').trim().split('\n')[0];
-    // npm bin 경로(node_modules/.bin)에 있으면 npm wrapper이므로 무시
-    if (govonPath.includes('node_modules')) return false;
+    // Resolve symlinks to detect npm wrapper even behind /usr/local/bin symlinks
+    let resolvedPath;
+    try {
+      resolvedPath = realpathSync(govonPath);
+    } catch {
+      resolvedPath = govonPath;
+    }
+    // If the resolved path is under node_modules/.bin it is the npm wrapper — ignore it
+    if (resolvedPath.includes('node_modules')) return false;
 
-    // Python module로 직접 확인
+    // Confirm directly via Python module
     const python = findPython();
     if (!python) return false;
 
@@ -81,7 +90,21 @@ function isGovonInstalled() {
 }
 
 /**
- * Python 환경 전체를 검사하고 결과를 반환합니다.
+ * Reads the npm package version from package.json for version pinning.
+ * @returns {string} - version string (e.g. "1.0.6"), or empty string on failure
+ */
+function getNpmPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = require(pkgPath);
+    return pkg.version || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Inspects the entire Python environment and returns the result.
  * @returns {{
  *   pythonFound: boolean,
  *   pythonCmd: string | null,
@@ -102,55 +125,99 @@ function checkEnvironment() {
 }
 
 /**
- * 환경 검사 결과를 stdout에 출력하고 문제가 있으면 안내 메시지를 표시합니다.
- * @returns {boolean} - 모든 조건이 충족되면 true
+ * Automatically installs the Python govon package via pip.
+ * Pins to the same version as the npm package to prevent version drift.
+ * @param {string} pythonCmd - path to the python executable
+ * @returns {boolean} - true if installation succeeded
  */
-function printEnvironmentStatus() {
-  const { pythonFound, pythonCmd, pythonVersion, govonInstalled } = checkEnvironment();
+function autoInstallGovon(pythonCmd) {
+  const version = getNpmPackageVersion();
+  const spec = version ? `govon==${version}` : 'govon';
 
-  if (!pythonFound) {
+  console.log('\n  [govon] Auto-installing the Python govon package…');
+  console.log(`  → ${pythonCmd} -m pip install ${spec}\n`);
+
+  const result = spawnSync(pythonCmd, ['-m', 'pip', 'install', spec], {
+    stdio: 'inherit',
+    timeout: 120000,
+  });
+
+  if (result.error || result.status !== 0) {
     console.error(
       [
         '',
-        '  [govon] Python 3.10 이상이 필요합니다.',
+        '  [govon] Auto-installation failed.',
         '',
-        '  Python을 설치한 뒤 다시 시도해 주세요:',
-        '    https://www.python.org/downloads/',
+        '  Please install manually with:',
+        `    ${pythonCmd} -m pip install ${spec}`,
         '',
-        '  또는 패키지 관리자를 이용하세요:',
-        '    macOS:   brew install python@3.12',
-        '    Ubuntu:  sudo apt install python3.12',
-        '    Windows: winget install Python.Python.3.12',
+        '  If you encounter a permission error:',
+        `    ${pythonCmd} -m pip install --user ${spec}`,
         '',
       ].join('\n')
     );
     return false;
   }
 
-  if (!govonInstalled) {
+  console.log('\n  [govon] ✓ Python govon package installed successfully.\n');
+  return true;
+}
+
+/**
+ * Prints the environment check result to stdout and displays guidance if issues are found.
+ * Attempts auto-installation if Python govon is not found.
+ * @returns {boolean} - true if all conditions are met
+ */
+function printEnvironmentStatus() {
+  const { pythonFound, pythonCmd, pythonVersion, govonInstalled } = checkEnvironment();
+
+  if (!pythonFound) {
     console.error(
       [
         '',
-        `  [govon] govon CLI가 설치되어 있지 않습니다. (Python ${pythonVersion} 감지됨)`,
+        '  [govon] Python 3.10 or later is required.',
         '',
-        '  아래 명령어로 설치해 주세요:',
-        `    ${pythonCmd} -m pip install govon`,
+        '  Please install Python and try again:',
+        '    https://www.python.org/downloads/',
         '',
-        '  가상환경을 사용하는 경우:',
-        '    python -m venv .venv && source .venv/bin/activate',
-        `    pip install govon`,
+        '  Or install via a package manager:',
+        '    macOS:   brew install python@3.12',
+        '    Ubuntu:  sudo apt install python3.12',
+        '    Windows: winget install Python.Python.3.12',
         '',
       ].join('\n')
     );
     return false;
   }
 
+  if (!govonInstalled) {
+    // Attempt auto-installation
+    if (!autoInstallGovon(pythonCmd)) {
+      return false;
+    }
+    // Re-verify after installation (resolve symlinks for accurate detection)
+    if (!isGovonInstalled()) {
+      console.error(
+        [
+          '',
+          '  [govon] govon CLI could not be found even after installation.',
+          '',
+          '  Please ensure the pip install path is included in your PATH.',
+          `  Or run directly: ${pythonCmd} -m govon`,
+          '',
+        ].join('\n')
+      );
+      return false;
+    }
+  }
+
   return true;
 }
 
 module.exports = {
   findPython,
   isGovonInstalled,
+  autoInstallGovon,
   checkEnvironment,
   printEnvironmentStatus,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "govon",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "npm wrapper for the GovOn CLI — Shell-first local agentic runtime for administrative assistance and civil complaint workflows",
   "keywords": [
     "govon",