@m14i/sith 1.23.0 → 1.23.1

package/README.md

@@ -10,6 +10,22 @@ Standardize and share your OpenCode setup with a fully dockerized environment, d
 
 ---
 
+## Quick Start
+
+```bash
+npm install -g @m14i/sith   # Install CLI
+sith --pull                  # Pull prebuilt Docker image
+sith                         # Launch TUI
+```
+
+No Docker? Use native Nix:
+
+```bash
+sith --nix-install && sith --nix
+```
+
+---
+
 ## Why?
 
 AI coding tools are powerful in isolation. They become fragile at scale:
@@ -29,6 +45,33 @@ Sith solves this by packaging both tools, all config, and your team's context in
 
 ---
 
+## How?
+
+Three modes. Pick based on your trust model, infra constraints, and whether Docker is available. The Docker path is recommended for teams and CI — native Nix is for when you want no container overhead on a machine you control.
+
+| | `sith --pull` | `sith --build` | `sith --nix` |
+|---|---|---|---|
+| **Setup time** | ~1 min (pull) | ~5–10 min (build) | ~2 min (first run) |
+| **Reproducibility** | Pinned image digest | Dockerfile-pinned | Nix-pinned (`nixos-23.11`) |
+| **Trust model** | GitHub Actions + Cosign | Your machine only | Your machine only |
+| **SBOM included** | ✅ | ❌ | ❌ |
+| **CI/CD ready** | ✅ drop-in | ⚠️ needs build step | ❌ |
+| **Requires Docker** | ✅ | ✅ | ❌ |
+| **Requires Nix** | ❌ | ❌ | ✅ |
+| **Disk usage** | ~2–3 GB (image) | ~2–3 GB (image) | ~500 MB (store) |
+| **Cold start** | ~1–2s (container spin-up) | ~1–2s (container spin-up) | ~200ms (native) |
+| **Runtime overhead** | Low (Linux containers) | Low (Linux containers) | None |
+| **File I/O (macOS)** | ⚠️ Slow (volume mounts) | ⚠️ Slow (volume mounts) | ✅ Native speed |
+| **File I/O (Linux)** | ✅ Native speed | ✅ Native speed | ✅ Native speed |
+| **Memory overhead** | ~50–100MB (Docker daemon) | ~50–100MB (Docker daemon) | None |
+| **Works offline** | ✅ after pull | ✅ after build | ⚠️ after store populated |
+| **macOS support** | ✅ (amd64 + arm64) | ✅ | ✅ |
+| **Linux support** | ✅ | ✅ | ✅ |
+| **Windows support** | ✅ Docker Desktop | ✅ Docker Desktop | ❌ |
+| **Ideal for** | Teams, CI, daily use | Air-gapped, custom | Local dev, no Docker |
+
+---
+
 ## Docker
 
 The recommended path. One image, works locally and in CI.
@@ -61,7 +104,7 @@ Supports `linux/amd64` and `linux/arm64`. Images are signed with cosign and incl
 cosign verify \
   --certificate-identity-regexp="https://github.com/MerzoukeMansouri/sith" \
   --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
-  ghcr.io/merzoukemanouri/sith:latest
+  ghcr.io/merzoukemansouri/sith:latest
 ```
 
 **Build from scratch — full control, no external trust:**
@@ -70,12 +113,6 @@ cosign verify \
 sith --build
 ```
 
-| | `sith --pull` | `sith --build` |
-|--|--------------|----------------|
-| Speed | Fast | Slow |
-| Trust | GitHub Actions + Cosign | Your machine |
-| Use case | Daily use, CI/CD | Air-gapped, custom builds |
-
 ### Use it
 
 **Interactive TUI** — type a prompt or use slash commands:
@@ -102,13 +139,7 @@ sith opencode -p "fix the bug"    # OpenCode starts immediately with your task
 sith claude -p "fix the bug"      # Claude Code starts immediately with your task
 ```
 
-**Skills:**
-
-```bash
-sith skills    # Install / manage skills from catalog (~/.sith/skills/)
-```
-
-### Cleanup & Uninstall
+### Cleanup
 
 ```bash
 sith --docker-cleanup    # Remove sith Docker images (sith:latest + prebuilt GHCR image)
@@ -126,7 +157,7 @@ sith --uninstall         # Remove ~/.sith/ (skills, config, nix files)
     docker run --rm \
       -e CLAUDE_CODE_OAUTH_TOKEN=$CLAUDE_CODE_OAUTH_TOKEN \
       -e GITHUB_TOKEN=$GITHUB_TOKEN \
-      ghcr.io/merzoukemanouri/sith:latest "claude auth status"
+      ghcr.io/merzoukemansouri/sith:latest "claude auth status"
 ```
 
 See [Authentication](./doc/AUTH_CLAUDE.md) for how to generate the tokens.
@@ -149,9 +180,10 @@ sith nix --install    # Install Nix
 sith nix --shell      # Run Nix shell
 ```
 
