nikcli 0.0.6

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsgo --noEmit

package/AGENTS.md

@@ -0,0 +1,27 @@
+# nikcli agent guidelines
+
+## Build/Test Commands
+
+- **Install**: `bun install`
+- **Run**: `bun run --conditions=browser ./src/index.ts`
+- **Typecheck**: `bun run typecheck` (npm run typecheck)
+- **Test**: `bun test` (runs all tests)
+- **Single test**: `bun test test/tool/tool.test.ts` (specific test file)
+
+## Code Style
+
+- **Runtime**: Bun with TypeScript ESM modules
+- **Imports**: Use relative imports for local modules, named imports preferred
+- **Types**: Zod schemas for validation, TypeScript interfaces for structure
+- **Naming**: camelCase for variables/functions, PascalCase for classes/namespaces
+- **Error handling**: Use Result patterns, avoid throwing exceptions in tools
+- **File structure**: Namespace-based organization (e.g., `Tool.define()`, `Session.create()`)
+
+## Architecture
+
+- **Tools**: Implement `Tool.Info` interface with `execute()` method
+- **Context**: Pass `sessionID` in tool context, use `App.provide()` for DI
+- **Validation**: All inputs validated with Zod schemas
+- **Logging**: Use `Log.create({ service: "name" })` pattern
+- **Storage**: Use `Storage` namespace for persistence
+- **API Client**: The TypeScript TUI (built with SolidJS + OpenTUI) communicates with the Nikcli server using `@nikcli-ai/sdk`. When adding/modifying server endpoints in `src/server/server.ts`, regenerate the SDK in `packages/sdk/js` to keep types in sync.

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM alpine AS base
+
+# Disable the runtime transpiler cache by default inside Docker containers.
+# On ephemeral containers, the cache is not useful
+ARG BUN_RUNTIME_TRANSPILER_CACHE_PATH=0
+ENV BUN_RUNTIME_TRANSPILER_CACHE_PATH=${BUN_RUNTIME_TRANSPILER_CACHE_PATH}
+RUN apk add libgcc libstdc++ ripgrep
+
+FROM base AS build-amd64
+COPY dist/nikcli-linux-x64-baseline-musl/bin/nikcli /usr/local/bin/nikcli
+
+FROM base AS build-arm64
+COPY dist/nikcli-linux-arm64-musl/bin/nikcli /usr/local/bin/nikcli
+
+ARG TARGETARCH
+FROM build-${TARGETARCH}
+RUN nikcli --version
+ENTRYPOINT ["nikcli"]

package/README.md

@@ -0,0 +1,15 @@
+# js
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.12. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/bin/nikcli

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+const envPath = process.env.NIKCLI_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const base = "nikcli-" + platform + "-" + arch
+const binary = platform === "windows" ? "nikcli.exe" : "nikcli"
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      const entries = fs.readdirSync(modules)
+      for (const entry of entries) {
+        if (!entry.startsWith(base)) {
+          continue
+        }
+        const candidate = path.join(modules, entry, "bin", binary)
+        if (fs.existsSync(candidate)) {
+          return candidate
+        }
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    'It seems that your package manager failed to install the right version of the nikcli CLI for your platform. You can try manually installing the "' +
+      base +
+      '" package',
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://nikcli.store/config.json",
+  "remote": {
+    "enableTunnel": true,
+    "provider": "cloudflared"
+  },
+  "connectors": {
+    "figma": {
+      "type": "figma",
+      "enabled": true
+    }
+  }
+}

package/docs/tailscale-mobile/01-tailscale-setup.md

