Prepare CLI package for npm

Author: itsflaid

.github/workflows/ci.yml

@@ -62,3 +62,36 @@ jobs:
 
       - name: Build web
         run: pnpm build:web
+
+  package:
+    name: Package smoke test
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.34.2
+          run_install: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Pack CLI
+        run: pnpm --filter devmap pack --pack-destination artifacts
+
+      - name: Smoke test packed CLI
+        run: |
+          npm exec --yes --package ./artifacts/devmap-0.1.0.tgz -- devmap --version
+          npm exec --yes --package ./artifacts/devmap-0.1.0.tgz -- devmap --help

docs/for-me-personal/DEBUG.md

@@ -362,14 +362,14 @@ menulis artifact project yang sama.
 
 **Tanggal ditemukan:** 2026-06-10
 
-**Status:** Belum diperbaiki.
+**Status:** Selesai.
 
 ### Gejala
 
 Dry-run package:
 
 ```powershell
-pnpm --filter @devmap/cli pack --dry-run
+pnpm --filter devmap pack --dry-run
 ```
 
 menunjukkan tarball ikut membawa:
@@ -385,7 +385,7 @@ menunjukkan tarball ikut membawa:
 
 Package CLI belum memiliki allowlist `files` atau `.npmignore` yang ketat.
 
-### Rencana Solusi
+### Solusi
 
 Gunakan allowlist pada `packages/cli/package.json`, misalnya:
 
@@ -404,15 +404,17 @@ Tambahkan script `prepack` untuk memastikan build selalu dibuat sebelum tarball.
 Pastikan fixture `.env`, test, source development, dan snapshot lokal tidak
 masuk package.
 
-### Verifikasi yang Diperlukan
+### Verifikasi
 
 ```powershell
-pnpm --filter @devmap/cli pack --dry-run
-npm install -g .\devmap-cli-*.tgz
-devmap --version
-devmap --help
+pnpm --filter devmap pack --pack-destination artifacts
+npm exec --yes --package .\artifacts\devmap-0.1.0.tgz -- devmap --version
+npm exec --yes --package .\artifacts\devmap-0.1.0.tgz -- devmap --help
 ```
 
+Tarball hanya berisi `dist`, `package.json`, `README.md`, dan `LICENSE`.
+Command versi dan help berhasil langsung dari tarball.
+
 ### Pelajaran
 
 `.gitignore` tidak cukup untuk mengontrol isi package npm. Selalu periksa hasil
@@ -513,6 +515,49 @@ sebelum release dan jangan menjadikan preview model sebagai default.
 
 ---
 
+## 10. Smoke Test npx Paralel Membaca Instalasi yang Belum Selesai
+
+**Tanggal:** 2026-06-11
+
+**Status:** Selesai.
+
+### Gejala
+
+`devmap --version` berhasil, tetapi `devmap --help` sempat gagal dengan:
+
+```text
+ENOENT: no such file or directory, open '...\node_modules\devmap\dist\commands\init.js'
+```
+
+### Akar Masalah
+
+Dua command `npx` dijalankan paralel dan memakai cache `_npx` yang sama.
+Salah satu proses mulai menjalankan binary ketika proses lain masih menyiapkan
+isi package. Tarball dan instalasi akhirnya sama-sama memiliki `init.js`.
+
+### Solusi
+
+- Jalankan smoke test package secara berurutan.
+- Gunakan cache npm terpisah untuk setiap instalasi ketika perlu isolasi penuh.
+- Jangan menyimpulkan file tarball hilang sebelum memeriksa isi arsip dengan
+  `tar -tf`.
+
+### Verifikasi
+
+```powershell
+npm exec --yes --cache "$env:TEMP\devmap-version" --package $tarball -- devmap --version
+npm exec --yes --cache "$env:TEMP\devmap-help" --package $tarball -- devmap --help
+```
+
+Keduanya berhasil.
+
+### Pelajaran
+
+Package installation bukan operasi yang aman diparalelkan ketika proses berbagi
+cache yang sama. Smoke test distribusi harus deterministik dan berurutan.
+
+---
+
 ## Checklist Saat Menambahkan Debug Baru
 
 Tambahkan catatan baru ketika:

