golutra-mcp 0.1.0 → 0.1.1

package/.env.example

@@ -1,5 +1,6 @@
-# Optional. If unset, mcp-golutra first tries the macOS app-bundled CLI path
-# and then falls back to resolving `golutra-cli` from PATH.
+# Optional. If unset, golutra-mcp first tries platform-specific default
+# install paths for `golutra-cli`, then falls back to the platform command
+# name from PATH (`golutra-cli.exe` on Windows, `golutra-cli` elsewhere).
 GOLUTRA_CLI_PATH=golutra-cli
 GOLUTRA_PROFILE=stable
 GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format follows Keep a Changelog, and this project uses Semantic Versioning.
 
+## [Unreleased]
+
+## [0.1.1] - 2026-03-21
+
+### Changed
+
+- Synced `scripts/e2e-smoke.mjs` with the layered `golutra-diagnose` output so self-hosted smoke tests validate the current diagnostic contract
+- Expanded the basic GitHub Actions check workflow to run on Linux, macOS, and Windows so platform-specific regressions surface earlier
+- Included `docs/` in the npm publish file list so packaged users can open the referenced diagnostic example document locally
+- Renamed `startup_processmd.md` to `STARTUP_PROCESS.md` and updated repository links to use a stable public-facing document name
+- Removed stale `mcp-golutra` wording from the bug report template so issue reports match the published package name
+- Stopped hardcoding the MCP server runtime version in source scripts and now read it from `package.json`
+
 ## [0.1.0] - 2026-03-17
 
 ### Added
@@ -14,7 +27,7 @@ The format follows Keep a Changelog, and this project uses Semantic Versioning.
 - `golutra-reset-context` and `golutra-diagnose` for runtime troubleshooting
 - ESLint, TypeScript, and Vitest based quality gates
 - CI workflow, contribution guide, security policy, and code of conduct
-- Dedicated `startup_processmd.md` for setup/start/build/validation flow
+- Dedicated `STARTUP_PROCESS.md` for setup/start/build/validation flow
 
 ### Changed
 
@@ -27,6 +40,6 @@ The format follows Keep a Changelog, and this project uses Semantic Versioning.
 - Started tracking the built `dist/` output so GitHub source archives also include runnable server files instead of documentation only
 - Switched the user-facing default profile examples from `dev` to `stable` so published usage aligns with the release app instead of development builds
 - Reworked `README.md` into a project-introduction document focused on purpose, architecture, tool surface, and design boundaries
-- Moved startup, environment, and local development instructions out of `README.md` into `startup_processmd.md`
+- Moved startup, environment, and local development instructions out of `README.md` into `STARTUP_PROCESS.md`
 - Replaced `README.md` again with a bilingual project-homepage version that explains what the project is, what it is today, and the future direction in English and Chinese
-- Moved the remaining reference and operational material from `README.md` into `startup_processmd.md`
+- Moved the remaining reference and operational material from `README.md` into `STARTUP_PROCESS.md`

package/README.md

@@ -6,6 +6,45 @@
 
 ## English
 
+### Install
+
+`golutra-mcp` is now published on npm as `golutra-mcp`.
+
+Install it as a normal MCP server package:
+
+```bash
+npm install -g golutra-mcp
+```
+
+Run it with a published Golutra desktop installation.
+
+macOS:
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
 ### What This Project Is
 
 `golutra-mcp` is a Model Context Protocol server that exposes Golutra collaboration capabilities to MCP-compatible hosts through `golutra-cli`.
@@ -14,7 +53,7 @@ It is not a replacement for Golutra itself, and it does not re-implement Golutra
 
 ### What It Is Today
 
-The current project is a usable engineering preview, not yet a fully mature public integration product.
+The current project is an installable public MCP server release with its first npm distribution already published.
 
 Today it already provides:
 
@@ -24,7 +63,7 @@ Today it already provides:
 - skill validation and direct project `SKILL.md` reading for local Golutra skill workflows
 - an open-source project skeleton with contribution, security, CI, and release-facing metadata
 
-At the current stage, the project should be understood as a focused integration layer that can already be downloaded and evaluated, but still needs broader real-world validation before it should be treated as a fully mature public MCP distribution.
+At the current stage, it should be understood as a real downloadable integration package that is ready for evaluation, pilot usage, and downstream MCP wiring, but still needs broader real-world validation before it should be treated as a fully hardened long-term public integration product.
 
 ### Why It Exists
 