@@ -0,0 +1,94 @@
+# 01 - Setup Tailscale (host + telefono)
+
+Questa sezione configura Tailscale in modo che:
+
+- l'host abbia un nome DNS nel tailnet (`...ts.net`)
+- il telefono possa raggiungere l'host in modo privato
+- Tailscale Serve possa generare cert HTTPS per il tuo nodo
+
+## 1) Crea (o scegli) il tuo tailnet
+
+1. Vai nella console admin di Tailscale (web).
+2. Assicurati di sapere quale account/tailnet userai per i device.
+
+Consiglio: se usi un tailnet condiviso (team/famiglia), pianifica subito ACL (vedi sezione 6).
+
+## 2) Installa Tailscale sull'host
+
+### macOS (consigliato)
+
+1. Installa l'app Tailscale (GUI).
+2. Apri l'app e fai login.
+3. Verifica da terminale:
+
+```bash
+tailscale version
+tailscale status
+```
+
+### Linux (generico)
+
+1. Installa e avvia Tailscale (metodo ufficiale):
+
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+sudo tailscale up
+```
+
+2. Verifica:
+
+```bash
+tailscale version
+tailscale status
+```
+
+## 3) Installa Tailscale sul telefono
+
+1. Installa l'app Tailscale (iOS/Android).
+2. Login con lo stesso tailnet.
+3. Attiva la VPN (toggle ON).
+4. Verifica che l'host appaia nella lista dei device.
+
+## 4) Abilita MagicDNS (consigliato)
+
+1. Console admin Tailscale -> DNS.
+2. Abilita MagicDNS.
+
+Questo ti permette di raggiungere l'host con un nome tipo:
+`nome-host.tuo-tailnet.ts.net`
+
+## 5) Abilita HTTPS certificates (Serve)
+
+1. Console admin Tailscale -> DNS.
+2. Abilita "HTTPS Certificates" (o voce equivalente).
+
+Serve usa questi cert per esporre `https://...ts.net`.
+
+## 6) (Raccomandato) Configura Access Controls / ACL
+
+Se il tailnet e' solo tuo e i device sono solo i tuoi, puoi anche evitare, ma e' meglio restringere.
+
+Obiettivo minimo:
+
+- solo il tuo utente/device puo' raggiungere questo host
+
+Da console admin Tailscale -> Access controls:
+
+- limita chi puo' connettersi al nodo che userai per Nikcli
+
+Nota: le ACL dipendono molto da come organizzi users/tags. Se vuoi, dimmi se il tuo tailnet e' personale o team e ti scrivo una policy ACL precisa.
+
+## 7) Trova il DNSName del tuo host (ti servira' dopo)
+
+Metodo 1 (piu' semplice)
+
+- apri `tailscale status`
+- cerca la riga del tuo host e copia il nome `...ts.net`
+
+Metodo 2 (automatica, senza jq, usando bun)
+
+```bash
+tailscale status --json | bun -e 'import { readFileSync } from "fs"; const j = JSON.parse(readFileSync(0, "utf8")); process.stdout.write(j.Self.DNSName.replace(/\.$/, ""))'
+```
+
+Salva questo valore: lo userai per aprire la UI dal telefono e per configurare l'API.

package/docs/tailscale-mobile/02-host-setup.md

@@ -0,0 +1,115 @@
+# 02 - Setup host (Nikcli server + Web UI)
+
+In questa sezione avvii i due processi sull'host:
+
+- Nikcli API server (loopback)
+- Web UI (loopback)
+
+Nota importante
+
+- Con auth Tailscale attiva e senza password, le chiamate locali dirette a `127.0.0.1:4096` (senza header Tailscale) rispondono 401. E' normale.
+
+## 1) Prerequisiti sull'host
+
+Verifica binari:
+
+```bash
+tailscale version
+nikcli --version || true
+bun --version || true
+```
+
+Se `nikcli` non e' nel PATH, usa la modalita' repo (vedi sotto) oppure installalo come fai di solito nel tuo ambiente.
+
+## 2) Scegli la directory workspace
+
+Decidi dove vuoi che Nikcli lavori (repo/progetto).
+
+Consiglio:
+
+- avvia `nikcli serve` con working directory uguale al workspace
+- cosi' il client mobile non deve impostare `Directory` nelle Settings
+
+Esempio:
+
+```bash
+cd /percorso/al/tuo/workspace
+pwd
+```
+
+## 3) Abilita auth passwordless via Tailscale
+
+Imposta queste env:
+
+```bash
+export NIKCLI_SERVER_TAILSCALE_AUTH=1
+
+# Raccomandato: allowlist. Di solito e' la mail con cui fai login a Tailscale.
+export NIKCLI_SERVER_TAILSCALE_USERS="tuo-utente@dominio.com"
+```
+
+Opzionale (fallback Basic Auth per accessi locali non via Serve):
+
+```bash
+export NIKCLI_SERVER_PASSWORD="una_password_forte"
+export NIKCLI_SERVER_USERNAME="nikcli"
+```
+
+## 4) Avvia Nikcli API server (loopback)
+
+Raccomandato (porta stabile):
+
+```bash
+nikcli --print-logs serve --hostname 127.0.0.1 --port 4096
+```
+
+Se stai lavorando dal monorepo e vuoi avviare la versione dev:
+
+```bash
+cd /percorso/al/monorepo/packages/nikcli
+bun run dev -- serve --hostname 127.0.0.1 --port 4096
+```
+
+## 5) Avvia la Web UI (packages/app)
+
+Se hai il monorepo:
+
+1. Installa deps (una volta sola):
+
+```bash
+cd /percorso/al/monorepo
+bun install
+```
+
+2. Build + preview:
+
+```bash
+cd packages/app
+bun run build
+bun run preview -- --host 127.0.0.1 --port 3002
+```
+
+Nota: `preview` va bene per uso personale. Se vuoi, puoi anche servire `packages/app/dist` con un web server a tua scelta.
+
+## 6) Verifica locale (host)
+
+UI (deve rispondere HTML):
+
+```bash
+curl -I http://127.0.0.1:3002
+```
+
+API (con Tailscale auth attiva e senza password, e' normale vedere 401):
+
+```bash
+curl -i http://127.0.0.1:4096/global/health
+```
+
+## 7) (Opzionale) Avvio automatico
+
+Se vuoi che tutto riparta dopo reboot, usa:
+
+- macOS: launchd
+- Linux: systemd
+
+Qui non creo file di sistema automaticamente (dipende dal tuo OS e percorsi), ma se mi dici macOS o Linux ti scrivo gli unit/plist completi con i comandi esatti che stai usando.

package/docs/tailscale-mobile/03-phone-and-serve.md

@@ -0,0 +1,134 @@
+# 03 - Tailscale Serve (Option B) + configurazione telefono
+
+Questa e' la parte che rende raggiungibili UI e API dal telefono tramite `https://...ts.net`.
+
+## 1) Configura Tailscale Serve sull'host
+
+Esegui sull'host:
+
+```bash
+# UI: espone in HTTPS 443 e proxya verso 127.0.0.1:3002
+tailscale serve --bg --https=443 3002
+
+# API: espone in HTTPS 8443 e proxya verso 127.0.0.1:4096
+tailscale serve --bg --https=8443 4096
+
+tailscale serve status
+```
+
+Se in futuro vuoi spegnere tutto:
+
+```bash
+tailscale serve off
+```
+
+## 2) Trova gli URL corretti
+
+Il comando `tailscale serve status` ti stampa gli URL pubblicati nel tailnet.
+
+In particolare ti servono:
+
+- URL UI: `https://<dnsname>.ts.net`
+- URL API: `https://<dnsname>.ts.net:8443`
+
+Se vuoi stampare solo il DNSName con bun:
+
+```bash
+tailscale status --json | bun -e 'import { readFileSync } from "fs"; const j = JSON.parse(readFileSync(0, "utf8")); process.stdout.write(j.Self.DNSName.replace(/\.$/, ""))'
+```
+
+## 3) Apri la UI dal telefono
+
+1. Sul telefono: apri Tailscale e metti ON.
+2. Apri Safari/Chrome.
+3. Vai all'URL UI (quello su 443).
+
+Se la pagina non carica:
+
+- verifica che l'host sia online
+- verifica `tailscale status` su host e telefono
+
+## 4) Configura la UI per puntare all'API (porta 8443)
+
+Nella web UI:
+
+1. Vai su Settings.
+2. In "Server URL" inserisci l'URL API su porta 8443.
+3. (Opzionale) "Directory": lascia vuoto per usare la directory di avvio del server, oppure imposta un path specifico.
+4. Premi Save.
+
+Se auth Tailscale e' corretta:
+
+- Status diventa Connected
+- La sezione Authentication mostra che non serve login
+
+## 5) Test end-to-end
+
+1. Crea una sessione.
+2. Invia un prompt.
+3. Verifica che i messaggi arrivino in realtime.
+4. Se Nikcli chiede permission/question/dbedit, rispondi dalla modale: la sessione deve riprendere.
+
+## 6) Troubleshooting
+
+### A) UI ok, ma API "Disconnected"
+
+Checklist:
+
+- `tailscale serve status` mostra anche la porta 8443?
+- il processo `nikcli serve` e' vivo sull'host?
+- hai inserito Server URL corretto (porta 8443)?
+
+Test da un altro device nel tailnet:
+
+```bash
+curl -i https://DNSNAME:8443/global/health
+```
+
+### B) 403 Forbidden
+
+Significa che l'header Tailscale e' presente ma l'utente non e' ammesso.
+
+Azioni:
+
+- controlla `NIKCLI_SERVER_TAILSCALE_USERS`
+- ricordati che in genere e' la mail con cui fai login a Tailscale
+
+### C) 401 Unauthorized
+
+Cause tipiche:
+
+- stai chiamando direttamente `http://127.0.0.1:4096` (non passa da Serve)
+- `tailscale serve` non e' configurato per 8443/4096
+- hai attivato Tailscale auth ma non hai header (Serve non in mezzo)
+
+Soluzioni:
+
+- usa sempre l'URL `https://...:8443` dal telefono
+- oppure imposta `NIKCLI_SERVER_PASSWORD` se vuoi anche accesso locale senza header
+
+### D) Errori CORS nel browser
+
+Con Option B l'origin e' `https://DNSNAME.ts.net` e l'API e' su `https://DNSNAME.ts.net:8443`.
+
+In Nikcli ho abilitato automaticamente CORS per `https://*.ts.net` quando:
+
+- `NIKCLI_SERVER_TAILSCALE_AUTH=1`
+- il server e' in listen su loopback (`127.0.0.1` / `localhost`)
+
+Se stai usando un origin diverso (custom domain, reverse proxy esterno, ecc.), allora avvia il server con `--cors <origin>`.
+
+### E) SSE (realtime) non aggiorna
+
+Controlla che l'endpoint eventi sia raggiungibile:
+
+```bash
+curl -N https://DNSNAME:8443/event
+```
+
+Devi vedere una riga iniziale con `server.connected` e poi heartbeat.
+
+## 7) Aggiungi alla Home Screen (esperienza "app")
+
+iOS (Safari): Share -> Add to Home Screen.
+Android (Chrome): menu -> Add to Home screen.

package/docs/tailscale-mobile/README.md

@@ -0,0 +1,59 @@
+# Nikcli sul telefono via Tailscale (Option B)
+
+Questa guida ti porta da zero ad avere Nikcli utilizzabile dal browser del tuo telefono, collegandoti in modo privato tramite Tailscale (nessuna porta esposta su Internet).
+
+Obiettivo finale
+
+- Apri un URL `https://...ts.net` dal telefono (Safari/Chrome).
+- Vedi la web UI di Nikcli.
+- Il telefono parla con il Nikcli server remoto (API) tramite Tailscale.
+- Autenticazione passwordless: l'accesso e' concesso solo se la richiesta arriva da Tailscale Serve e (opzionale) se l'utente Tailscale e' in allowlist.
+
+Architettura (Option B)
+
+```
+Telefono (Tailscale ON)
+  |
+  | HTTPS 443  -> Web UI (Vite preview o static)
+  | HTTPS 8443 -> Nikcli API (Hono/Bun)
+  v
+Tailscale Serve sul nodo host
+  |
+  | proxy verso 127.0.0.1
+  v
+Host (workspace e processi)
+  - Web UI locale:  http://127.0.0.1:3002
+  - Nikcli API:     http://127.0.0.1:4096
+```
+
+Perche' Option B
+
+- Funziona bene su mobile.
+- Mantiene API e UI separate (utile per debug e upgrade).
+- Non richiede reverse proxy esterni.
+
+Porte usate
+
+- UI locale (host): `3002` (solo loopback)
+- API locale (host): `4096` (solo loopback)
+- UI esposta nel tailnet: `443` (HTTPS)
+- API esposta nel tailnet: `8443` (HTTPS)
+
+Prerequisiti
+
+- Un "host" sempre acceso (Mac/Linux/VM) dove risiede il tuo workspace.
+- Tailscale installato su host e telefono.
+- Nikcli disponibile sull'host (binario installato o repo).
+- Bun sull'host se vuoi buildare la web UI dal repo.
+
+Indice (leggi in ordine)
+
+- `docs/tailscale-mobile/01-tailscale-setup.md`
+- `docs/tailscale-mobile/02-host-setup.md`
+- `docs/tailscale-mobile/03-phone-and-serve.md`
+
+Security note (importante)
+
+- Nikcli puo' leggere/scrivere file ed eseguire comandi sul tuo host.
+- Non usare Funnel.
+- Se il tailnet non e' solo tuo, configura ACL Tailscale e/o `NIKCLI_SERVER_TAILSCALE_USERS`.

package/examples/README.md

@@ -0,0 +1,54 @@
+# Nikcli Visual Examples
+
+This directory contains visual demonstrations of nikcli's capabilities.
+
+## Examples
+
+### 1. CLI Interface Demo (`cli-demo/`)
+
+Interactive terminal UI showcasing nikcli's command-line interface with:
+
+- Session management display
+- Real-time AI response streaming
+- File tree visualization
+- Command palette
+
+### 2. Web App Components (`web-components/`)
+
+React components from the nikcli web app:
+
+- Session viewer with syntax highlighting
+- Settings panel with theme switcher
+- Connection status indicators
+- Terminal emulator
+
+### 3. Mobile App UI (`mobile-ui/`)
+
+Expo/React Native screens:
+
+- Session list with swipe actions
+- Chat interface with code blocks
+- Settings and connection management
+- Offline mode indicators
+
+### 4. AI Tools Visualization (`ai-tools/`)
+
+Visual representations of nikcli's AI tool system:
+
+- Tool execution flow diagrams
+- Context collection visualization
+- RAG search result display
+- Multi-agent orchestration
+
+## Running Examples
+
+```bash
+# CLI Demo
+bun run packages/nikcli/examples/cli-demo/demo.ts
+
+# Web Components
+cd packages/app && bun dev
+
+# Mobile UI
+cd packages/mobile && bun start
+```