@kmugalkhod/lightcode 0.7.1 → 0.9.0

package/README.md

@@ -1,119 +1,119 @@
-# Lightcode
-
-A personal AI coding agent with a terminal UI. Lightcode pairs an OpenTUI
-chat interface with a local Hono API server, persistent SQLite sessions, a
-permission-gated tool suite (files, shell, git, web, MCP), and tiered context
-optimization that keeps long sessions inside the model's context window
-without ever losing history.
-
-## Install
-
-```bash
-npm install -g @kmugalkhod/lightcode
-lightcode
-```
-
-Works on macOS (Apple Silicon and Intel), Linux, and Windows. Bun ships with
-the package, so there's nothing else to install — the first `lightcode` run
-uses the bundled runtime automatically (and reuses a system Bun if you already
-have one). The published package is scoped as `@kmugalkhod/lightcode`; the
-command it installs is `lightcode`.
-
-## Quick start (from source)
-
-```bash
-bun install
-bun run cli:dev        # starts the TUI; it boots the server automatically
-```
-
-Lightcode is aware of the directory you launch it in: each turn it reads the
-project's shape (top-level files, git branch/status) and any `AGENTS.md` /
-`CLAUDE.md` / `README.md`, so "review my code" or "explain this" inspects your
-actual files instead of asking you to paste them.
-
-On first run Lightcode walks you through provider setup (Anthropic,
-OpenRouter, OpenCode Zen, or any OpenAI-compatible endpoint) and stores the
-API key in `~/.lightcode/credentials.json`. Environment variables such as
-`ANTHROPIC_API_KEY` always take precedence.
-
-## Commands
-
-```bash
-bun run cli:dev          # TUI (auto-starts the server)
-bun run server:dev       # API server alone, watch mode
-bun run typecheck        # TypeScript + tool schema preflight
-bun test                 # test suite
-bun run build            # build the publishable package into dist/
-bun run release          # verify + build + npm pack (--publish to release)
-```
-
-## Configuration
-
-Settings merge from `~/.lightcode/settings.json`, then
-`.lightcode/settings.json` in the project, then `LIGHTCODE_*` environment
-variables. Notable keys:
-
-| Key | Purpose |
-| --- | --- |
-| `provider`, `model`, `baseUrl` | Provider selection and model id |
-| `defaultMode` | `build` or `plan` |
-| `permissionMode`, `permissions` | Tool permission policy |
-| `context.compactAtFraction` | Context compaction threshold (default 0.8) |
-| `context.pruneAtFraction` | Tool-output pruning threshold (default 0.6) |
-| `context.contextWindowOverride` | Override the model context window |
-| `maxRetries` | Provider-call retries for transient errors (default 5) |
-| `autoContinue.stallTimeoutSeconds` | Abort+retry a byte-silent stream (default 300; raise for very slow reasoning models) |
-| `autoContinue.maxErrorRetries` | Auto-resends before surfacing a stream error (default 8) |
-
-The local companion server listens on `127.0.0.1:4983` (uncommon on purpose —
-port 3000 belongs to the apps you build). Override with `PORT` for the server
-and `LIGHTCODE_API_URL` for the CLI. Runtime model switching: `/model` in the
-TUI lists every OpenRouter model and persists the choice to
-`~/.lightcode/settings.json`. Diagnostics: `GET /diagnostics/connectivity`
-probes the provider endpoint, and daily JSONL logs live under the Lightcode
-data directory (`logs/`).
-
-## Context optimization
-
-Long sessions stay healthy through three tiers: real-usage-calibrated token
-estimation, free pruning of stale tool outputs and duplicate file reads, and
-LLM-written summaries once the compaction threshold is crossed (with an
-extractive fallback when the model is unreachable). The full conversation is
-always preserved in SQLite — compaction only changes what the model sees.
-Use `/compact` in a chat to compact manually.
-
-## Skills
-
-Skills are reusable instruction files the agent can load on demand — a recipe
-for a recurring task (writing a PR description, cutting a release, following a
-review checklist). Each skill is a `SKILL.md` file with frontmatter:
-
-```markdown
----
-name: pr-description
-description: Write a clear PR title and description from the diff.
----
-
-# Instructions the agent follows when this skill is loaded…
-```
-
-Lightcode discovers skills from three locations, first match wins (project
-overrides user):
-
-1. `.lightcode/skills/<name>/SKILL.md` — project-local
-2. `.agents/skills/<name>/SKILL.md` — project-local (fallback)
-3. `~/.lightcode/skills/<name>/SKILL.md` — available in every project
-
-Each turn the agent is told which skills are available (name + description), so
-just ask it to "use the pr-description skill" (or mention the skill by name) and
-it loads the instructions via the `skill` tool and follows them. Run `/skills`
-in the TUI to list what's installed. Only simple `key: value` frontmatter lines
-are parsed (`name`, `description`); the rest of the file is the instruction body.
-
-## Workspaces
-
-- `apps/cli` — OpenTUI React terminal interface
-- `apps/server` — Hono API server (sessions, streaming, diagnostics)
-- `packages/ai` — agent core: tools, permissions, context engine, config
-- `packages/db` — Prisma + local SQLite storage
-- `packages/shared` — logging, errors, version
+# Lightcode
+
+A personal AI coding agent with a terminal UI. Lightcode pairs an OpenTUI
+chat interface with a local Hono API server, persistent SQLite sessions, a
+permission-gated tool suite (files, shell, git, web, MCP), and tiered context
+optimization that keeps long sessions inside the model's context window
+without ever losing history.
+
+## Install
+
+```bash
+npm install -g @kmugalkhod/lightcode
+lightcode
+```
+
+Works on macOS (Apple Silicon and Intel), Linux, and Windows. Bun ships with
+the package, so there's nothing else to install — the first `lightcode` run
+uses the bundled runtime automatically (and reuses a system Bun if you already
+have one). The published package is scoped as `@kmugalkhod/lightcode`; the
+command it installs is `lightcode`.
+
+## Quick start (from source)
+
+```bash
+bun install
+bun run cli:dev        # starts the TUI; it boots the server automatically
+```
+
+Lightcode is aware of the directory you launch it in: each turn it reads the
+project's shape (top-level files, git branch/status) and any `AGENTS.md` /
+`CLAUDE.md` / `README.md`, so "review my code" or "explain this" inspects your
+actual files instead of asking you to paste them.
+
+On first run Lightcode walks you through provider setup (Anthropic,
+OpenRouter, OpenCode Zen, or any OpenAI-compatible endpoint) and stores the
+API key in `~/.lightcode/credentials.json`. Environment variables such as
+`ANTHROPIC_API_KEY` always take precedence.
+
+## Commands
+
+```bash
+bun run cli:dev          # TUI (auto-starts the server)
+bun run server:dev       # API server alone, watch mode
+bun run typecheck        # TypeScript + tool schema preflight
+bun test                 # test suite
+bun run build            # build the publishable package into dist/
+bun run release          # verify + build + npm pack (--publish to release)
+```
+
+## Configuration
+
+Settings merge from `~/.lightcode/settings.json`, then
+`.lightcode/settings.json` in the project, then `LIGHTCODE_*` environment
+variables. Notable keys:
+
+| Key | Purpose |
+| --- | --- |
+| `provider`, `model`, `baseUrl` | Provider selection and model id |
+| `defaultMode` | `build` or `plan` |
+| `permissionMode`, `permissions` | Tool permission policy |
+| `context.compactAtFraction` | Context compaction threshold (default 0.8) |
+| `context.pruneAtFraction` | Tool-output pruning threshold (default 0.6) |
+| `context.contextWindowOverride` | Override the model context window |
+| `maxRetries` | Provider-call retries for transient errors (default 5) |
+| `autoContinue.stallTimeoutSeconds` | Abort+retry a byte-silent stream (default 300; raise for very slow reasoning models) |
+| `autoContinue.maxErrorRetries` | Auto-resends before surfacing a stream error (default 8) |
+
+The local companion server listens on `127.0.0.1:4983` (uncommon on purpose —
+port 3000 belongs to the apps you build). Override with `PORT` for the server
+and `LIGHTCODE_API_URL` for the CLI. Runtime model switching: `/model` in the
+TUI lists every OpenRouter model and persists the choice to
+`~/.lightcode/settings.json`. Diagnostics: `GET /diagnostics/connectivity`
+probes the provider endpoint, and daily JSONL logs live under the Lightcode
+data directory (`logs/`).
+
+## Context optimization
+
+Long sessions stay healthy through three tiers: real-usage-calibrated token
+estimation, free pruning of stale tool outputs and duplicate file reads, and
+LLM-written summaries once the compaction threshold is crossed (with an
+extractive fallback when the model is unreachable). The full conversation is
+always preserved in SQLite — compaction only changes what the model sees.
+Use `/compact` in a chat to compact manually.
+
+## Skills
+
+Skills are reusable instruction files the agent can load on demand — a recipe
+for a recurring task (writing a PR description, cutting a release, following a
+review checklist). Each skill is a `SKILL.md` file with frontmatter:
+
+```markdown
+---
+name: pr-description
+description: Write a clear PR title and description from the diff.
+---
+
+# Instructions the agent follows when this skill is loaded…
+```
+
+Lightcode discovers skills from three locations, first match wins (project
+overrides user):
+
+1. `.lightcode/skills/<name>/SKILL.md` — project-local
+2. `.agents/skills/<name>/SKILL.md` — project-local (fallback)
+3. `~/.lightcode/skills/<name>/SKILL.md` — available in every project
+
+Each turn the agent is told which skills are available (name + description), so
+just ask it to "use the pr-description skill" (or mention the skill by name) and
+it loads the instructions via the `skill` tool and follows them. Run `/skills`
+in the TUI to list what's installed. Only simple `key: value` frontmatter lines
+are parsed (`name`, `description`); the rest of the file is the instruction body.
+
+## Workspaces
+
+- `apps/cli` — OpenTUI React terminal interface
+- `apps/server` — Hono API server (sessions, streaming, diagnostics)
+- `packages/ai` — agent core: tools, permissions, context engine, config
+- `packages/db` — Prisma + local SQLite storage
+- `packages/shared` — logging, errors, version

