@willh/copilotstatusline 0.1.0

package/docs/DEVELOPMENT.md

@@ -0,0 +1,79 @@
+# Development
+
+## Setup
+
+```sh
+bun install
+```
+
+The project is written in TypeScript. Bun runs source files and tests; the published bundle targets Node.js 22 or newer.
+
+## Verification
+
+```sh
+bun run lint
+bun test
+bun run build
+bun run example
+```
+
+`bun run lint` runs TypeScript checking before ESLint. The lint configuration is intentionally strict. Fix the implementation instead of suppressing a rule.
+
+## Architecture
+
+The external Copilot payload is parsed into `NormalizedCopilotStatus` before rendering. This boundary prevents payload aliases and nullable fields from spreading through widget logic.
+
+Formatter settings and Copilot CLI settings are separate:
+
+- formatter settings control lines, widgets, colors, Powerline, and local command behavior;
+- Copilot settings control whether and how Copilot invokes the formatter.
+
+Both settings writers use a temporary file and atomic rename. Copilot settings also receive timestamped backups because the file belongs to another application.
+
+## Adding a payload field
+
+1. Add the known optional field to `CopilotStatusSchema`.
+2. Normalize it in `normalizeCopilotStatus`.
+3. Add a widget type and catalog entry only if the value is useful independently.
+4. Render absence as `null` instead of a fabricated fallback.
+5. Add payload and rendering tests.
+
+Keep the top-level and nested schemas loose so future Copilot fields do not break existing installations.
+
+## Adding a widget
+
+1. Add its type to `WIDGET_TYPES` in `src/types/Settings.ts`.
+2. Add metadata to `WIDGET_CATALOG` in `src/widgets/catalog.ts`.
+3. Add rendering behavior to `renderWidget`.
+4. Add a focused renderer or widget test.
+
+Subprocess widgets must suppress stderr, use a short timeout, work with an absent command, and avoid filesystem mutations. Git and Jujutsu values should go through the existing TTL cache.
+
+## Integration testing
+
+Use a temporary Copilot home so local user settings are never touched:
+
+```sh
+temporary_home="$(mktemp -d)"
+COPILOT_HOME="$temporary_home" bun run src/copilotstatusline.ts --install global
+COPILOT_HOME="$temporary_home" bun run src/copilotstatusline.ts --check
+COPILOT_HOME="$temporary_home" bun run src/copilotstatusline.ts --uninstall
+```
+
+For custom formatter settings:
+
+```sh
+temporary_config="$(mktemp)"
+rm "$temporary_config"
+COPILOT_HOME="$temporary_home" bun run src/copilotstatusline.ts \
+  --config "$temporary_config" --install global
+```
+
+## Build
+
+```sh
+bun run build
+node dist/copilotstatusline.js --version
+```
+
+The postbuild script replaces the `__PACKAGE_VERSION__` placeholder from `package.json`. The bundle must remain executable as the npm `copilotstatusline` binary.

package/docs/USAGE.md

@@ -0,0 +1,135 @@
+# Usage
+
+## Runtime model
+
+GitHub Copilot CLI executes the configured shell command and sends a JSON object on stdin. `copilotstatusline` validates the known fields, normalizes aliases, loads formatter settings, and writes rendered lines to stdout.
+
+Unknown payload fields are accepted for forward compatibility. Missing optional fields hide the corresponding widgets. Invalid known field types fail the invocation with a concise stderr message and a nonzero exit code.
+
+## Installation
+
+Interactive installation:
+
+```sh
+npx -y copilotstatusline@latest
+```
+
+Non-interactive installation:
+
+```sh
+npx -y copilotstatusline@latest --install npm
+bunx -y copilotstatusline@latest --install bunx
+copilotstatusline --install global
+```
+
+The accepted install modes are `npm`, `bunx`, and `global`. Installation writes only to `$COPILOT_HOME/settings.json`, with `~/.copilot/settings.json` as the fallback. Existing files are backed up as `settings.json.bak.<timestamp>` before replacement.
+
+The installer:
+
+- preserves unrelated root and footer keys;
+- sets `statusLine.type` to `command`;
+- sets status-line padding to zero;
+- enables `footer.showCustom`;
+- refuses an installed Copilot CLI version older than 1.0.52.
+
+If the `copilot` executable cannot be resolved, installation still writes the configuration. This supports configuring an environment before Copilot CLI is added to `PATH`.
+
+## Uninstallation safety
+
+```sh
+copilotstatusline --uninstall
+```
+
+Uninstallation removes `statusLine` only when its command is recognized as belonging to `copilotstatusline`. A different custom status-line command is left untouched.
+
+## Formatter settings
+
+Default path:
+
+```text
+~/.config/copilotstatusline/settings.json
+```
+
+`XDG_CONFIG_HOME` changes the Unix root. `%APPDATA%` is used on Windows. A custom path can be selected with:
+
+```sh
+copilotstatusline --config /absolute/path/settings.json
+```
+
+Combine the flag with installation so Copilot always invokes the same file:
+
+```sh
+copilotstatusline --config /absolute/path/settings.json --install global
+```
+
+The settings schema is versioned independently of Copilot settings:
+
+```json
+{
+  "version": 1,
+  "lines": [
+    [
+      {
+        "id": "model",
+        "type": "model",
+        "color": "cyan",
+        "backgroundColor": "none",
+        "bold": false,
+        "raw": false,
+        "prefix": "",
+        "suffix": "",
+        "merge": false,
+        "hideWhenZero": false
+      }
+    ]
+  ],
+  "defaultSeparator": " · ",
+  "colorLevel": 2,
+  "powerline": {
+    "enabled": false,
+    "separator": ""
+  },
+  "gitCacheTtlSeconds": 5
+}
+```
+
+`colorLevel` accepts zero through three. Zero disables ANSI styling. The current renderer uses ANSI 16-color names; values above zero enable them.
+
+## Widget configuration
+
+Every widget has an `id`, `type`, foreground and background colors, bold and raw-value flags, prefix and suffix text, merge behavior, and an optional zero-hiding flag.
+
+Additional widget fields:
+
+- `custom-text`: set `value`.
+- `custom-command`: set `command`.
+- `separator`: set `value`.
+- `flex`: no additional value; it consumes remaining terminal width.
+
+Custom commands execute through the local shell with a 500 ms timeout. Only the first output line is rendered. Store only trusted commands in the settings file.
+
+## Payload fields
+
+The normalized widgets currently use:
+
+- session: `session_id`, `session_name`, `cwd`, `workspace`, and `version`;
+- model: string or object `model`, `modelName`, `current_model`, `reasoning_effort`, and `effort.level`;
+- context: cumulative input, output, cache read/write, reasoning and total tokens, last-call tokens, current context, displayed limit, and used percentage;
+- cost: API duration, total duration, premium requests, and added/removed lines;
+- permission state: `allow_all`.
+
+## Diagnostics
+
+Inspect integration status:
+
+```sh
+copilotstatusline --check
+```
+
+Test rendering without changing Copilot settings:
+
+```sh
+bun run example
+```
+
+Warnings about malformed formatter settings go to stderr. Status-line content remains on stdout so Copilot does not receive diagnostics as display content.