docs/for-me-personal/PROGRESS.md

@@ -73,7 +73,20 @@ Terakhir diperbarui: 2026-06-11
 - Availability selected model ikut diperiksa.
 - Snapshot dibedakan menjadi valid, missing, corrupt, dan unsupported schema.
 - API key dan raw stack trace tidak pernah ditampilkan.
-- Automated test saat ini berjumlah 32 dan seluruhnya lulus.
+- Automated test saat ini berjumlah 33 dan seluruhnya lulus.
+
+### Distribusi npm
+
+- Package CLI publik sekarang bernama `devmap`, sedangkan root private workspace
+  bernama `devmap-workspace`.
+- Allowlist package hanya memasukkan `dist`; npm tetap menyertakan
+  `package.json`, `README.md`, dan `LICENSE`.
+- Script `prepack` selalu membangun CLI sebelum tarball dibuat.
+- Source, test, `.devmap`, fixture `.env`, dan fixture `node_modules` tidak lagi
+  masuk tarball.
+- Tarball `devmap-0.1.0.tgz` berhasil dijalankan melalui `npm exec` untuk
+  `devmap --version` dan `devmap --help`.
+- GitHub Actions memiliki package smoke test setelah seluruh matrix CI lulus.
 
 ### Cross-Platform CI
 
@@ -99,9 +112,9 @@ Terakhir diperbarui: 2026-06-11
 ### Prioritas Berikutnya
 
 1. Pastikan rerun GitHub Actions hijau pada seluruh 9 kombinasi.
-2. Rapikan package npm dan verifikasi tarball sebelum publish.
-3. Tambahkan streaming output untuk jawaban AI.
-4. Lakukan manual verification Groq pada project nyata.
+2. Lakukan manual verification Groq pada project nyata.
+3. Benchmark Context Builder dengan minimal 20 pertanyaan.
+4. Tambahkan streaming output untuk jawaban AI jika waktu MVP masih tersedia.
 
 ## Status Saat Ini
 
@@ -143,15 +156,15 @@ Saat ini CLI sudah bisa:
 
 ### Setup Package CLI
 
-- Package CLI diganti namanya menjadi `@devmap/cli`.
+- Package CLI publik memakai nama `devmap` agar `npx devmap` bekerja.
 - Entry binary `devmap` ditambahkan dan diarahkan ke `./dist/index.js`.
 - Welcome screen aqua ditambahkan untuk command `devmap` tanpa argumen. Desainnya
   memakai ASCII wordmark DevMap sebagai brand signal, memakai warna truecolor
   `#2EE6D6`, lalu isi di bawahnya tetap ringkas dan command-focused.
 - Script package CLI ditambahkan:
-  - `pnpm --filter @devmap/cli dev`
-  - `pnpm --filter @devmap/cli build`
-  - `pnpm --filter @devmap/cli test`
+  - `pnpm --filter devmap dev`
+  - `pnpm --filter devmap build`
+  - `pnpm --filter devmap test`
 - `commander` dipasang di versi `^12.0.0` supaya tetap kompatibel dengan
   requirement Node.js 18+ yang tertulis di dokumentasi.
 - Node types ditambahkan ke `tsconfig.json` supaya TypeScript mengenali
@@ -179,9 +192,9 @@ Saat ini CLI sudah bisa:
   menambah framework test baru.
 - Script test CLI sekarang menjalankan unit/integration test dan TypeScript
   type-check:
-  - `pnpm --filter @devmap/cli test`
-  - `pnpm --filter @devmap/cli test:unit`
-  - `pnpm --filter @devmap/cli test:types`
+  - `pnpm --filter devmap test`
+  - `pnpm --filter devmap test:unit`
+  - `pnpm --filter devmap test:types`
 - Fixture Next.js mencakup:
   - App Router
   - import lokal dengan suffix `.js`
@@ -566,8 +579,8 @@ Mencakup:
 Pengecekan berikut sudah berhasil:
 
 ```bash
-pnpm --filter @devmap/cli test
-pnpm --filter @devmap/cli build
+pnpm --filter devmap test
+pnpm --filter devmap build
 pnpm --filter @devmap/web build
 node packages\cli\dist\index.js --help
 node packages\cli\dist\index.js init

docs/for-me-personal/TEST.md

@@ -54,8 +54,8 @@ pnpm test:cli
 Command tersebut menjalankan:
 
 ```powershell