package/assets/grammars/c/highlights.scm

@@ -0,0 +1,341 @@
+; Lower priority to prefer @variable.parameter when identifier appears in parameter_declaration.
+((identifier) @variable
+  (#set! priority 95))
+
+(preproc_def
+  (preproc_arg) @variable)
+
+[
+  "default"
+  "goto"
+  "asm"
+  "__asm__"
+] @keyword
+
+[
+  "enum"
+  "struct"
+  "union"
+  "typedef"
+] @keyword.type
+
+[
+  "sizeof"
+  "offsetof"
+] @keyword.operator
+
+(alignof_expression
+  .
+  _ @keyword.operator)
+
+"return" @keyword.return
+
+[
+  "while"
+  "for"
+  "do"
+  "continue"
+  "break"
+] @keyword.repeat
+
+[
+  "if"
+  "else"
+  "case"
+  "switch"
+] @keyword.conditional
+
+[
+  "#if"
+  "#ifdef"
+  "#ifndef"
+  "#else"
+  "#elif"
+  "#endif"
+  "#elifdef"
+  "#elifndef"
+  (preproc_directive)
+] @keyword.directive
+
+"#define" @keyword.directive.define
+
+"#include" @keyword.import
+
+[
+  ";"
+  ":"
+  ","
+  "."
+  "::"
+] @punctuation.delimiter
+
+"..." @punctuation.special
+
+[
+  "("
+  ")"
+  "["
+  "]"
+  "{"
+  "}"
+] @punctuation.bracket
+
+[
+  "="
+  "-"
+  "*"
+  "/"
+  "+"
+  "%"
+  "~"
+  "|"
+  "&"
+  "^"
+  "<<"
+  ">>"
+  "->"
+  "<"
+  "<="
+  ">="
+  ">"
+  "=="
+  "!="
+  "!"
+  "&&"
+  "||"
+  "-="
+  "+="
+  "*="
+  "/="
+  "%="
+  "|="
+  "&="
+  "^="
+  ">>="
+  "<<="
+  "--"
+  "++"
+] @operator
+
+; Make sure the comma operator is given a highlight group after the comma
+; punctuator so the operator is highlighted properly.
+(comma_expression
+  "," @operator)
+
+[
+  (true)
+  (false)
+] @boolean
+
+(conditional_expression
+  [
+    "?"
+    ":"
+  ] @keyword.conditional.ternary)
+
+(string_literal) @string
+
+(system_lib_string) @string
+
+(escape_sequence) @string.escape
+
+(null) @constant.builtin
+
+(number_literal) @number
+
+(char_literal) @character
+
+(preproc_defined) @function.macro
+
+((field_expression
+  (field_identifier) @property) @_parent
+  (#not-has-parent? @_parent template_method function_declarator call_expression))
+
+(field_designator) @property
+
+((field_identifier) @property
+  (#has-ancestor? @property field_declaration)
+  (#not-has-ancestor? @property function_declarator))
+
+(statement_identifier) @label
+
+(declaration
+  type: (type_identifier) @_type
+  declarator: (identifier) @label
+  (#eq? @_type "__label__"))
+
+[
+  (type_identifier)
+  (type_descriptor)
+] @type
+
+(storage_class_specifier) @keyword.modifier
+
+[
+  (type_qualifier)
+  (gnu_asm_qualifier)
+  "__extension__"
+] @keyword.modifier
+
+(linkage_specification
+  "extern" @keyword.modifier)
+
+(type_definition
+  declarator: (type_identifier) @type.definition)
+
+(primitive_type) @type.builtin
+
+(sized_type_specifier
+  _ @type.builtin
+  type: _?)
+
+((identifier) @constant
+  (#lua-match? @constant "^[A-Z][A-Z0-9_]+$"))
+
+(preproc_def
+  (preproc_arg) @constant
+  (#lua-match? @constant "^[A-Z][A-Z0-9_]+$"))
+
+(enumerator
+  name: (identifier) @constant)
+
+(case_statement
+  value: (identifier) @constant)
+
+((identifier) @constant.builtin
+  ; format-ignore
+  (#any-of? @constant.builtin
+    "stderr" "stdin" "stdout"
+    "__FILE__" "__LINE__" "__DATE__" "__TIME__"
+    "__STDC__" "__STDC_VERSION__" "__STDC_HOSTED__"
+    "__cplusplus" "__OBJC__" "__ASSEMBLER__"
+    "__BASE_FILE__" "__FILE_NAME__" "__INCLUDE_LEVEL__"
+    "__TIMESTAMP__" "__clang__" "__clang_major__"
+    "__clang_minor__" "__clang_patchlevel__"
+    "__clang_version__" "__clang_literal_encoding__"
+    "__clang_wide_literal_encoding__"
+    "__FUNCTION__" "__func__" "__PRETTY_FUNCTION__"
+    "__VA_ARGS__" "__VA_OPT__"))
+
+(preproc_def
+  (preproc_arg) @constant.builtin
+  ; format-ignore
+  (#any-of? @constant.builtin
+    "stderr" "stdin" "stdout"
+    "__FILE__" "__LINE__" "__DATE__" "__TIME__"
+    "__STDC__" "__STDC_VERSION__" "__STDC_HOSTED__"
+    "__cplusplus" "__OBJC__" "__ASSEMBLER__"
+    "__BASE_FILE__" "__FILE_NAME__" "__INCLUDE_LEVEL__"
+    "__TIMESTAMP__" "__clang__" "__clang_major__"
+    "__clang_minor__" "__clang_patchlevel__"
+    "__clang_version__" "__clang_literal_encoding__"
+    "__clang_wide_literal_encoding__"
+    "__FUNCTION__" "__func__" "__PRETTY_FUNCTION__"
+    "__VA_ARGS__" "__VA_OPT__"))
+
+(attribute_specifier
+  (argument_list
+    (identifier) @variable.builtin))
+
+(attribute_specifier
+  (argument_list
+    (call_expression
+      function: (identifier) @variable.builtin)))
+
+((call_expression
+  function: (identifier) @function.builtin)
+  (#lua-match? @function.builtin "^__builtin_"))
+
+((call_expression
+  function: (identifier) @function.builtin)
+  (#has-ancestor? @function.builtin attribute_specifier))
+
+; Preproc def / undef
+(preproc_def
+  name: (_) @constant.macro)
+
+(preproc_call
+  directive: (preproc_directive) @_u
+  argument: (_) @constant.macro
+  (#eq? @_u "#undef"))
+
+(preproc_ifdef
+  name: (identifier) @constant.macro)
+
+(preproc_elifdef
+  name: (identifier) @constant.macro)
+
+(preproc_defined
+  (identifier) @constant.macro)
+
+(call_expression
+  function: (identifier) @function.call)
+
+(call_expression
+  function: (field_expression
+    field: (field_identifier) @function.call))
+
+(function_declarator
+  declarator: (identifier) @function)
+
+(function_declarator
+  declarator: (parenthesized_declarator
+    (pointer_declarator
+      declarator: (field_identifier) @function)))
+
+(preproc_function_def
+  name: (identifier) @function.macro)
+
+(comment) @comment @spell
+
+((comment) @comment.documentation
+  (#lua-match? @comment.documentation "^/[*][*][^*].*[*]/$"))
+
+; Parameters
+(parameter_declaration
+  declarator: (identifier) @variable.parameter)
+
+(parameter_declaration
+  declarator: (array_declarator) @variable.parameter)
+
+(parameter_declaration
+  declarator: (pointer_declarator) @variable.parameter)
+
+; K&R functions
+; To enable support for K&R functions,
+; add the following lines to your own query config and uncomment them.
+; They are commented out as they'll conflict with C++
+; Note that you'll need to have `; extends` at the top of your query file.
+;
+; (parameter_list (identifier) @variable.parameter)
+;
+; (function_definition
+;   declarator: _
+;   (declaration
+;     declarator: (identifier) @variable.parameter))
+;
+; (function_definition
+;   declarator: _
+;   (declaration
+;     declarator: (array_declarator) @variable.parameter))
+;
+; (function_definition
+;   declarator: _
+;   (declaration
+;     declarator: (pointer_declarator) @variable.parameter))
+(preproc_params
+  (identifier) @variable.parameter)
+
+[
+  "__attribute__"
+  "__declspec"
+  "__based"
+  "__cdecl"
+  "__clrcall"
+  "__stdcall"
+  "__fastcall"
+  "__thiscall"
+  "__vectorcall"
+  (ms_pointer_modifier)
+  (attribute_declaration)
+] @attribute

package/assets/grammars/cpp/highlights.scm

@@ -0,0 +1,74 @@
+; Functions
+
+(call_expression
+  function: (qualified_identifier
+    name: (identifier) @function))
+
+(template_function
+  name: (identifier) @function)
+
+(template_method
+  name: (field_identifier) @function)
+
+(template_function
+  name: (identifier) @function)
+
+(function_declarator
+  declarator: (qualified_identifier
+    name: (identifier) @function))
+
+(function_declarator
+  declarator: (qualified_identifier
+    name: (identifier) @function))
+
+(function_declarator
+  declarator: (field_identifier) @function)
+
+; Types
+
+((namespace_identifier) @type
+ (#match? @type "^[A-Z]"))
+
+(auto) @type
+
+; Constants
+
+(this) @variable.builtin
+(null "nullptr" @constant)
+
+; Keywords
+
+[
+ "catch"
+ "class"
+ "co_await"
+ "co_return"
+ "co_yield"
+ "constexpr"
+ "constinit"
+ "consteval"
+ "delete"
+ "explicit"
+ "final"
+ "friend"
+ "mutable"
+ "namespace"
+ "noexcept"
+ "new"
+ "override"
+ "private"
+ "protected"
+ "public"
+ "template"
+ "throw"
+ "try"
+ "typename"
+ "using"
+ "virtual"
+ "concept"
+ "requires"
+] @keyword
+
+; Strings
+
+(raw_string_literal) @string