@mindexec/cli 0.2.0

package/README.md

@@ -0,0 +1,275 @@
+# MindExec Local Bridge Server
+
+??Blazor ?깆뿉??濡쒖뺄 ?뚯씪 ?쒖뒪?쒖뿉 ?묎렐?섍린 ?꾪븳 Node.js 釉뚮━吏€ ?쒕쾭?낅땲??
+
+## npm quick start
+
+```bash
+npx @mindexec/cli
+```
+
+The npm CLI now starts both pieces of the local product:
+
+- MindCanvas app: `http://localhost:5147/mindcanvas`
+- LocalBridge API: `http://127.0.0.1:5147/api/status`
+- Workspace assets: `http://127.0.0.1:5147/assets/...`
+
+By default the CLI opens the MindCanvas app in your default browser after the
+bridge is ready. Use `mindexec --no-open` or `MINDEXEC_NO_OPEN=1` when you only
+want to start the listener.
+
+For local frontend development, keep LocalBridge running and refresh the
+packaged app bundle after code changes:
+
+```powershell
+.\scripts\publish-mindexec-cli.ps1 -AppOnly
+```
+
+Then hard-refresh `http://localhost:5147/mindcanvas` in the browser.
+
+The app and bridge are packaged together. Run `scripts/publish-mindexec-cli.ps1`
+from the repository root before publishing so the latest
+`MindExecution.Web` WASM `wwwroot` is copied into `LocalBridge/wwwroot`.
+The packaged app is configured with `Bridge:Url=app-origin`, so custom
+`BRIDGE_PORT` values keep the WASM app and LocalBridge API on the same origin.
+The publish helper trims hosted/demo-only gallery images and unused
+precompressed static files from the npm bundle by default. Use
+`-KeepPackagedGalleryImages` or `-KeepPackagedPrecompressedAssets` only when
+testing a full untrimmed local package.
+
+?먮뒗 ?꾩뿭 ?ㅼ튂 ???ㅽ뻾?⑸땲??
+
+```bash
+npm install -g @mindexec/cli
+mindexec
+```
+
+湲곕낯 ?ㅽ뻾 二쇱냼??`http://127.0.0.1:5147`?낅땲?? `WORKSPACE_PATH`媛€ 鍮꾩뼱 ?덉쑝硫??ㅼ튂???⑦궎吏€??遺€紐??대뜑瑜?湲곕낯 ?묒뾽 怨듦컙?쇰줈 ?ъ슜?⑸땲??
+
+```bash
+BRIDGE_PORT=8080 WORKSPACE_PATH=/custom/path mindexec
+```
+
+?꾩?留먭낵 踰꾩쟾 ?뺤씤:
+
+```bash
+mindexec --help
+mindexec --version
+```
+
+## ?ㅼ튂
+
+```bash
+cd LocalBridge
+npm install
+```
+
+## ?ㅽ뻾
+
+### ?쇰컲 ?ㅽ뻾
+```bash
+cd LocalBridge
+npm start
+```
+
+`npm start`??`WORKSPACE_PATH`媛€ 鍮꾩뼱 ?덉쑝硫?`LocalBridge`??遺€紐??대뜑(蹂댄넻 ?€?μ냼 猷⑦듃)瑜?湲곕낯 ?묒뾽 怨듦컙?쇰줈 ?ъ슜?⑸땲??
+
+### macOS / Linux?먯꽌 ?명븯寃??ㅽ뻾
+```bash
+cd LocalBridge
+chmod +x start-bridge.sh
+./start-bridge.sh
+```
+
+`start-bridge.sh`???ㅼ쓬???먮룞?쇰줈 泥섎━?⑸땲??
+- `WORKSPACE_PATH`媛€ ?놁쑝硫??€?μ냼 猷⑦듃瑜??묒뾽 怨듦컙?쇰줈 ?ъ슜
+- `BRIDGE_PORT`媛€ ?놁쑝硫?`5147` ?ъ슜
+- 媛숈? ?ы듃???대? 釉뚮━吏€媛€ ???덉쑝硫?以묐났 ?ㅽ뻾 諛⑹?
+- ?ㅻⅨ OS?먯꽌 蹂듭궗????`node_modules`媛€ 媛먯??섎㈃ ?꾩옱 ?뚮옯?쇱슜?쇰줈 ?ㅼ떆 `npm install`
+
+### 媛쒕컻 紐⑤뱶 (?먮룞 ?ъ떆??
+```bash
+npm run dev
+```
+
+### ?섍꼍 蹂€??
+
+| 蹂€??| ?ㅻ챸 | 湲곕낯媛?|
+|------|------|--------|
+| `BRIDGE_PORT` | ?쒕쾭 ?ы듃 | 5147 |
+| `WORKSPACE_PATH` | ?묒뾽 怨듦컙 寃쎈줈 | `LocalBridge` ?먮뒗 ?ㅼ튂 ?⑦궎吏€??遺€紐??대뜑 (?놁쑝硫?`~/Documents/MindExecution`) |
+| `BRIDGE_TOKEN` | ?꾪뿕 REST API???ъ슜??怨좎젙 ?좏겙. 鍮꾩슦硫??ㅽ뻾 ???쒕뜡 ?앹꽦 | ?쒕뜡 |
+| `BRIDGE_REQUIRE_TOKEN` | `false`/`0`/`off`濡??ㅼ젙?섎㈃ REST ?좏겙 寃€??鍮꾪솢?깊솕 | true |
+| `COMPANY_CORE_URL` | CompanyCore 濡쒖뺄 API 二쇱냼. `/api/company-core/*` ?꾨줉???€??| http://127.0.0.1:5077 |
+| `BRIDGE_SKIP_PORT_REAP` | ?쒖옉 ???숈씪 ?ы듃??湲곗〈 MindExec bridge ?뺣━瑜?嫄대꼫?? | false |
+| `BRIDGE_FORCE_KILL_PORT_OWNER` | `BRIDGE_PORT`瑜??≪쓣 ?꾩쓽 ?꾨줈?몄뒪瑜??뺣━ | false |
+
+?덉떆:
+```bash
+BRIDGE_PORT=8080 WORKSPACE_PATH=/custom/path npm start
+```
+
+macOS / Linux?먯꽌 ?ㅽ겕由쏀듃?€ ?④퍡 ?ㅽ뻾???뚮룄 ?숈씪?⑸땲??
+```bash
+BRIDGE_PORT=8080 WORKSPACE_PATH=/custom/path ./start-bridge.sh
+```
+
+## API ?붾뱶?ъ씤??
+
+### ?곹깭 ?뺤씤
+- `GET /api/status` - ?쒕쾭 ?곹깭 ?뺤씤, `/events`??`wsToken`怨??꾪뿕 REST API??`bridgeToken` 諛섑솚
+
+### ?묒뾽 怨듦컙
+- `GET /api/workspace` - ?꾩옱 ?묒뾽 怨듦컙 ?뺣낫
+- `POST /api/workspace/set` - ?묒뾽 怨듦컙 寃쎈줈 ?ㅼ젙
+
+### ?뚯씪 ?묒뾽
+- `POST /api/file/read` - ?뚯씪 ?쎄린
+- `POST /api/file/write` - ?뚯씪 ?곌린
+- `POST /api/file/delete` - ?뚯씪 ??젣
+- `POST /api/file/exists` - ?뚯씪 議댁옱 ?뺤씤
+- `POST /api/file/copy` - ?뚯씪 蹂듭궗
+- `POST /api/file/move` - ?뚯씪 ?대룞/?대쫫 蹂€寃?
+- `POST /api/file/info` - ?뚯씪 ?뺣낫
+
+### ?붾젆?좊━ ?묒뾽
+- `POST /api/dir/create` - ?붾젆?좊━ ?앹꽦
+- `POST /api/dir/list` - ?붾젆?좊━ 紐⑸줉
+- `POST /api/dir/delete` - ?붾젆?좊━ ??젣
+
+### ???ㅽ뻾
+- `POST /api/shell/execute` - ??紐낅졊 ?ㅽ뻾. 湲곗〈 ?명솚?⑹씠硫??대??곸쑝濡?job ?대깽?몃? `/events`濡??꾩넚
+- `POST /api/shell/jobs` - ??紐낅졊??諛깃렇?쇱슫??job?쇰줈 ?쒖옉?섍퀬 `jobId` 諛섑솚
+- `GET /api/shell/jobs/:jobId` - job ?곹깭/異쒕젰 議고쉶
+- `POST /api/shell/jobs/:jobId/cancel` - ?ㅽ뻾 以묒씤 job 痍⑥냼
+
+### ?대깽???ㅽ듃由?- `WebSocket /events?token=<wsToken>` - ?꾨줈?앺듃 蹂€寃쎄낵 shell/Codex job ?대깽?몃? push
+
+Shell/Codex job ?대깽??
+- `ShellQueued`
+- `ShellStarted`
+- `ShellStdout`
+- `ShellStderr`
+- `ShellCompleted`
+- `ShellFailed`
+- `ShellCancelRequested`
+
+### OpenAI Codex runtime
+- `GET /api/codex/capabilities` - TypeScript SDK / App Server scaffold / Legacy Exec provider availability
+- `POST /api/codex/thread/start` - start a local Codex thread
+- `POST /api/codex/thread/run` - run a Codex turn. Uses `@openai/codex-sdk` first and falls back to legacy `codex exec`
+- `POST /api/codex/thread/resume` - resume a stored SDK thread by id
+- `POST /api/codex/thread/cancel` - cancel an active turn
+- `GET /api/codex/thread/:threadId/status` - inspect local thread status and compact run metadata
+
+The TypeScript SDK runs only inside LocalBridge. Browser/WASM clients should call these bridge endpoints and must not import or execute Codex SDK packages directly.
+
+### Port ownership
+
+On startup, LocalBridge checks `BRIDGE_PORT` and stops an existing MindExec/LocalBridge listener on that same port before binding. If the port is owned by an unrelated process, startup fails with a clear message instead of silently killing it. Set `BRIDGE_FORCE_KILL_PORT_OWNER=1` only when the launcher owns that port policy and should terminate any listener.
+
+The `start-bridge.bat` and `start-bridge.sh` wrappers always delegate startup to `launch-bridge.cjs`, so port cleanup is handled by the same guard path on every launch.
+### CompanyCore ?꾨줉??- `GET /api/company-core/health` -> `CompanyCore /health`
+- `GET /api/company-core/companies` -> `CompanyCore /api/companies`
+- `POST /api/company-core/companies/create-and-run` -> `CompanyCore /api/companies/create-and-run`
+
+MindExec Web?€ CompanyCore ?ы듃瑜?吏곸젒 ???꾩슂 ?놁씠 LocalBridge `5147`留??몄텧?섎㈃ ?⑸땲?? ???꾨줉?쒕룄 Bridge Token 蹂댄샇瑜?諛쏆뒿?덈떎.
+
+## 蹂댁븞 二쇱쓽?ы빆
+
+- ???쒕쾭??**濡쒖뺄?몄뒪??127.0.0.1)?먯꽌留?* ?묎렐 媛€?ν빀?덈떎.
+- ?묒뾽 怨듦컙 ?몃????뚯씪?먮뒗 ?묎렐?????놁뒿?덈떎.
+- ?꾪뿕????紐낅졊(rm -rf, format ???€ 李⑤떒?⑸땲??
+- ?뚯씪 ?곌린/??젣, ?붾젆?좊━ ?앹꽦/??젣, asset ?낅줈?? shell, project open/close 媛숈? ?꾪뿕 REST API??湲곕낯?곸쑝濡?`X-Bridge-Token` ?먮뒗 `Authorization: Bearer <token>`???꾩슂?⑸땲??
+- ?좏겙?€ `GET /api/status`??`bridgeToken`?쇰줈 ?뺤씤?⑸땲?? 怨좎젙 ?좏겙???꾩슂?섎㈃ `BRIDGE_TOKEN` ?섍꼍 蹂€?섎? ?ъ슜?섏꽭??
+
+## ?ъ슜 ?덉떆
+
+### ?뚯씪 ?쎄린
+```javascript
+const response = await fetch('http://127.0.0.1:5147/api/file/read', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: 'test.txt' })
+});
+const data = await response.json();
+console.log(data.content);
+```
+
+### ?뚯씪 ?곌린
+```javascript
+const status = await fetch('http://127.0.0.1:5147/api/status').then(r => r.json());
+
+await fetch('http://127.0.0.1:5147/api/file/write', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        [status.bridgeTokenHeader || 'X-Bridge-Token']: status.bridgeToken
+    },
+    body: JSON.stringify({ 
+        path: 'test.txt', 
+        content: 'Hello, World!' 
+    })
+});
+```
+
+### ??紐낅졊 ?ㅽ뻾
+```javascript
+const status = await fetch('http://127.0.0.1:5147/api/status').then(r => r.json());
+
+const response = await fetch('http://127.0.0.1:5147/api/shell/execute', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        [status.bridgeTokenHeader || 'X-Bridge-Token']: status.bridgeToken
+    },
+    body: JSON.stringify({ 
+        command: 'dir',
+        timeout: 30000 
+    })
+});
+const result = await response.json();
+console.log(result.stdout);
+```
+
+### ??job ?ㅽ듃由щ컢
+```javascript
+const status = await fetch('http://127.0.0.1:5147/api/status').then(r => r.json());
+const ws = new WebSocket(`ws://127.0.0.1:5147/events?token=${encodeURIComponent(status.wsToken)}`);
+
+ws.onmessage = (message) => {
+    const event = JSON.parse(message.data);
+    if (event.type === 'ShellStdout') console.log(event.payload.chunk);
+    if (event.type === 'ShellCompleted') console.log('done', event.payload.jobId);
+};
+
+await fetch('http://127.0.0.1:5147/api/shell/jobs', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+        [status.bridgeTokenHeader || 'X-Bridge-Token']: status.bridgeToken
+    },
+    body: JSON.stringify({
+        command: 'codex exec \"Summarize this repository\"',
+        timeout: 300000
+    })
+});
+```
+
+## CORS
+
+湲곕낯?곸쑝濡??ㅼ쓬 origin?ㅼ씠 ?덉슜?⑸땲??
+- http://localhost:5000
+- http://localhost:5001
+- https://localhost:5001
+- http://127.0.0.1:5000
+- http://127.0.0.1:5001
+
+異붽? origin???꾩슂?섎㈃ `server.js`??CORS ?ㅼ젙???섏젙?섏꽭??
+
+## Web怨?MAUI ?숈떆 ?ъ슜
+
+1. 釉뚮━吏€ ?쒕쾭瑜??ㅽ뻾?⑸땲??(`npm start`)
+2. Web Blazor ?깆쓣 ?ㅽ뻾?⑸땲??
+3. MAUI ?깆? 釉뚮━吏€ ?쒕쾭 ?놁씠???묐룞?⑸땲??(吏곸젒 ?뚯씪 ?쒖뒪???묎렐)
+