@hasna/statusline 0.0.1 → 0.0.3

package/README.md

@@ -8,7 +8,7 @@ and more — rendered as a single line for your agent's status bar.
 apple03 · statusline (main) · 12h · 1.2k · fable 5 [1m] · 90% left · $0.04
 ```
 
-Zero runtime dependencies. Built with [Bun](https://bun.sh) + TypeScript. Apache-2.0.
+Built with [Bun](https://bun.sh) + TypeScript. The CLI renderer is dependency-light; the optional MCP server uses the Model Context Protocol SDK. Apache-2.0.
 
 ## Install
 
@@ -21,34 +21,146 @@ That's it — Claude Code picks it up on the next status refresh (no restart nee
 
 ## Segments
 
-`statusline list` shows everything available:
+`statusline list` shows a compact, enabled-first summary of your segments (use
+`statusline list --all` for every row). The table below is the full catalog — all 18
+segment ids from `src/segments/index.ts`.
 
+`renderLine` walks your configured segment order, renders each one, and **drops**
+anything that returns `null` or throws. A failed segment never breaks the host UI.
+
+| Segment | Default | Description | Data source | Omit when | Example |
+|---------|---------|-------------|-------------|-----------|---------|
+| `machine` | on | Machine hostname (short) | `os.hostname()` — first label before `.` | never (always renders) | `apple03` |
+| `project` | on | Project name with current Git branch | `gitProjectName(cwd)` + `gitBranch(cwd)`; falls back to cwd basename | no project name resolvable | `statusline (main)` |
+| `project-name` | off | Project name only | `gitProjectName(cwd)` or cwd basename | outside a git repo with no name | `statusline` |
+| `git-branch` | off | Current Git branch | `git branch --show-current` in `cwd` | outside git or detached | `main` |
+| `commit-age` | on | Time since last commit (compact) | `git log -1` epoch vs now | no commits / not a repo | `12h` |
+| `loc` | on | Lines of code tracked by Git (compact) | `git ls-files` + `wc -l` in repo root | outside git or zero lines | `1.2k` |
+| `current-dir` | off | Current working directory (basename) | `StatusContext.cwd` | never (always renders basename) | `open-statusline` |
+| `model` | off | Current model name (no context tag) | `StatusContext.model.id` via friendly formatter | no model id | `fable 5` |
+| `model-context` | on | Model name with context-size tag | same formatter, keeps `[tag]` suffix | no model id | `fable 5 [1m]` |
+| `model-with-reasoning` | off | Model name with its reasoning effort | `model.display_name` (or friendly id) + `effort.level`; falls back to `thinking.enabled`, which the host defaults to on | no model | `Fable (xhigh)` |
+| `auth-profile` | off | Account profile this session runs as | this process's `CLAUDE_CONFIG_DIR`, resolved against the accounts registry | config dir is unmanaged and has no login | `account001` |
+| `auth-email` | off | Account email this session is logged in as | the agent's own login record for this config dir, else the registry | no login recorded | `dev@example.com` |
+| `five-hour-limit` | off | Percentage of the 5-hour rate limit used | `rate_limits.five_hour.used_percentage` | host reports no limit data | `5h:42%` |
+| `seven-day-limit` | off | Percentage of the 7-day rate limit used | `rate_limits.seven_day.used_percentage` | host reports no limit data | `7d:12%` |
+| `thread-title` | off | Thread title set with `/rename` | `session_name` | thread not renamed | `ship it` |
+| `context-used` | off | Percentage of context window used | session transcript JSONL (`contextUsage`) | transcript missing/unreadable | `10%` |
+| `context-remaining` | on | Percentage of context window remaining | transcript via `contextUsage` | transcript missing/unreadable | `90% left` |
+| `used-tokens` | off | Total tokens in the context window | transcript usage block (input + output) | transcript missing/unreadable | `102k tok` |
+| `cost` | on | Session cost in USD | `StatusContext.cost.totalCostUsd` | cost is zero or missing | `$1,234.50` |
+| `duration` | off | Session wall-clock duration | `StatusContext.cost.totalDurationMs` | duration missing | `1h30m` |
+| `lines-changed` | off | Lines added/removed this session | `cost.totalLinesAdded/Removed` | both zero | `+142/-18` |
+| `output-style` | off | Active output style | `StatusContext.outputStyle` | style is `default` or missing | `concise` |
+| `agent-version` | off | Host agent version | `StatusContext.version` | version missing | `v2.1.39` |
+| `session-id` | off | Session identifier (short) | first UUID segment of `sessionId` | no session id | `abc12345` |
+
+### Context segments and transcripts
+
+Segments that report context usage (`context-used`, `context-remaining`, `used-tokens`)
+read the session transcript path from the provider payload. `contextUsage` scans the
+JSONL for the last assistant entry with a `usage` block and sums
+`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. Window size is
+**1,000,000** when the model id contains `[1m]`, otherwise **200,000**.
+
+With the test fixture transcript (100k input-side tokens on a 1m window), expect
+`context-used` → `10%`, `context-remaining` → `90% left`, `used-tokens` → `102k tok`.
+
+### Which account am I? (`auth-profile`)
+
+Statusline payloads carry no account or profile field, so `auth-profile` reads the
+config dir **this process** was handed — `CLAUDE_CONFIG_DIR`, which multi-account
+launchers set per session — and resolves it in order:
+
+1. the `@hasna/accounts` registry entry whose `dir` matches, preferring one that
+   belongs to the agent being rendered (a dir can be claimed by several tools;
+   another tool's entry is never adopted);
+2. the managed layout `<accountsHome>/profiles/<tool>/<name>`, for dirs the local
+   registry has no entry for;
+3. the account email the agent recorded in that dir, when neither names a profile.
+
+It never consults an "active"/"current" profile pointer. Those are global — and,
+against a shared registry, global across every machine: two sessions running under
+different accounts would both report whichever profile was switched to last.
+Resolving from the process's own config dir keeps concurrent sessions independent.
+
+Where the agent's login record lives mirrors Claude Code's own rule: `.config.json`
+in the config dir wins, otherwise `.claude<oauth-variant>.json`. Note the base dir
+is the config dir **or the home dir** — with `CLAUDE_CONFIG_DIR` unset the file is
+`~/.claude.json`, a sibling of `~/.claude` rather than something inside it.
+
+Registry location comes from `@hasna/accounts` itself when it is installed
+alongside this package (imported lazily, only when an auth segment renders);
+otherwise from its documented overrides `ACCOUNTS_STORE_PATH`, then
+`ACCOUNTS_HOME`, then `~/.hasna/accounts`. `@hasna/accounts` is not a dependency —
+with none of it present the segment renders nothing rather than guessing.
+
+**Known limitation.** Renaming a profile does not move its dir. For a profile the
+local registry has no entry for, step 2 therefore reports the name the dir was
+created with until the registry catches up. Step 1 is tried first so a profile the
+registry knows about always wins.
+
+### Colours
+
+Segments may declare a colour, applied by `renderLine` when colours are on
+(the default). The rate-limit segments escalate from yellow to red past 80%.
+
+```bash
+statusline colors off      # or set "colors": false in the config
 ```
-  [x] machine            Machine hostname (short)
-  [x] project            Project name with current Git branch
-  [ ] project-name       Project name (omitted when unavailable)
-  [ ] git-branch         Current Git branch (omitted when unavailable)
-  [x] commit-age         Time since last commit (compact)
-  [x] loc                Lines of code tracked by Git (compact)
-  [ ] current-dir        Current working directory (basename)
-  [ ] model              Current model name
-  [x] model-context      Model name with context-size tag (e.g. [1m])
-  [ ] context-used       Percentage of context window used (omitted when unknown)
-  [x] context-remaining  Percentage of context window remaining (omitted when unknown)
-  [ ] used-tokens        Total tokens in the context window (omitted when unknown)
-  [x] cost               Session cost in USD (omitted when zero)
-  [ ] duration           Session wall-clock duration
-  [ ] lines-changed      Lines added/removed this session (omitted when zero)
-  [ ] output-style       Active output style (omitted when default)
-  [ ] agent-version      Host agent version (e.g. Claude Code version)
-  [ ] session-id         Session identifier (short)
+
+`NO_COLOR` in the environment always wins.
+
+### Quick reference from `statusline list`
+
+`statusline list` is compact by default so it stays friendly in agent terminals —
+enabled segments first, capped rows, and hints for the detail paths:
+
+```
+Segments: 7 enabled / 18 total (showing 12 of 18)
+state  default  id
+on     yes      machine
+on     yes      project
+on     yes      commit-age
+on     yes      loc
+on     yes      model-context
+on     yes      context-remaining
+on     yes      cost
+off    no       project-name
+off    no       git-branch
+off    no       current-dir
+off    no       model
+off    no       context-used
+Hint: use `--all` for all matching rows, `statusline show <id>` for details, `--verbose` for descriptions, `--json` for machines.
 ```
 
+Use gradual disclosure when you need more:
+
+```bash
+statusline list --verbose             # include descriptions, still capped
+statusline list --all --verbose       # include every row with descriptions
+statusline list --all                 # show every segment row
+statusline list --limit 5             # cap rows explicitly
+statusline list --enabled             # only enabled segments
+statusline list --disabled            # only disabled segments
+statusline list --search token        # filter by id or description
+statusline list --json                # structured output for tooling
+statusline show model-context         # full details for one segment
+statusline inspect used-tokens --json # JSON detail path
+```
+
+`statusline list --json` returns `{ total, matching, showing, limited, segments, next }`.
+Each segment has `{ id, description, enabled, defaultEnabled }`; `next` is `null`
+unless the result is limited. Column padding is display-only — it does not affect
+statusbar width.
+
 ## Usage
 
 ```bash
+statusline list                          # compact segment summary
 statusline enable used-tokens duration    # turn segments on (appended at the end)
 statusline disable loc                    # turn segments off
+statusline colors off                     # drop ANSI colours
 statusline order machine project model-context cost   # exact order = enabled set
 statusline separator " | "                # change the separator
 statusline preview                        # render a sample line from the current dir
@@ -64,6 +176,23 @@ Config lives at `~/.config/statusline/config.json` (override with `$STATUSLINE_C
 }
 ```
 
+## Theming and layout
+
+There is no fixed width knob — the rendered line grows with enabled segments. Control
+length practically:
+
+1. **Fewer segments** — `statusline disable` segments you do not need, or `statusline order` to pick a compact set.
+2. **Shorter separator** — `statusline separator "·"` or `" | "` (default is `" · "`).
+3. **Split project info** — use `project-name` + `git-branch` instead of combined `project` if you want to omit the branch when unknown.
+4. **Rely on omit-when-null** — segments like `cost`, `context-remaining`, and `lines-changed` disappear when data is unavailable instead of showing placeholders.
+
+**Segment order matters.** `statusline order a b c` sets both the display order and the
+exact enabled set — segments not listed are disabled. `statusline enable` appends new
+ids to the end; `statusline disable` removes them.
+
+**Config path:** `~/.config/statusline/config.json`, overridable with `$STATUSLINE_CONFIG`.
+`statusline reset` restores `defaultConfig()` (separator + default segment list above).
+
 ## How it works
 
 Claude Code pipes a JSON payload (cwd, model, session cost, transcript path, …) to the
@@ -72,11 +201,118 @@ renders each enabled segment, drops anything unavailable, and prints one line. S
 that need more than the payload offers (e.g. `context-remaining`) read the session
 transcript to compute it. A segment failure is never fatal — it's simply omitted.
 
+## SDK
+
+The package root is a side-effect-free SDK surface:
+
+```ts
+import {
+  renderStatusline,
+  listSegments,
+  enableSegments,
+  saveConfig,
+  loadConfig,
+} from "@hasna/statusline";
+
+const config = loadConfig();
+const line = await renderStatusline({ cwd: process.cwd() }, config);
+const next = enableSegments(["duration"], config).config;
+saveConfig(next);
+```
+
+Useful exports include `parseClaudeInput`, `renderLine`, `segments`, `getSegment`,
+`defaultConfig`, `loadConfig`, `saveConfig`, `configPath`, `previewStatusline`,
+`orderSegments`, `disableSegments`, `setSeparator`, and `installClaude`.
+
+## MCP
+
+`statusline-mcp` starts a stdio MCP server:
+
+```bash
+statusline-mcp
+```
+
+It exposes safe tools for `render_statusline`, `preview_statusline`,
+`list_segments`, `get_config`, `update_config`, `enable_segments`,
+`disable_segments`, `order_segments`, and `reset_config`. Config mutation tools
+require `confirm_write: true`; every mutation tool supports `dry_run: true`.
+
+The MCP server intentionally does not mutate Claude settings. Use
+`statusline install claude` or the `installClaude()` SDK helper when you
+explicitly want to wire the CLI into Claude Code.
+
 ## Providers
 
+### Claude Code (implemented)
+
+```bash
+bun install -g @hasna/statusline
+statusline install claude
+```
+
+`installClaude()` writes to `$CLAUDE_CONFIG_DIR/settings.json`, falling back to
+`~/.claude/settings.json`. This matters for multi-account setups: when a session is
+bound to an isolated config dir, `~/.claude/settings.json` is never read, so
+installing there wires up a statusline that silently never runs.
+
+Only `~/.claude` is created on demand. Every other target — an isolated config
+dir, or a path passed as `installClaude(path)` — must already exist: installing
+there is a request to configure a profile someone else created, not to fabricate
+one. The rule follows the target, not the shell you install from, so driving a
+list of profiles gives the same answer from any session. Pass the environment to
+resolve against as `installClaude(undefined, env)`.
+
+```json
+{
+  "statusLine": { "type": "command", "command": "statusline render" }
+}
+```
+
+Existing settings are preserved; the previous file is backed up as
+`settings.json.bak-statusline`. Claude Code pipes JSON on stdin to `statusline render`
+on every status refresh — **no restart needed**.
+
+**stdin fields** parsed by `parseClaudeInput` (`src/providers/claude.ts`):
+
+| Payload field | Maps to `StatusContext` |
+|---------------|-------------------------|
+| `cwd` / `workspace.current_dir` | `cwd` |
+| `workspace.project_dir` | `projectDir` |
+| `model.id`, `model.display_name` | `model.id`, `model.displayName` |
+| `cost.total_cost_usd` | `cost.totalCostUsd` |
+| `cost.total_duration_ms` | `cost.totalDurationMs` |
+| `cost.total_lines_added/removed` | `cost.totalLinesAdded/Removed` |
+| `transcript_path` | `transcriptPath` |
+| `session_id` | `sessionId` |
+| `session_name` | `sessionName` |
+| `version` | `version` |
+| `output_style.name` | `outputStyle` |
+| `effort.level` | `effort` |
+| `thinking.enabled` | `thinking` |
+| `rate_limits.five_hour.used_percentage` | `rateLimits.fiveHour.usedPercentage` |
+| `rate_limits.seven_day.used_percentage` | `rateLimits.sevenDay.usedPercentage` |
+
+Every field is optional — partial or empty payloads still produce a usable context.
+
+### Codewith (not implemented)
+
+`statusline install` only accepts `claude` today. Running
+`statusline install codewith` errors with *unsupported target* (`src/cli.ts`).
+
+The renderer is provider-agnostic: a future `parseCodewithInput` would map Codewith's
+status payload into `StatusContext` (`src/providers/types.ts`) and reuse the same
+segment registry. No install wiring exists yet (tracked in STA-00003).
+
+### Cursor (not implemented)
+
+Same gap as Codewith — no `statusline install cursor` subcommand and no Cursor-specific
+parser. A future adapter would implement `parseCursorInput` → `StatusContext` and hook
+into Cursor's status bar the same way Claude does (tracked in STA-00004).
+
+### Other agents
+
 | Agent | Status |
 |-------|--------|
-| Claude Code | ✅ `statusline install claude` |
 | OpenCode | ⏳ no statusline/footer hook in its config as of v1.3.x — the renderer is provider-agnostic (`src/providers/`), so an adapter slots in the moment one exists |
 | Codex CLI | Codex ships its own built-in segment picker; no external command hook |
 
@@ -87,8 +323,16 @@ Adding a provider means one small parser: agent payload → `StatusContext`
 
 ```bash
 bun install