@@ -37,6 +76,33 @@ That means this repository is mainly responsible for:
 - safe command wrapping
 - diagnostics and integration ergonomics
 
+### Runtime Requirements
+
+To work correctly, the server still depends on the existing Golutra desktop runtime:
+
+- a locally installed Golutra desktop application
+- a reachable `golutra-cli` binary
+- a valid Golutra workspace path
+- the target Golutra desktop app profile running locally, usually `stable`
+
+Default CLI discovery by platform:
+
+- macOS: `/Applications/Golutra.app/Contents/MacOS/golutra-cli`, then `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`, then `golutra-cli` from `PATH`
+- Windows: `%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`, then `%ProgramFiles%\Golutra\golutra-cli.exe`, then `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`, then `golutra-cli.exe` from `PATH`
+- Linux: `~/.local/bin/golutra-cli`, then `~/.cargo/bin/golutra-cli`, then `/usr/local/bin/golutra-cli`, `/usr/bin/golutra-cli`, `/opt/Golutra/golutra-cli`, `/app/bin/golutra-cli`, then `golutra-cli` from `PATH`
+
+### Diagnostics
+
+Use `golutra-diagnose` when you need to separate:
+
+- CLI path problems
+- missing or invalid workspace paths
+- missing user identity for app-backed probes
+- app-not-running or profile-mismatch failures
+- generic app command failures
+
+Detailed diagnostic output fields and common `reasonCode` values are documented in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`.
+
 ### Future Direction
 
 The next stages should move the project from "basic bridge" to "usable integration product."
@@ -50,9 +116,9 @@ Likely future work includes:
 - tighter documentation around real Golutra collaboration workflows
 - stronger release hardening across installation paths, packaging validation, and end-to-end compatibility checks
 
-### Getting Started
+### Source Development
 
-Try from source first:
+If you want to run or modify the repository from source instead of installing the npm package:
 
 ```bash
 npm install
@@ -62,19 +128,48 @@ export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 npm run dev
 ```
 
-Use the npm package after you are ready to consume it as a normal MCP server distribution:
+Detailed startup, validation, and client wiring instructions live in `STARTUP_PROCESS.md`.
+
+## 中文
+
+### 安装方式
+
+`golutra-mcp` 现在已经以 `golutra-mcp` 这个包名发布到 npm。
+
+按普通 MCP Server 包安装即可：
 
 ```bash
 npm install -g golutra-mcp
-export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
+```
+
+建议配合已安装的 Golutra 桌面应用直接运行。
+
+macOS：
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
 export GOLUTRA_PROFILE=stable
 export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 golutra-mcp
 ```
 
-Detailed startup, validation, and client wiring instructions live in `startup_processmd.md`.
+Windows PowerShell：
 
-## 中文
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux：
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
 
 ### 这是什么项目
 
@@ -84,7 +179,7 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 
 ### 当前阶段是什么
 
-当前这个项目已经进入“可下载试用的工程化预发布”阶段，但还不能算“完全成熟、长期稳定的公共 MCP 成品”。
+当前这个项目已经进入“可下载安装的公开版本”阶段，并且第一版 npm 包已经发布。
 
 现阶段已经具备：
 
@@ -94,7 +189,7 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 技能校验与项目 `SKILL.md` 直接读取能力，能覆盖本地技能开发链路
 - 基本完整的开源项目骨架，包括贡献规范、安全策略、CI 和发布元数据
 
-但它现在还不是一个“已经经过广泛真实场景验证的完整 Golutra 远程集成产品”，更准确的定位是：一个已经能下载试用、也具备基本发布骨架的 MCP 集成底座。
+但它现在还不是一个“已经经过大规模真实场景验证、长期充分打磨”的成熟公共集成产品。更准确的定位是：一个已经可以下载安装、接入验证、试点使用的 Golutra MCP 集成层。
 
 ### 这个项目解决什么问题
 
@@ -107,6 +202,33 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 对现有 CLI 能力的稳定封装
 - 联通诊断与集成体验
 