-pnpm --filter @devmap/cli test:unit
-pnpm --filter @devmap/cli test:types
+pnpm --filter devmap test:unit
+pnpm --filter devmap test:types
 ```
 
 Saat ini test mencakup:
@@ -78,8 +78,8 @@ Saat ini test mencakup:
 Hasil minimum yang diharapkan:
 
 ```text
-tests 32
-pass 32
+tests 33
+pass 33
 fail 0
 ```
 
@@ -120,8 +120,8 @@ npx -p node@20 node packages\cli\node_modules\tsx\dist\cli.mjs packages\cli\test
 Hasil minimum yang diharapkan untuk keduanya:
 
 ```text
-tests 32
-pass 32
+tests 33
+pass 33
 fail 0
 ```
 
@@ -234,9 +234,12 @@ pnpm build:web
 Total job yang harus hijau:
 
 ```text
-9
+10
 ```
 
+Sembilan job berasal dari matrix OS/Node. Satu job tambahan membuat dan menguji
+tarball npm setelah seluruh matrix lulus.
+
 ## Development CLI Tanpa Build
 
 Untuk menguji source terbaru tanpa build:
@@ -499,5 +502,32 @@ devmap doctor
 Untuk melepas link global:
 
 ```powershell
-npm unlink -g @devmap/cli
+npm unlink -g devmap
+```
+
+## Testing Tarball npm
+
+Buat package dari root repository:
+
+```powershell
+pnpm --filter devmap pack --pack-destination artifacts
+```
+
+Pastikan daftar file hanya berisi:
+
+- `dist/`
+- `package.json`
+- `README.md`
+- `LICENSE`
+
+Pastikan tidak ada `src/`, `test/`, `.devmap/`, `.env`, atau `node_modules/`.
+
+Jalankan smoke test secara berurutan dengan cache terpisah:
+
+```powershell
+$tarball = "C:\path\to\artifacts\devmap-0.1.0.tgz"
+npm exec --yes --cache "$env:TEMP\devmap-version" --package $tarball -- devmap --version
+npm exec --yes --cache "$env:TEMP\devmap-help" --package $tarball -- devmap --help
 ```
+
+Jangan menjalankan dua instalasi `npx` secara paralel dengan cache yang sama.

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "devmap",
+  "name": "devmap-workspace",
   "private": true,
   "version": "1.0.0",
   "packageManager": "pnpm@10.34.2",
@@ -11,9 +11,9 @@
     "dev:web": "pnpm --filter @devmap/web dev",
     "build:web": "pnpm --filter @devmap/web build",
     "preview:web": "pnpm --filter @devmap/web preview",
-    "dev:cli": "pnpm --filter @devmap/cli dev",
-    "build:cli": "pnpm --filter @devmap/cli build",
-    "test:cli": "pnpm --filter @devmap/cli test"
+    "dev:cli": "pnpm --filter devmap dev",
+    "build:cli": "pnpm --filter devmap build",
+    "test:cli": "pnpm --filter devmap test"
   },
   "keywords": [
     "codebase",

packages/cli/LICENSE

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

packages/cli/README.md

@@ -0,0 +1,36 @@
+# DevMap
+
+Understand any codebase in minutes, not days.
+
+## Install
+
+```bash
+npm install --global devmap
+```
+
+Or run it without a global install:
+
+```bash
+npx devmap --help
+```
+
+## Quick Start
+
+```bash
+devmap init
+devmap analyze
+devmap ask "How does authentication work?"
+devmap doctor
+```
+
+DevMap generates a reusable project snapshot at
+`.devmap/snapshot.json`. The snapshot combines static analysis with an optional
+Groq-powered architecture interpretation.
+
+## Requirements
+
+- Node.js 18 or newer
+- A Groq API key for AI-powered analysis and answers
+
+Source code, documentation, and issue tracking are available at
+https://github.com/itsflaid/devmap.