@akonwi/kit 0.1.0

package/README.md

@@ -0,0 +1,71 @@
+# kit
+
+Kit is a TUI coding agent heavily inspired by [Pi](https://pi.dev) and built on top of [`pi-agent-core`](https://github.com/badlogic/pi-mono/tree/main/packages/agent) with [OpenTUI](https://opentui.com/).
+
+## Requirements
+
+- [Bun](https://bun.sh) `>= 1.3.0`
+
+## Install
+
+From npm:
+
+```bash
+bun install --global @akonwi/kit
+```
+
+From a checkout:
+
+```bash
+bun install
+bun run build
+bun link
+```
+
+The packaged CLI uses the compiled binary as its non-development entry point.
+
+## Usage
+
+```bash
+kit              # resumes the most recent session for the current directory or starts a new one
+kit -s abc123    # opens a specific session by ID (long or short id)
+kit threads      # launches a session picker
+```
+
+## What Kit includes
+
+- terminal-first coding agent workflow
+- session restore and persistence
+- slash commands, prompt commands, and skills
+- settings UI and app-owned settings
+- code review tools and diff browser
+
+For feature details, see [`docs/features/`](docs/features/).
+
+## Development
+
+Commit messages in this repo should use [Conventional Commits](https://www.conventionalcommits.org/), preferably in the form `type(scope): summary`.
+
+Run from source:
+
+```bash
+bun run dev
+```
+
+Build the distributed binary:
+
+```bash
+bun run build
+```
+
+Preview the npm package contents:
+
+```bash
+bun run pack:dry
+```
+
+## More documentation
+
+- feature docs: [`docs/features/`](docs/features/)
+- ADRs: [`docs/adrs/`](docs/adrs/)
+- project guidance: [`AGENTS.md`](AGENTS.md)

package/dist/plugin.d.ts

@@ -0,0 +1,196 @@
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { Api, Model, Static, TSchema } from "@mariozechner/pi-ai";
+import type { JSX } from "solid-js";
+import type { ToastInput } from "./toasts";
+
+export type PluginSubscription = () => void;
+export type PluginDispose = () => void;
+
+export type PluginOverlaySurfaceProps = {
+	zIndex?: number;
+};
+
+export type PluginOverlayComponentProps<T> = {
+	done: (result: T) => void;
+	surfaceProps: PluginOverlaySurfaceProps;
+};
+
+export type PluginUI = {
+	toast: (toast: ToastInput) => void;
+	custom: <T>(
+		component: (props: PluginOverlayComponentProps<T>) => JSX.Element,
+	) => Promise<T>;
+	getTranscriptViewport: () => { width: number; height: number } | null;
+};
+
+export type PluginToolExecutionMode = "sequential" | "parallel";
+
+export type PluginToolResultContentBlock =
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string };
+
+export type PluginToolResult<TDetails = unknown> = {
+	content: PluginToolResultContentBlock[];
+	details: TDetails;
+	terminate?: boolean;
+};
+
+export type PluginToolUpdateCallback<TDetails = unknown> = (
+	partialResult: PluginToolResult<TDetails>,
+) => void;
+
+export type PluginToolDefinition<
+	TParameters extends TSchema = TSchema,
+	TDetails = unknown,
+> = {
+	name: string;
+	label?: string;
+	description: string;
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+	parameters: TParameters;
+	prepareArguments?: (args: unknown) => Static<TParameters>;
+	execute: (
+		toolCallId: string,
+		params: Static<TParameters>,
+		signal?: AbortSignal,
+		onUpdate?: PluginToolUpdateCallback<TDetails>,
+	) => Promise<PluginToolResult<TDetails>>;
+	executionMode?: PluginToolExecutionMode;
+};
+
+export type PluginLogger = {
+	log: (...args: unknown[]) => void;
+};
+
+export type PluginMessagePart = {
+	type: string;
+	[key: string]: unknown;
+};
+
+export type PluginSession = {
+	id: string;
+	cwd: string;
+	name?: string;
+	model?: string;
+	thinkingLevel?: string;
+	parentSessionId?: string;
+	forkedFromTurnId?: string;
+	createdAt?: string;
+	updatedAt?: string;
+	turns?: unknown[];
+	[key: string]: unknown;
+};
+
+export type PluginSessionAPI = {
+	get: () => PluginSession;
+	getMessages: () => AgentMessage[];
+	setName: (name: string) => Promise<void>;
+	submitMessage: (input: string | PluginMessagePart[]) => Promise<void>;
+	submitPromptCommandMessage: (
+		command: string,
+		args: string,
+		expandedPrompt: string,
+	) => Promise<void>;
+};
+
+export type PluginReviewDiffView = "unified" | "split";
+
+export type PluginSettings = {
+	theme?: string;
+	bells?: boolean;
+	speech?:
+		| boolean
+		| {
+				enabled?: boolean;
+				maxChars?: number;
+				voice?: string;
+		  };
+	pager?: boolean;
+	guidedQuestions?: boolean;
+	sessionNaming?: boolean;
+	diffs?: {
+		view?: PluginReviewDiffView;
+	};
+	retry?: {
+		enabled?: boolean;
+		maxRetries?: number;
+		baseDelayMs?: number;
+		maxDelayMs?: number;
+	};
+	[key: string]: unknown;
+};
+
+export type PluginSettingsAPI = {
+	get: () => PluginSettings;
+	update: (patch: Partial<PluginSettings>) => Promise<void>;
+};
+
+export type PluginModelAPI = {
+	getCurrent: () => Model<Api> | undefined;
+};
+
+export type PluginSystemAPI = {
+	readonly cwd: string;
+	open: (url: string | URL) => Promise<void>;
+};
+
+export type PluginEventContext = {
+	logger: PluginLogger;
+	ui: PluginUI;
+	session: PluginSessionAPI;
+	settings: PluginSettingsAPI;
+	model: PluginModelAPI;
+	system: PluginSystemAPI;
+};
+
+export type PluginCommandContext = PluginEventContext & {
+	args: string;
+};
+
+export type PluginCommandOptions = {
+	title?: string;
+	description?: string;
+	argName?: string;
+	category?: string;
+};
+
+export type PluginRuntimeEvent<Type extends string = string> = {
+	type: Type;
+} & Record<string, unknown>;
+
+export type PluginEventHandler<Type extends string = string> = (
+	event: PluginRuntimeEvent<Type>,
+	ctx: PluginEventContext,
+) => void | Promise<void>;
+
+export interface PluginAPI {
+	logger: PluginLogger;
+	ui: PluginUI;
+	session: PluginSessionAPI;
+	settings: PluginSettingsAPI;
+	model: PluginModelAPI;
+	system: PluginSystemAPI;
+	on(handler: PluginEventHandler): PluginSubscription;
+	on<Type extends string>(
+		type: Type,
+		handler: PluginEventHandler<Type>,
+	): PluginSubscription;
+	on<Prefix extends string>(
+		options: { prefix: Prefix },
+		handler: PluginEventHandler<`${Prefix}${string}`>,
+	): PluginSubscription;
+	registerCommand: (
+		id: string,
+		options: PluginCommandOptions,
+		handler: (ctx: PluginCommandContext) => void | Promise<void>,
+	) => PluginSubscription;
+	registerTool: <TParameters extends TSchema, TDetails>(
+		tool: PluginToolDefinition<TParameters, TDetails>,
+	) => PluginSubscription;
+	addSystemPrompt: (text: string) => PluginSubscription;
+	addDebugSection: (key: string, lines: string[]) => PluginSubscription;
+}
+
+// biome-ignore lint/suspicious/noConfusingVoidType: plugin definitions may omit a return value or return a disposer.
+export type PluginDefinition = (kit: PluginAPI) => void | PluginDispose;

package/dist/plugin.js

@@ -0,0 +1,3 @@
+// Runtime placeholder for the type-only @akonwi/kit/plugin SDK.
+// Use `import type` when consuming plugin API types.
+export {};

package/dist/runtime/assets/javascript/highlights.scm

@@ -0,0 +1,205 @@
+; Query from: https://raw.githubusercontent.com/tree-sitter/tree-sitter-javascript/refs/heads/master/queries/highlights.scm
+; Variables
+;----------
+
+(identifier) @variable
+
+; Properties
+;-----------
+
+(property_identifier) @property
+
+; Function and method definitions
+;--------------------------------
+
+(function_expression
+  name: (identifier) @function)
+(function_declaration
+  name: (identifier) @function)
+(method_definition
+  name: (property_identifier) @function.method)
+
+(pair
+  key: (property_identifier) @function.method
+  value: [(function_expression) (arrow_function)])
+
+(assignment_expression
+  left: (member_expression
+    property: (property_identifier) @function.method)
+  right: [(function_expression) (arrow_function)])
+
+(variable_declarator
+  name: (identifier) @function
+  value: [(function_expression) (arrow_function)])
+
+(assignment_expression
+  left: (identifier) @function
+  right: [(function_expression) (arrow_function)])
+
+; Function and method calls
+;--------------------------
+
+(call_expression
+  function: (identifier) @function)
+
+(call_expression
+  function: (member_expression
+    property: (property_identifier) @function.method))
+
+; Special identifiers
+;--------------------
+
+((identifier) @constructor
+ (#match? @constructor "^[A-Z]"))
+
+([
+    (identifier)
+    (shorthand_property_identifier)
+    (shorthand_property_identifier_pattern)
+ ] @constant
+ (#match? @constant "^[A-Z_][A-Z\\d_]+$"))
+
+((identifier) @variable.builtin
+ (#match? @variable.builtin "^(arguments|module|console|window|document)$")
+ (#is-not? local))
+
+((identifier) @function.builtin
+ (#eq? @function.builtin "require")
+ (#is-not? local))
+
+; Literals
+;---------
+
+(this) @variable.builtin
+(super) @variable.builtin
+
+[
+  (true)
+  (false)
+  (null)
+  (undefined)
+] @constant.builtin
+
+(comment) @comment
+
+[
+  (string)
+  (template_string)
+] @string
+
+(regex) @string.special
+(number) @number
+
+; Tokens
+;-------
+
+[
+  ";"
+  (optional_chain)
+  "."
+  ","
+] @punctuation.delimiter
+
+[
+  "-"
+  "--"
+  "-="
+  "+"
+  "++"
+  "+="
+  "*"
+  "*="
+  "**"
+  "**="
+  "/"
+  "/="
+  "%"
+  "%="
+  "<"
+  "<="
+  "<<"
+  "<<="
+  "="
+  "=="
+  "==="
+  "!"
+  "!="
+  "!=="
+  "=>"
+  ">"
+  ">="
+  ">>"
+  ">>="
+  ">>>"
+  ">>>="
+  "~"
+  "^"
+  "&"
+  "|"
+  "^="
+  "&="
+  "|="
+  "&&"
+  "||"
+  "??"
+  "&&="
+  "||="
+  "??="
+] @operator
+
+[
+  "("
+  ")"
+  "["
+  "]"
+  "{"
+  "}"
+]  @punctuation.bracket
+
+(template_substitution
+  "${" @punctuation.special
+  "}" @punctuation.special) @embedded
+
+[
+  "as"
+  "async"
+  "await"
+  "break"
+  "case"
+  "catch"
+  "class"
+  "const"
+  "continue"
+  "debugger"
+  "default"
+  "delete"
+  "do"
+  "else"
+  "export"
+  "extends"
+  "finally"
+  "for"
+  "from"
+  "function"
+  "get"
+  "if"
+  "import"
+  "in"
+  "instanceof"
+  "let"
+  "new"
+  "of"
+  "return"
+  "set"
+  "static"
+  "switch"
+  "target"
+  "throw"
+  "try"
+  "typeof"
+  "var"
+  "void"
+  "while"
+  "with"
+  "yield"
+] @keyword

package/dist/runtime/assets/markdown/highlights.scm

@@ -0,0 +1,150 @@
+; Query from: https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/refs/heads/master/queries/markdown/highlights.scm
+;From MDeiml/tree-sitter-markdown & Helix
+(setext_heading
+  (paragraph) @markup.heading.1
+  (setext_h1_underline) @markup.heading.1)
+
+(setext_heading
+  (paragraph) @markup.heading.2
+  (setext_h2_underline) @markup.heading.2)
+
+; Capture the entire heading node first based on the marker it contains
+((atx_heading (atx_h1_marker)) @markup.heading.1
+  (#set! priority 90))
+
+((atx_heading (atx_h2_marker)) @markup.heading.2
+  (#set! priority 90))
+
+((atx_heading (atx_h3_marker)) @markup.heading.3
+  (#set! priority 90))
+
+((atx_heading (atx_h4_marker)) @markup.heading.4
+  (#set! priority 90))
+
+((atx_heading (atx_h5_marker)) @markup.heading.5
+  (#set! priority 90))
+
+((atx_heading (atx_h6_marker)) @markup.heading.6
+  (#set! priority 90))
+
+; Then capture and conceal just the markers (they don't need special styling)
+(atx_heading
+  (atx_h1_marker) @conceal
+  (#set! conceal ""))
+
+(atx_heading
+  (atx_h2_marker) @conceal
+  (#set! conceal ""))
+
+(atx_heading
+  (atx_h3_marker) @conceal
+  (#set! conceal ""))
+
+(atx_heading
+  (atx_h4_marker) @conceal
+  (#set! conceal ""))
+
+(atx_heading
+  (atx_h5_marker) @conceal
+  (#set! conceal ""))
+
+(atx_heading
+  (atx_h6_marker) @conceal
+  (#set! conceal ""))
+
+(info_string) @label
+
+(pipe_table_header
+  (pipe_table_cell) @markup.heading)
+
+(pipe_table_header
+  "|" @punctuation.special)
+
+(pipe_table_row
+  "|" @punctuation.special)
+
+(pipe_table_delimiter_row
+  "|" @punctuation.special)
+
+(pipe_table_delimiter_cell) @punctuation.special
+
+; Code blocks (conceal backticks and language annotation)
+(indented_code_block) @markup.raw.block
+
+((fenced_code_block) @markup.raw.block
+  (#set! priority 90))
+
+(fenced_code_block
+  (fenced_code_block_delimiter) @markup.raw.block
+  (#set! conceal "")
+  (#set! conceal_lines ""))
+
+(fenced_code_block
+  (info_string
+    (language) @label
+    (#set! conceal "")
+    (#set! conceal_lines "")))
+
+(link_destination) @markup.link.url
+
+[
+  (link_title)
+  (link_label)
+] @markup.link.label
+
+((link_label)
+  .
+  ":" @punctuation.delimiter)
+
+[
+  (list_marker_plus)
+  (list_marker_minus)
+  (list_marker_star)
+  (list_marker_dot)
+  (list_marker_parenthesis)
+] @markup.list
+
+; NOTE: The following has been commented out due to issues with spaces in the
+; list marker nodes generated by the parser. If those spaces ever get captured
+; by a different node (e.g. block_continuation) we can safely re-add these
+; conceals.
+; ;; Conceal bullet points
+; ([(list_marker_plus) (list_marker_star)]
+;   @punctuation.special
+;   (#offset! @punctuation.special 0 0 0 -1)
+;   (#set! conceal "•"))
+; ([(list_marker_plus) (list_marker_star)]
+;   @punctuation.special
+;   (#any-of? @punctuation.special "+" "*")
+;   (#set! conceal "•"))
+; ((list_marker_minus)
+;   @punctuation.special
+;   (#offset! @punctuation.special 0 0 0 -1)
+;   (#set! conceal "—"))
+; ((list_marker_minus)
+;   @punctuation.special
+;   (#eq? @punctuation.special "-")
+;   (#set! conceal "—"))
+(thematic_break) @punctuation.special
+
+(task_list_marker_unchecked) @markup.list.unchecked
+
+(task_list_marker_checked) @markup.list.checked
+
+((block_quote) @markup.quote
+  (#set! priority 90))
+
+([
+  (plus_metadata)
+  (minus_metadata)
+] @keyword.directive
+  (#set! priority 90))
+
+[
+  (block_continuation)
+  (block_quote_marker)
+] @punctuation.special
+
+(backslash_escape) @string.escape
+
+(inline) @spell

package/dist/runtime/assets/markdown/injections.scm

@@ -0,0 +1,27 @@
+; Query from: https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/refs/heads/master/queries/markdown/injections.scm
+(fenced_code_block
+  (info_string
+    (language) @_lang)
+  (code_fence_content) @injection.content
+  (#set-lang-from-info-string! @_lang))
+
+((html_block) @injection.content
+  (#set! injection.language "html")
+  (#set! injection.combined)
+  (#set! injection.include-children))
+
+((minus_metadata) @injection.content
+  (#set! injection.language "yaml")
+  (#offset! @injection.content 1 0 -1 0)
+  (#set! injection.include-children))
+
+((plus_metadata) @injection.content
+  (#set! injection.language "toml")
+  (#offset! @injection.content 1 0 -1 0)
+  (#set! injection.include-children))
+
+([
+  (inline)
+  (pipe_table_cell)
+] @injection.content
+  (#set! injection.language "markdown_inline"))