+### 运行前提
+
+这个 MCP Server 运行时依赖现有的 Golutra 本地运行环境：
+
+- 本机已安装 Golutra 桌面应用
+- 能访问到 `golutra-cli`
+- 已知的有效工作区路径
+- 本地已启动目标 profile 的 Golutra 桌面应用，通常使用 `stable`
+
+按平台的默认 CLI 自动发现顺序：
+
+- macOS：`/Applications/Golutra.app/Contents/MacOS/golutra-cli`，然后 `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`，最后回退到 `PATH` 里的 `golutra-cli`
+- Windows：`%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`，然后 `%ProgramFiles%\Golutra\golutra-cli.exe`，再然后 `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`，最后回退到 `PATH` 里的 `golutra-cli.exe`
+- Linux：`~/.local/bin/golutra-cli`，然后 `~/.cargo/bin/golutra-cli`、`/usr/local/bin/golutra-cli`、`/usr/bin/golutra-cli`、`/opt/Golutra/golutra-cli`、`/app/bin/golutra-cli`，最后回退到 `PATH` 里的 `golutra-cli`
+
+### 诊断能力
+
+需要排查问题时，可以优先用 `golutra-diagnose` 区分：
+
+- CLI 路径问题
+- workspacePath 缺失或非法
+- userId 缺失导致 app 探针跳过
+- 桌面应用未运行或 profile 不匹配
+- 普通 app 命令失败
+
+更完整的诊断输出字段和常见 `reasonCode` 说明见 `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`。
+
 ### 后续规划
 
 后续项目应该从“能桥接”继续推进到“更好用、可发布、可维护”。
@@ -120,9 +242,9 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 补齐围绕真实 Golutra 协作场景的文档和示例
 - 继续补强跨平台安装路径、自诊断、端到端兼容性验证
 
-### 开始使用
+### 源码开发
 
-建议先从源码试用：
+如果你要按源码方式运行或参与开发：
 
 ```bash
 npm install
@@ -132,22 +254,14 @@ export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 npm run dev
 ```
 
-确认链路符合预期后，再按普通 MCP 包的方式安装：
-
-```bash
-npm install -g golutra-mcp
-export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
-export GOLUTRA_PROFILE=stable
-export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
-golutra-mcp
-```
-
-更完整的启动、验证与客户端接入说明见 `startup_processmd.md`。
+更完整的启动、验证与客户端接入说明见 `STARTUP_PROCESS.md`。
 
 ## Documentation
 
 - Startup, installation, validation, and MCP client wiring:
-  [startup_processmd.md](./startup_processmd.md)
+  [STARTUP_PROCESS.md](./STARTUP_PROCESS.md)
+- Diagnostic output examples and reason codes:
+  [docs/GOLUTRA_DIAGNOSE_EXAMPLES.md](./docs/GOLUTRA_DIAGNOSE_EXAMPLES.md)
 - Contribution guide:
   [CONTRIBUTING.md](./CONTRIBUTING.md)
 - Security policy:

package/{startup_processmd.md → STARTUP_PROCESS.md}

@@ -1,4 +1,4 @@
-# startup_processmd
+# STARTUP_PROCESS
 
 This document contains the setup, startup, build, validation, local integration steps, and the detailed operational notes previously kept in `README.md`.
 
@@ -43,6 +43,9 @@ This repository focuses on protocol translation, context management, diagnostics
 - `golutra-set-context` updates defaults for later tool calls
 - `golutra-reset-context` restores defaults from the process environment used at startup
 - `golutra-diagnose` verifies `golutra-cli` reachability and, when both `workspacePath` and `userId` are available, probes app connectivity with `chat.conversations.list`
