@thieung/agentkit-helper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thieu Nguyen
+
+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.

package/README.md

@@ -0,0 +1,92 @@
+# AgentKit Helper
+
+[Tiếng Việt](./README.vi.md)
+
+A friendly TUI for installing and updating AgentKit Kits. It detects your
+`ak` binary, asks a few questions, shows the official command, and runs it for
+you.
+
+![AgentKit Helper TUI](./assets/tui-preview.en.svg)
+
+## Start
+
+Requires Node.js 20.12+ and the `ak` CLI.
+
+```bash
+npx --yes @thieung/agentkit-helper
+```
+
+For the shorter `akh` command:
+
+```bash
+npm install --global @thieung/agentkit-helper
+akh
+```
+
+In the TUI, use:
+
+- ↑/↓ to navigate
+- Space to select multiple runtimes
+- Enter to confirm
+- `← Back` to return to the previous step
+
+Choose a project or user/global scope, Engineer or Marketing Kit, one or more
+runtimes, and the Stable or Beta channel. AgentKit remains responsible for Kit
+verification, ownership, snapshots, and runtime-specific files.
+
+For global install, the helper first runs without `--force`. If the target
+already exists or drift is detected, the TUI shows a WARNING and asks for
+separate consent, defaulting to No. It retries with `--force` only after you
+choose Yes. Global update is preserve-only: user-modified files are skipped
+and the helper never adds `--force`.
+
+<details>
+<summary><strong>Advanced CLI usage</strong></summary>
+
+Install into a project:
+
+```bash
+akh install --project /path/to/project --kit engineer \
+  --runtime codex --channel stable
+```
+
+Install into runtime user/global scope:
+
+```bash
+akh install --global --kit engineer \
+  --runtime codex,omp,pi --channel stable
+```
+
+Update Kit installs or only the signed `ak` binary:
+
+```bash
+akh update --project /path/to/project
+akh update-all --channel stable
+akh self-update --channel stable
+```
+
+Preview without applying changes:
+
+```bash
+akh update --project /path/to/project --dry-run
+```
+
+Targets:
+
+- Install: `claude-code`, `codex`, `cursor`, `dsh`, `grok`, `omp`, `pi`
+- Update: `claude-code`, `codex`, `cursor`, `grok`, `omp`, `pi`
+- Export: `agy`, `portable`
+
+Run `akh --help` for every command and option.
+
+</details>
+
+## Development
+
+```bash
+npm ci
+npm run check
+npm test
+```
+
+MIT License

package/README.vi.md

@@ -0,0 +1,90 @@
+# AgentKit Helper
+
+[English](./README.md)
+
+TUI thân thiện giúp cài đặt và cập nhật AgentKit Kit. Helper tự detect `ak`
+binary, hỏi một vài lựa chọn, hiển thị command chính thức rồi chạy giúp bạn.
+
+![Giao diện AgentKit Helper](./assets/tui-preview.svg)
+
+## Bắt đầu
+
+Yêu cầu Node.js 20.12+ và `ak` CLI.
+
+```bash
+npx --yes @thieung/agentkit-helper
+```
+
+Muốn dùng command ngắn `akh`:
+
+```bash
+npm install --global @thieung/agentkit-helper
+akh
+```
+
+Trong TUI, dùng:
+
+- ↑/↓ để di chuyển
+- Space để chọn nhiều runtime
+- Enter để xác nhận
+- `← Quay lại` để trở về bước trước
+
+Bạn chỉ cần chọn scope project hoặc user/global, Engineer hoặc Marketing Kit,
+một hay nhiều runtime và release channel Stable hoặc Beta. AgentKit vẫn quản
+lý việc xác minh Kit, ownership, snapshot và file riêng của từng runtime.
+
+Khi cài global scope, helper chạy trước mà không có `--force`. Nếu target đã
+tồn tại hoặc có drift, TUI hiển thị WARNING và hỏi consent riêng, mặc định No.
+Chỉ khi chọn Yes, helper mới retry bằng `--force`. Global update luôn dùng
+preserve-only: file do user chỉnh sửa được bỏ qua và helper không thêm `--force`.
+
+<details>
+<summary><strong>Cách dùng CLI nâng cao</strong></summary>
+
+Cài vào project:
+
+```bash
+akh install --project /path/to/project --kit engineer \
+  --runtime codex --channel stable
+```
+
+Cài vào user/global scope của runtime:
+
+```bash
+akh install --global --kit engineer \
+  --runtime codex,omp,pi --channel stable
+```
+
+Cập nhật Kit install hoặc chỉ cập nhật signed `ak` binary:
+
+```bash
+akh update --project /path/to/project
+akh update-all --channel stable
+akh self-update --channel stable
+```
+
+Preview mà không áp dụng thay đổi:
+
+```bash
+akh update --project /path/to/project --dry-run
+```
+
+Các target:
+
+- Cài đặt: `claude-code`, `codex`, `cursor`, `dsh`, `grok`, `omp`, `pi`
+- Cập nhật: `claude-code`, `codex`, `cursor`, `grok`, `omp`, `pi`
+- Export: `agy`, `portable`
+
+Chạy `akh --help` để xem toàn bộ command và option.
+
+</details>
+
+## Phát triển local
+
+```bash
+npm ci
+npm run check
+npm test
+```
+
+MIT License