-**Cleanup:**
+**Maintenance:**
 
 ```bash
+sith --nix-update       # Update Nix channels and upgrade installed packages
 sith --nix-cleanup      # Remove ~/.sith/nix/ + run nix-collect-garbage -d
 sith --nix-uninstall    # Fully remove Nix from system (daemon, /nix/store) — needs sudo
 ```
@@ -160,6 +192,24 @@ See [doc/NIX_INSTALLATION.md](./doc/NIX_INSTALLATION.md) for full setup guide.
 
 ---
 
+## Skills
+
+Skills are AI instruction sets installed to `~/.sith/skills/` and automatically mounted into the container at runtime. They shape how Claude Code and OpenCode behave — tone, workflow, shortcuts.
+
+```bash
+sith skills    # Browse and install / uninstall skills from catalog
+```
+
+Installed skills are synced to `~/.sith/CLAUDE.md` (Claude Code) and `~/.sith/opencode.json` (OpenCode) automatically.
+
+| Skill | What it does | Auto-loaded |
+|-------|-------------|-------------|
+| `caveman` | Ultra-compressed responses (~75% token reduction) | ✅ |
+
+Skills are loaded from `~/.sith/skills/<name>/` and can be toggled individually. Community skills can be installed from any Git URL.
+
+---
+
 ## Authentication
 
 Two AI providers, two token setups:
@@ -169,6 +219,31 @@ Two AI providers, two token setups:
 
 ---
 