+- `golutra-diagnose` now returns layered checks for `cliPath`, `cliCommand`, `workspace`, `userId`, and `appConnection`
+- `golutra-diagnose` also returns `summary.status` (`ok`, `partial`, `error`), `reasonCodes`, and `nextSteps`
+- Detailed output examples and common `reasonCode` values live in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`
 
 ### Current Limitations
 
@@ -76,7 +79,7 @@ It still needs more real-world validation across MCP hosts, operating systems, a
 ## Environment Variables
 
 - `GOLUTRA_CLI_PATH`
-  Default: auto-discover the macOS app-bundled CLI when available, otherwise `golutra-cli`
+  Default: auto-discover a platform-specific `golutra-cli` install when available, otherwise fall back to the platform command name from `PATH`
 - `GOLUTRA_PROFILE`
   Optional Golutra runtime profile: `dev`, `canary`, or `stable`
 - `GOLUTRA_WORKSPACE_PATH`
@@ -86,6 +89,12 @@ It still needs more real-world validation across MCP hosts, operating systems, a
 
 Use [.env.example](./.env.example) as the minimal local template.
 
+Default CLI discovery order:
+
+- macOS: `/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `golutra-cli`
+- Windows: `%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`, `%ProgramFiles%\Golutra\golutra-cli.exe`, `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`, `golutra-cli.exe`
+- Linux: `~/.local/bin/golutra-cli`, `~/.cargo/bin/golutra-cli`, `/usr/local/bin/golutra-cli`, `/usr/bin/golutra-cli`, `/opt/Golutra/golutra-cli`, `/app/bin/golutra-cli`, `golutra-cli`
+
 ## Install Dependencies
 
 ```bash
@@ -102,6 +111,35 @@ npm install -g golutra-mcp
 
 Then configure your MCP client to launch `golutra-mcp` directly.
 
+Typical launch examples by platform:
+
+macOS:
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
 ## Local Development
 
 Start the MCP server directly from source:
@@ -205,7 +243,7 @@ Recommended runner prerequisites:
 Repository variables:
 
 - `GOLUTRA_E2E_WORKSPACE_PATH`: required unless provided as a workflow input
-- `GOLUTRA_E2E_CLI_PATH`: optional, defaults to `/Applications/Golutra.app/Contents/MacOS/golutra-cli`
+- `GOLUTRA_E2E_CLI_PATH`: optional, defaults to the same platform-specific discovery rules as runtime startup; macOS runners commonly use `/Applications/Golutra.app/Contents/MacOS/golutra-cli`
 - `GOLUTRA_E2E_PROFILE`: optional, defaults to `stable`
 - `GOLUTRA_E2E_USER_ID`: required only when the workflow is run with `app_probe=true`
 

package/dist/index.js

@@ -4,9 +4,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { NodeCliJsonRunner } from "./lib/cli-runner.js";
 import { ContextStore, createInitialContext } from "./lib/context.js";
 import { GolutraCliGateway } from "./lib/golutra-client.js";
+import { readPackageMetadata } from "./lib/package-metadata.js";
 import { registerTools } from "./lib/toolkit.js";
-const SERVER_NAME = "golutra-mcp";
-const SERVER_VERSION = "0.1.0";
+const { name: SERVER_NAME, version: SERVER_VERSION } = readPackageMetadata();
 async function main() {
     const server = new McpServer({
         name: SERVER_NAME,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAC;IAE/D,kDAAkD;IAClD,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,qBAAqB,OAAO,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,mBAAmB,EAAE,CAAC;AAE7E,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAC;IAE/D,kDAAkD;IAClD,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,qBAAqB,OAAO,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/context.js

@@ -4,11 +4,23 @@ import path from "node:path";
 import { GOLUTRA_PROFILES } from "./types.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
-const DEFAULT_CLI_COMMAND = "golutra-cli";
 function normalizeNonEmptyString(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
 }
+function uniqueNonEmptyPaths(candidatePaths) {
+    const seen = new Set();
+    const result = [];
+    for (const candidatePath of candidatePaths) {
+        const normalizedPath = candidatePath.trim();
+        if (!normalizedPath || seen.has(normalizedPath)) {
+            continue;
+        }
+        seen.add(normalizedPath);
+        result.push(normalizedPath);
+    }
+    return result;
+}
 function normalizeTimeout(value) {
     if (typeof value === "number" && Number.isInteger(value) && value > 0) {
         return Math.min(value, MAX_TIMEOUT_MS);
@@ -31,15 +43,49 @@ function normalizeProfile(value) {
     }
     throw new Error(`Unsupported Golutra profile: ${trimmed}`);
 }
-function getDefaultCliCandidates(platform, homeDirectory) {
+function getDefaultCliCommand(platform) {
+    return platform === "win32" ? "golutra-cli.exe" : "golutra-cli";
+}
+function getPathModule(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+function getDefaultCliCandidates(env, platform, homeDirectory) {
+    const pathModule = getPathModule(platform);
     if (platform === "darwin") {
-        return [
+        return uniqueNonEmptyPaths([
             "/Applications/Golutra.app/Contents/MacOS/golutra-cli",
-            path.join(homeDirectory, "Applications", "Golutra.app", "Contents", "MacOS", "golutra-cli"),
-            DEFAULT_CLI_COMMAND
-        ];
+            pathModule.join(homeDirectory, "Applications", "Golutra.app", "Contents", "MacOS", "golutra-cli"),
+            getDefaultCliCommand(platform)
+        ]);
+    }
+    if (platform === "win32") {
+        const localAppData = normalizeNonEmptyString(env.LOCALAPPDATA) ??
+            pathModule.join(homeDirectory, "AppData", "Local");
+        const programFiles = normalizeNonEmptyString(env.ProgramFiles);
+        const programFilesX86 = normalizeNonEmptyString(env["ProgramFiles(x86)"]);
+        const cliName = getDefaultCliCommand(platform);
+        return uniqueNonEmptyPaths([
+            pathModule.join(localAppData, "Programs", "Golutra", cliName),
+            ...(programFiles ? [pathModule.join(programFiles, "Golutra", cliName)] : []),
+            ...(programFilesX86
+                ? [pathModule.join(programFilesX86, "Golutra", cliName)]
+                : []),
+            cliName
+        ]);
+    }
+    if (platform === "linux") {
+        const cliName = getDefaultCliCommand(platform);
+        return uniqueNonEmptyPaths([
+            pathModule.join(homeDirectory, ".local", "bin", cliName),
+            pathModule.join(homeDirectory, ".cargo", "bin", cliName),
+            "/usr/local/bin/golutra-cli",
+            "/usr/bin/golutra-cli",
+            "/opt/Golutra/golutra-cli",
+            "/app/bin/golutra-cli",
+            cliName
+        ]);
     }
-    return [DEFAULT_CLI_COMMAND];
+    return [getDefaultCliCommand(platform)];
 }
 export function resolveDefaultCliPath(env, options = {}) {
     const explicitCliPath = normalizeNonEmptyString(env.GOLUTRA_CLI_PATH);
@@ -49,8 +95,10 @@ export function resolveDefaultCliPath(env, options = {}) {
     const platform = options.platform ?? process.platform;
     const homeDirectory = options.homeDirectory ?? homedir();
     const pathExists = options.pathExists ?? existsSync;
-    const candidates = getDefaultCliCandidates(platform, homeDirectory);
-    return (candidates.find((candidatePath) => path.isAbsolute(candidatePath) && pathExists(candidatePath)) ?? DEFAULT_CLI_COMMAND);
+    const candidates = getDefaultCliCandidates(env, platform, homeDirectory);
+    const fallbackCommand = getDefaultCliCommand(platform);
+    const pathModule = getPathModule(platform);
+    return (candidates.find((candidatePath) => pathModule.isAbsolute(candidatePath) && pathExists(candidatePath)) ?? fallbackCommand);
 }
 export function createInitialContext(env) {
     return {

package/dist/lib/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/lib/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/lib/context.ts"],"names":[],"mappings":"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"}

package/dist/lib/diagnostics.d.ts

@@ -0,0 +1,34 @@
+import type { RuntimeContextSnapshot } from "./types.js";
+export type DiagnosisReasonCode = "CLI_PATH_NOT_FOUND" | "CLI_NOT_FOUND" | "CLI_TIMEOUT" | "CLI_PROTOCOL_ERROR" | "CLI_COMMAND_FAILED" | "WORKSPACE_PATH_MISSING" | "WORKSPACE_PATH_NOT_FOUND" | "WORKSPACE_PATH_NOT_DIRECTORY" | "WORKSPACE_PATH_INVALID" | "USER_ID_MISSING" | "APP_NOT_RUNNING_OR_PROFILE_MISMATCH" | "APP_COMMAND_FAILED" | "APP_PROBE_SKIPPED";
+export interface DiagnosisCheck {
+    ok: boolean;
+    skipped?: boolean;
+    reasonCode?: DiagnosisReasonCode;
+    message?: string;
+    error?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function inspectCliPath(cliPath: string): DiagnosisCheck & {
+    cliPath: string;
+    source: "explicit-path" | "command-from-path";
+    exists?: boolean;
+};
+export declare function inspectWorkspacePath(workspacePath: string | undefined): DiagnosisCheck & {
+    workspacePath?: string;
+};
+export declare function inspectUserId(userId: string | undefined): DiagnosisCheck & {
+    userId?: string;
+};
+export declare function classifyCliProbeFailure(error: unknown): DiagnosisCheck & {
+    nextSteps: string[];
+};
+export declare function classifyAppProbeFailure(error: unknown, runtimeContext: RuntimeContextSnapshot): DiagnosisCheck & {
+    nextSteps: string[];
+};
+export declare function buildSkippedAppProbe(reasonCode: DiagnosisReasonCode, message: string): DiagnosisCheck;
+export declare function summarizeDiagnosis(checks: Record<string, DiagnosisCheck>): {
+    ok: boolean;
+    status: "ok" | "partial" | "error";
+    reasonCodes: DiagnosisReasonCode[];
+};
+export declare function mergeNextSteps(stepLists: string[][]): string[];