package/assets/tui-preview.en.svg

@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="650" viewBox="0 0 1200 650" role="img" aria-labelledby="title description">
+  <title id="title">AgentKit Helper interactive terminal</title>
+  <desc id="description">AgentKit Helper showing the installed ak binary and its main action menu in English.</desc>
+  <rect width="1200" height="650" rx="18" fill="#18181b"/>
+  <rect x="1" y="1" width="1198" height="648" rx="17" fill="none" stroke="#3f3f46" stroke-width="2"/>
+  <circle cx="32" cy="30" r="7" fill="#ff5f57"/>
+  <circle cx="56" cy="30" r="7" fill="#febc2e"/>
+  <circle cx="80" cy="30" r="7" fill="#28c840"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="25">
+    <text x="30" y="88" fill="#f4f4f5">┌  AgentKit Helper</text>
+    <text x="30" y="128" fill="#71717a">│</text>
+    <text x="30" y="168" fill="#7dd3fc">◇</text>
+    <text x="72" y="168" fill="#a7f3d0" font-weight="700">Choose interface language / Chọn ngôn ngữ giao diện</text>
+    <text x="30" y="208" fill="#71717a">│</text>
+    <text x="72" y="208" fill="#e4e4e7">English</text>
+    <rect x="58" y="226" width="510" height="48" rx="8" fill="#27272a"/>
+    <text x="72" y="258" fill="#fbbf24" font-weight="700">Current ak binary: 2.14.0 (stable)</text>
+    <text x="30" y="310" fill="#71717a">│</text>
+    <text x="30" y="350" fill="#7dd3fc">◆</text>
+    <text x="72" y="350" fill="#a7f3d0" font-weight="700">What do you want to do?</text>
+    <text x="30" y="392" fill="#71717a">│</text>
+    <circle cx="82" cy="387" r="9" fill="#86efac"/>
+    <text x="108" y="396" fill="#fafafa">Install a Kit</text>
+    <text x="72" y="438" fill="#71717a">○</text>
+    <text x="108" y="438" fill="#d4d4d8">Update a Kit</text>
+    <text x="72" y="480" fill="#71717a">○</text>
+    <text x="108" y="480" fill="#d4d4d8">Update all detected AgentKit installs</text>
+    <text x="72" y="522" fill="#71717a">○</text>
+    <text x="108" y="522" fill="#d4d4d8">Run health checks</text>
+    <text x="30" y="572" fill="#71717a">│</text>
+    <text x="72" y="572" fill="#a1a1aa">↑/↓ to navigate • Enter: confirm</text>
+    <text x="30" y="618" fill="#71717a">└</text>
+  </g>
+</svg>

package/assets/tui-preview.svg

@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="650" viewBox="0 0 1200 650" role="img" aria-labelledby="title description">
+  <title id="title">AgentKit Helper interactive terminal</title>
+  <desc id="description">AgentKit Helper showing the installed ak binary and its main action menu.</desc>
+  <rect width="1200" height="650" rx="18" fill="#18181b"/>
+  <rect x="1" y="1" width="1198" height="648" rx="17" fill="none" stroke="#3f3f46" stroke-width="2"/>
+  <circle cx="32" cy="30" r="7" fill="#ff5f57"/>
+  <circle cx="56" cy="30" r="7" fill="#febc2e"/>
+  <circle cx="80" cy="30" r="7" fill="#28c840"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace" font-size="25">
+    <text x="30" y="88" fill="#f4f4f5">┌  AgentKit Helper</text>
+    <text x="30" y="128" fill="#71717a">│</text>
+    <text x="30" y="168" fill="#7dd3fc">◇</text>
+    <text x="72" y="168" fill="#a7f3d0" font-weight="700">Choose interface language / Chọn ngôn ngữ giao diện</text>
+    <text x="30" y="208" fill="#71717a">│</text>
+    <text x="72" y="208" fill="#e4e4e7">Tiếng Việt</text>
+    <rect x="58" y="226" width="525" height="48" rx="8" fill="#27272a"/>
+    <text x="72" y="258" fill="#fbbf24" font-weight="700">ak binary hiện tại: 2.14.0 (stable)</text>
+    <text x="30" y="310" fill="#71717a">│</text>
+    <text x="30" y="350" fill="#7dd3fc">◆</text>
+    <text x="72" y="350" fill="#a7f3d0" font-weight="700">Bạn muốn làm gì?</text>
+    <text x="30" y="392" fill="#71717a">│</text>
+    <circle cx="82" cy="387" r="9" fill="#86efac"/>
+    <text x="108" y="396" fill="#fafafa">Cài Kit</text>
+    <text x="72" y="438" fill="#71717a">○</text>
+    <text x="108" y="438" fill="#d4d4d8">Cập nhật Kit</text>
+    <text x="72" y="480" fill="#71717a">○</text>
+    <text x="108" y="480" fill="#d4d4d8">Cập nhật mọi AgentKit install đã detect</text>
+    <text x="72" y="522" fill="#71717a">○</text>
+    <text x="108" y="522" fill="#d4d4d8">Chạy health check</text>
+    <text x="30" y="572" fill="#71717a">│</text>
+    <text x="72" y="572" fill="#a1a1aa">↑/↓ to navigate • Enter: confirm</text>
+    <text x="30" y="618" fill="#71717a">└</text>
+  </g>
+</svg>