+## Command Reference
+
+| Command / Flag | Description |
+|---|---|
+| `sith` | Launch interactive TUI |
+| `sith shell` | Raw Nix shell inside Docker |
+| `sith opencode -p "<prompt>"` | Launch OpenCode with prompt |
+| `sith claude -p "<prompt>"` | Launch Claude Code with prompt |
+| `sith skills` | Manage skills from catalog |
+| `sith nix --install` | Install Nix package manager |
+| `sith nix --shell` | Run Nix shell |
+| `sith --pull` | Pull prebuilt Docker image from GHCR |
+| `sith --build` | Build Docker image from scratch |
+| `sith --it` | Interactive shell in Docker container |
+| `sith --nix` | Launch native Nix shell (no Docker) |
+| `sith --nix-install` | Install Nix package manager |
+| `sith --nix-update` | Update Nix channels + upgrade packages |
+| `sith --nix-cleanup` | Remove `~/.sith/nix/` + garbage collect store |
+| `sith --nix-uninstall` | Fully remove Nix from system (needs sudo) |
+| `sith --docker-cleanup` | Remove sith Docker images from local machine |
+| `sith --uninstall` | Remove `~/.sith/` config directory |
+| `sith --update` | Check for CLI updates |
+
+---
+
 ## Development
 
 ```bash

package/dist/commands/maintenance.d.ts

@@ -1,5 +1,6 @@
 export declare function dockerCleanupCommand(): Promise<void>;
 export declare function nixCleanupCommand(): Promise<void>;
+export declare function nixUpdateCommand(): Promise<void>;
 export declare function nixUninstallCommand(): Promise<void>;
 export declare function uninstallCommand(): Promise<void>;
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/commands/maintenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/maintenance.ts"],"names":[],"mappings":"AAkBA,wBAAsB,oBAAoB,kBAwBzC;AAED,wBAAsB,iBAAiB,kBAqBtC;AAED,wBAAsB,mBAAmB,kBAmExC;AAED,wBAAsB,gBAAgB,kBAwBrC"}
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/maintenance.ts"],"names":[],"mappings":"AAkBA,wBAAsB,oBAAoB,kBAwBzC;AAED,wBAAsB,iBAAiB,kBAqBtC;AAED,wBAAsB,gBAAgB,kBAmBrC;AAED,wBAAsB,mBAAmB,kBAmExC;AAED,wBAAsB,gBAAgB,kBAwBrC"}

package/dist/commands/nix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nix.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/nix.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAsBrD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO1D;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA0ChD;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAuClD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAoDjD;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAc1E"}
+{"version":3,"file":"nix.d.ts","sourceRoot":"","sources":["file:///home/runner/work/sith/sith/src/commands/nix.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAsBrD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO1D;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA0ChD;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAuClD;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA8DjD;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAc1E"}

package/dist/index.js

@@ -43075,6 +43075,7 @@ __nccwpck_require__.d(__webpack_exports__, {
   Yb: () => (/* binding */ dockerCleanupCommand),
   V: () => (/* binding */ nixCleanupCommand),
   be: () => (/* binding */ nixUninstallCommand),
+  m9: () => (/* binding */ nixUpdateCommand),
   Wd: () => (/* binding */ uninstallCommand)
 });
 
@@ -43152,6 +43153,25 @@ async function nixCleanupCommand() {
         console.log(source/* default */.Ay.yellow("nix-collect-garbage failed — Nix may not be installed."));
     }
 }
+async function nixUpdateCommand() {
+    console.log(source/* default */.Ay.cyan("Updating Nix channels..."));
+    try {
+        (0,external_node_child_process_.execSync)("nix-channel --update", { stdio: "inherit" });
+        console.log(source/* default */.Ay.green("✓ Channels updated."));
+    }
+    catch {
+        console.log(source/* default */.Ay.yellow("nix-channel failed — Nix may not be installed."));
+        return;
+    }
+    console.log(source/* default */.Ay.cyan("Upgrading Nix packages..."));
+    try {
+        (0,external_node_child_process_.execSync)("nix-env -u '*'", { stdio: "inherit" });
+        console.log(source/* default */.Ay.green("✓ Packages upgraded."));
+    }
+    catch {
+        console.log(source/* default */.Ay.yellow("nix-env upgrade failed — no user packages or error above."));
+    }
+}
 async function nixUninstallCommand() {
     console.log(source/* default */.Ay.yellow("This will fully remove Nix from your system:"));
     console.log(source/* default */.Ay.dim("  /nix/store, Nix daemon, shell profile entries"));
@@ -43351,13 +43371,11 @@ async function runNixShell() {
         console.error("Run: sith --nix-install");
         process.exit(1);
     }
-    // Copy files if not already present
+    // Always copy to pick up source changes
     const homeDir = node_os__WEBPACK_IMPORTED_MODULE_1___default().homedir();
     const localConfigDir = node_path__WEBPACK_IMPORTED_MODULE_2___default().join(homeDir, _config_js__WEBPACK_IMPORTED_MODULE_4__/* .NIX_CONFIG */ .Z3.localConfigDir);
     const shellNixPath = node_path__WEBPACK_IMPORTED_MODULE_2___default().join(localConfigDir, "shell.nix");
-    if (!node_fs__WEBPACK_IMPORTED_MODULE_0___default().existsSync(shellNixPath)) {
-        await copyNixFiles();
-    }
+    await copyNixFiles();
     console.log("🚀 Starting Nix shell...");
     console.log(`Configuration: ${shellNixPath}`);
     console.log('Press Ctrl+D or type "exit" to leave');
@@ -43379,7 +43397,15 @@ async function runNixShell() {
     }
     // Run nix-shell
     try {
-        await (0,execa__WEBPACK_IMPORTED_MODULE_5__/* .execa */ .Ho)("nix-shell", [shellNixPath], {
+        await (0,execa__WEBPACK_IMPORTED_MODULE_5__/* .execa */ .Ho)("nix-shell", [
+            "--option",
+            "substituters",
+            "https://cache.nixos.org",
+            "--option",
+            "trusted-public-keys",
+            "cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=",
+            shellNixPath,
+        ], {
             stdio: "inherit",
             env,
             cwd: process.cwd(),
@@ -44110,6 +44136,7 @@ function createProgram() {
         .option("--update", "Check for updates")
         .option("--docker-cleanup", "Remove sith Docker images from local machine")
         .option("--nix-cleanup", "Remove ~/.sith/nix and run nix-collect-garbage")
+        .option("--nix-update", "Update Nix channels and upgrade installed packages")
         .option("--nix-uninstall", "Fully remove Nix from the system (daemon, /nix/store)")
         .option("--uninstall", "Remove ~/.sith config directory");
     // Default action - show terminal UI
@@ -44120,6 +44147,9 @@ function createProgram() {
         else if (options.nixCleanup) {
             await (0,_commands_maintenance_js__WEBPACK_IMPORTED_MODULE_5__/* .nixCleanupCommand */ .V)();
         }
+        else if (options.nixUpdate) {
+            await (0,_commands_maintenance_js__WEBPACK_IMPORTED_MODULE_5__/* .nixUpdateCommand */ .m9)();
+        }
         else if (options.nixUninstall) {
             await (0,_commands_maintenance_js__WEBPACK_IMPORTED_MODULE_5__/* .nixUninstallCommand */ .be)();
         }

package/docker/nix/shell.nix

@@ -15,14 +15,15 @@
 let
   # Load packages from external configuration
   packages = import ./nix-config/packages.nix { inherit pkgs; lib = pkgs.lib; };
+  isLinux = pkgs.stdenv.isLinux;
 in
 
 pkgs.mkShell {
   name = "sith-environment";
-  
+
   # Packages loaded from nix-config/packages.json
   buildInputs = packages;
-  
+
   # Variables d'environnement
   shellHook = ''
     # Source external setup script (not bash, so exports persist)
@@ -34,9 +35,9 @@ pkgs.mkShell {
     # setup.sh sets -e for safety; unset for interactive session
     set +e
   '';
-  
+
   # Variables d'environnement persistantes
-  LOCALE_ARCHIVE = "${pkgs.glibcLocales}/lib/locale/locale-archive";
+  LOCALE_ARCHIVE = pkgs.lib.optionalString isLinux "${pkgs.glibcLocales}/lib/locale/locale-archive";
   LANG = "en_US.UTF-8";
   LC_ALL = "en_US.UTF-8";
   LC_CTYPE = "en_US.UTF-8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m14i/sith",
-  "version": "1.23.0",
+  "version": "1.23.1",
   "description": "Turn your context to the dark side. Standardize and share your OpenCode setup with a fully dockerized environment, designed for seamless collaboration and CI integration.",
   "type": "module",
   "repository": {