From 506821f6384df8632026f680e444da17a7aaeb0d Mon Sep 17 00:00:00 2001
From: jasmine <its.jassy@pm.me>
Date: Mon, 27 Oct 2025 22:44:14 +0800
Subject: [PATCH] Add interactive REPL with helpers and improve package
 management

- Add Node.js to devshell for mature, stable REPL
- Create .replrc.js with println() and dir() helpers
- Add 'just repl' command with auto-loaded helpers
- Add 'just add-dev' and 'just remove' for package management
- Update README with complete command reference and feature list
---
 .replrc.js               |  5 +++++
 Justfile                 |  8 ++++++++
 README.md                | 20 ++++++++++++++++++--
 nix/modules/devshell.nix |  1 +
 4 files changed, 32 insertions(+), 2 deletions(-)
 create mode 100644 .replrc.js

diff --git a/.replrc.js b/.replrc.js
new file mode 100644
index 0000000..f6059e6
--- /dev/null
+++ b/.replrc.js
@@ -0,0 +1,5 @@
+// REPL helper functions
+// Loaded automatically by `just repl`
+
+globalThis.println = (...args) => console.log(...args);
+globalThis.dir = (obj) => console.dir(obj, { depth: null, colors: true });
diff --git a/Justfile b/Justfile
index 0ce057f..7773502 100644
--- a/Justfile
+++ b/Justfile
@@ -6,6 +6,10 @@ default:
 dev:
     bun run dev
 
+# Start interactive REPL with auto-loaded helpers
+repl:
+    node --eval "await import('./.replrc.js')" -i
+
 # Add a package dependency
 add package:
     bun add {{package}}
@@ -34,6 +38,10 @@ install:
 update:
     nix flake update
 
+# Upgrade package dependencies
+upgrade:
+    bun update
+
 # Clean build artifacts and dependencies
 clean:
     rm -rf dist node_modules bun.lockb
diff --git a/README.md b/README.md
index 24cd418..9473058 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,9 @@
 A minimal JavaScript development template using Nix. Key features:
 
 - Nix + Flakes for reproducible environments
-- Bun (fast JavaScript runtime)
+- Bun (fast JavaScript runtime & package manager)
 - Vite (development server & build tool)
+- Node.js (mature REPL with custom helpers)
 - ESLint + Prettier (linting & formatting)
 - Devshell commands via just
 
@@ -37,14 +38,29 @@ just dev
 fhs = true;
 ```
 
+## Available Commands
+
+Run `just` to see all available commands:
+
+```sh
+just dev       # Start dev server
+just repl      # Node.js REPL with helpers
+just lint      # Lint with ESLint
+just format    # Format with Prettier
+just build     # Production build
+just clean     # Clean build artifacts
+just update    # Update flake inputs
+just upgrade   # Upgrade bun packages
+```
+
 ## Customization
 
 This template provides minimal, sensible defaults. Customize as needed:
 
-- Add dependencies: `just add <package>`
 - Modify linting rules in `eslint.config.js`
 - Add Prettier config via `.prettierrc` if needed
 - Extend `Justfile` with project-specific commands
+- Add custom REPL helpers in `.replrc.js`
 
 ## Acknowledgments
 
diff --git a/nix/modules/devshell.nix b/nix/modules/devshell.nix
index 70265b1..6b88beb 100644
--- a/nix/modules/devshell.nix
+++ b/nix/modules/devshell.nix
@@ -21,6 +21,7 @@ in {
       nativeBuildInputs = with pkgs;
         [
           bun
+          nodejs
           eslint
           just
           prettierd