package/docs/WINDOWS.md

@@ -0,0 +1,54 @@
+# Windows
+
+## Requirements
+
+- GitHub Copilot CLI 1.0.52 or newer
+- Node.js 22 or newer
+- Windows Terminal or another terminal with ANSI support
+
+## Paths
+
+Copilot user settings:
+
+```text
+%COPILOT_HOME%\settings.json
+```
+
+When `COPILOT_HOME` is not set, the fallback is the `.copilot` directory in the current user's home directory.
+
+Formatter settings:
+
+```text
+%APPDATA%\copilotstatusline\settings.json
+```
+
+`--config <path>` overrides the formatter settings path. Installing with the same command writes the absolute Windows path into Copilot settings.
+
+## Installation
+
+PowerShell:
+
+```powershell
+npx -y copilotstatusline@latest --install npm
+```
+
+If a global package is installed:
+
+```powershell
+copilotstatusline --install global
+```
+
+Restart Copilot CLI after installation.
+
+## Powerline
+
+The default Powerline separator requires a font containing U+E0B0. If the glyph is missing, disable Powerline in the TUI or install a compatible terminal font and select it in the terminal profile.
+
+## Diagnostics
+
+```powershell
+copilotstatusline --check
+Get-Content $env:COPILOT_HOME\settings.json
+```
+
+All helper subprocesses are launched with hidden Windows process windows. Missing Git or Jujutsu executables cause only the related widgets to be omitted.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@willh/copilotstatusline",
+  "version": "0.1.0",
+  "bugs": {
+    "url": "https://github.com/sirmalloc/copilotstatusline/issues"
+  },
+  "description": "A customizable status line formatter for GitHub Copilot CLI",
+  "main": "./dist/copilotstatusline.js",
+  "module": "./dist/copilotstatusline.js",
+  "type": "module",
+  "bin": {
+    "copilotstatusline": "./dist/copilotstatusline.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/copilotstatusline.js",
+      "default": "./dist/copilotstatusline.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "NOTICE"
+  ],
+  "scripts": {
+    "start": "bun run src/copilotstatusline.ts",
+    "build": "rm -rf dist/* && bun build src/copilotstatusline.ts --target=node --outfile=dist/copilotstatusline.js --target-version=22",
+    "postbuild": "bun run scripts/replace-version.ts",
+    "example": "bun run src/copilotstatusline.ts < scripts/payload.example.json",
+    "prepublishOnly": "bun run build",
+    "lint": "bun tsc --noEmit && eslint . --config eslint.config.js --max-warnings=0",
+    "lint:fix": "bun tsc --noEmit && eslint . --config eslint.config.js --max-warnings=0 --fix",
+    "docs": "typedoc",
+    "docs:clean": "rm -rf typedoc"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.2.3",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.10",
+    "eslint": "^10.0.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-newlines": "^2.0.0",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.3.0",
+    "ink": "6.2.0",
+    "ink-select-input": "^6.2.0",
+    "ink-text-input": "^6.0.0",
+    "react": "19.2.7",
+    "slice-ansi": "^7.1.2",
+    "string-width": "^8.1.0",
+    "strip-ansi": "^7.1.0",
+    "typedoc": "^0.28.12",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.39.1",
+    "vitest": "^4.0.18",
+    "zod": "^4.0.17"
+  },
+  "keywords": [
+    "github-copilot",
+    "copilot-cli",
+    "cli",
+    "status-line",
+    "terminal"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sirmalloc/copilotstatusline.git"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "trustedDependencies": [
+    "unrs-resolver"
+  ]
+}