hacklab 0.5.4 → 0.6.0

package/README.md

@@ -22,7 +22,7 @@ npx hacklab@latest join
 ## The join ritual
 
 ```
-scan local AI usage → see your rank → pick a username → sign in with GitHub → claim
+scan local AI usage → see your rank → pick a username → sign in with GitHub → claim → chat
 ```
 
 1. **Scan** — reads your local AI token usage from Claude Code, Codex, Cursor,
@@ -35,6 +35,8 @@ scan local AI usage → see your rank → pick a username → sign in with GitHu
    uploads in the background while you get a shareable stats card.
 6. **Share** — a stats thumbnail (belt, level, rank, token breakdown) is rendered
    locally, copied to your clipboard, and you can post it to X in one keystroke.
+7. **Chat** — finally, you're offered the live channel (default yes). Decline and
+   you can jump in anytime with `hacklab chat`.
 
 ## Commands
 
@@ -43,13 +45,13 @@ scan local AI usage → see your rank → pick a username → sign in with GitHu
 - `hacklab sync` — re-scan local AI usage and sync it to your profile.
 - `hacklab whoami` — show who you're logged in as.
 - `hacklab drop "message"` — post a drop to your feed (`-u <url>` to attach a link).
-- `hacklab chat <sub>` — the channel and DMs (`live`, `tail`, `post`, `history`,
-  `dms`, `dm <handle>`, `flag`). Author handles are coloured by belt rank. Add
-  `--json` to any non-interactive subcommand for machine-readable output an agent
-  can drive.
+- `hacklab chat` — open the live channel (typing posts; this is the default, so
+  bare `hacklab chat` and `hacklab chat live` are the same). Other subcommands:
+  `tail`, `post`, `history`, `dms`, `dm <handle>`, `flag`. Author handles are
+  coloured by belt rank. Add `--json` to any non-interactive subcommand for
+  machine-readable output an agent can drive.
 - `hacklab login` — re-authenticate with GitHub.
-- `hacklab exam [--pyro|--hacker]` — run your belt exam (token usage + GitHub code).
-- `hacklab scan` — build your full profile (skills, repos, blog).
+- `hacklab logout` — clear your saved session on this machine.
 - `hacklab config <key> <value>` — set config (`cursor-api-key`, `cursor-email`).
 - `hacklab brag [path]` — sync a `.hacklab/project.yaml` to your profile.
 - `hacklab org` — edit the profile of an organization you've claimed. Pick a
@@ -59,33 +61,89 @@ scan local AI usage → see your rank → pick a username → sign in with GitHu
 
 ## Choosing a backend
 
-By default the CLI talks to **production** (`https://hacklab.so`). Pick another
-with `--env` (works on any command):
+Every command resolves which backend to talk to by the same precedence:
+
+1. **`--env <name>`** on the command line (highest);
+2. **`HACKLAB_APP_URL`** set in the environment;
+3. **the backend you logged into** (saved in the session file);
+4. **production** (`https://hacklab.so`) by default.
 
 ```bash
 hacklab join --env staging        # https://staging.hacklab.so
 hacklab join --env development     # http://localhost:3000
+hacklab drop "hi" --env staging    # the override applies to every command, not just login
 ```
 
-`--env` maps to a fixed URL; `HACKLAB_APP_URL` overrides it for a custom target.
+`--env` accepts any unambiguous abbreviation (`dev`, `prod`, `stag`) and the
+aliases `local`/`localhost` for development. Under the hood it just sets
+`HACKLAB_APP_URL` for that run, so an explicit `--env` overrides an inherited
+`HACKLAB_APP_URL`.
+
+Note that **sessions are per-backend**: your token is only valid on the backend
+you logged into. Overriding `--env` to a backend you haven't authenticated
+against will 401 until you `hacklab login --env <that>`. `hacklab whoami` shows
+the effective backend and warns when it differs from where you logged in.
 
 ## Environment
 