+bun run typecheck
 bun test
-echo '{"cwd":"'$PWD'","model":{"id":"claude-fable-5[1m]"}}' | bun src/index.ts render
+bun run build
+echo '{"cwd":"'$PWD'","model":{"id":"claude-fable-5[1m]"}}' | bun src/cli.ts render
+```
+
+Spot-check fixture output:
+
+```bash
+cat test/fixtures/claude-input.json | bun src/cli.ts render
 ```
 
 ## License

package/dist/accounts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which account is *this* session running as?
+ *
+ * The host agent's statusline payload carries no account or profile field, so
+ * the answer has to come from the process environment. Tools that manage
+ * several logins (`@hasna/accounts`, and Claude Code itself) isolate each
+ * login in its own config dir and point the child process at it via
+ * `CLAUDE_CONFIG_DIR`. That variable is per-process, so it is the only signal
+ * that stays correct when several sessions run under different accounts at the
+ * same time.
+ *
+ * Deliberately NOT used: any "active"/"current"/"applied" profile pointer.
+ * Those are global — every concurrent session would report whichever profile
+ * was switched to last, which is the staleness this module exists to avoid.
+ */
+export interface SessionAccount {
+    /** Config dir this session is running against (canonicalized). */
+    configDir: string;
+    /** Managed profile name owning that dir, when it can be resolved. */
+    profile: string | null;
+    /** Tool id the profile belongs to (e.g. "claude"), when known. */
+    tool: string | null;
+    /**
+     * How `profile` was resolved. `"layout"` means it was read off the dir path
+     * rather than the registry, which is authoritative about the dir but can lag
+     * a rename — see `layoutProfile`. Surfaced for diagnostics, not for display.
+     */
+    source: "registry" | "layout" | null;
+}
+type Env = Record<string, string | undefined>;
+/** Config dir the current process is bound to, for settings and registry lookup. */
+export declare function sessionConfigDir(env?: Env): string;
+/**
+ * Path of the host agent's account record for this session, or null when none
+ * of its known filenames are present.
+ */
+export declare function sessionStateFile(env?: Env): string | null;
+/**
+ * Resolve the profile owning this session. `tool` is the agent being rendered
+ * for, used to disambiguate a config dir claimed by several tools. Never throws.
+ */
+export declare function sessionAccount(env?: Env, tool?: string): Promise<SessionAccount>;
+/**
+ * Email this session is logged in as. The host agent's own record for this
+ * config dir wins over the registry's copy, which can lag behind a re-login.
+ * Read separately from `sessionAccount` because it parses the agent's state
+ * blob, which is large enough to only touch when a segment asks for it.
+ */
+export declare function sessionAccountEmail(env?: Env, tool?: string): Promise<string | null>;
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export declare function runCli(argv?: string[]): Promise<void>;