-- `HACKLAB_APP_URL` — explicit app base URL; overrides `--env`. Defaults to
-  production when unset.
+- `HACKLAB_APP_URL` — explicit app base URL (read from the real environment; the
+  CLI does not load any `.env` file). A command-line `--env` sets this for the
+  run, so `--env` wins over an inherited value. See **Choosing a backend** for
+  the full precedence.
 - `HACKLAB_SESSION_PATH` — custom path for the session file
   (default `~/.hacklab/session.json`).
+- `HACKLAB_CALLBACK_PORT` — pin the local OAuth callback port (default: a random
+  free port). Lets you forward a fixed port for the browser-callback flow on a
+  remote host.
+
+## Signing in
+
+`hacklab login` and `hacklab join` use **GitHub's device flow** by default,
+everywhere (desktop or headless): they print a short code and
+`github.com/login/device`. Open that on any device where you're signed into
+GitHub, enter the code, and authorize Hacklab — the terminal logs into the
+linked Hacklab account. No local server, no port forwarding, no localhost/app
+URL. (No Hacklab account linked to that GitHub yet? `hacklab join` registers
+one; `hacklab login` tells you to run `join`.)
+
+### `--browser`: the local browser flow
+
+Pass `--browser` to `login`/`join` to use the OAuth-redirect flow instead — it
+opens your browser and catches the redirect on a local callback server. Handy on
+a desktop where auto-opening a browser beats typing a code. On a remote host
+you'd forward the callback port (pin it with `HACKLAB_CALLBACK_PORT` so the
+forward is stable):
+
+```bash
+# on the remote host:
+HACKLAB_CALLBACK_PORT=8765 hacklab login --browser
+# from your laptop, forward that port, then open the printed URL:
+ssh -L 8765:localhost:8765 <this-host>
+```
+
+The device flow also falls back to `--browser` automatically if a backend
+doesn't expose the device routes yet (e.g. not-yet-deployed staging).
 
 ## Local development
 
-From the repo root, run the CLI from source against a local app:
+From the repo root, `pnpm cli <command>` runs the CLI from source (tsx, no
+build) and defaults to the **development** backend, so local work needs no
+flags:
+
+```bash
+pnpm cli chat                      # runs against http://localhost:3000
+pnpm cli join --env staging        # override the dev default per-command
+```
+
+The dev default lives only in the root `cli` script (`--env development`), so
+the published npm package still defaults to production. Use a throwaway session
+to avoid touching a real account:
 
 ```bash
-HACKLAB_SESSION_PATH=/tmp/hl-test.json \
-pnpm --filter hacklab dev join --env development
+HACKLAB_SESSION_PATH=/tmp/hl-test.json pnpm cli join
 ```
 
-`pnpm --filter hacklab dev <command>` runs `src/index.ts` via tsx (no build).
+Under the hood `pnpm cli` is `pnpm --filter hacklab dev` (= `tsx src/index.ts`).
 `pnpm --filter hacklab build` compiles to `dist/`.
 
 To reset a test account so its GitHub identity can join fresh:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hacklab",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,10 +10,9 @@
     "node": ">=20"
   },
   "bin": {
-    "hacklab": "./dist/index.js",
-    "ddd": "./bin/ddd"
+    "hacklab": "./dist/index.js"
   },
-  "files": ["dist", "bin"],
+  "files": ["dist"],
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",

package/bin/ddd

@@ -1,19 +0,0 @@
-#!/bin/sh
-# Wrapper that invokes the real dd.js entrypoint.
-# When used with a noglob alias (alias ddd='noglob ddd'), zsh won't
-# expand special characters like ? ! * before they reach Node.
-#
-# Resolve symlinks so dist/dd.js is found even when this script is invoked
-# through a bin symlink (e.g. /opt/homebrew/bin/ddd -> .../hacklab/bin/ddd).
-# A plain `dirname "$0"` would point at the symlink's dir, not the package.
-src="$0"
-while [ -L "$src" ]; do
-  dir="$(cd -P "$(dirname "$src")" && pwd)"
-  src="$(readlink "$src")"
-  case "$src" in
-    /*) ;;
-    *) src="$dir/$src" ;;
-  esac
-done
-dir="$(cd -P "$(dirname "$src")" && pwd)"
-exec node "$dir/../dist/dd.js" "$@"