@akonwi/kit 0.1.0

package/dist/toasts.d.ts

@@ -0,0 +1,12 @@
+export type ToastVariant = "error" | "warning" | "info";
+
+export type ToastInput = {
+	variant: ToastVariant;
+	title: string;
+	lines: string[];
+	persistent?: boolean;
+};
+
+export type Toast = ToastInput & {
+	id: number;
+};

package/docs/README.md

@@ -0,0 +1,14 @@
+# Docs
+
+This directory contains project documentation for Kit.
+
+## Structure
+
+- `adrs/` — architecture and design decision records
+- `features/` — feature-specific behavior, UX, and implementation notes
+
+## Conventions
+
+- Put durable architecture and design decisions in `adrs/`.
+- Put user- or feature-facing behavior docs in `features/`.
+- Capture important decisions in docs instead of leaving them only in chat history.

package/docs/features/plugins.md

@@ -0,0 +1,70 @@
+# Plugins
+
+Kit can load trusted TypeScript plugins that extend the app through the public `PluginAPI` capability surface.
+
+## Locations
+
+Kit loads plugins from Kit-specific directories only:
+
+1. user plugins: `~/.kit/plugins/*.ts`
+2. project plugins: `.kit/plugins/*.ts`
+
+Discovery is non-recursive. Only direct `.ts` files in those directories are loaded.
+
+Project plugins load after user plugins. Built-in plugins load before both.
+
+If an external plugin registers a command, tool, or debug section that already exists, Kit treats that as a plugin failure and reports it with a persistent toast.
+
+Kit does **not** load plugins from `.agents/plugins/`. Plugins execute code and are Kit-specific functionality, while `.agents/` is reserved for compatibility-oriented resources such as prompts, skills, and MCP config.
+
+## Trust model
+
+Plugins execute local code in the Kit process. Only use plugins from people and projects you trust.
+
+A failed user/project plugin does not stop Kit from starting. Kit shows a persistent toast with the plugin file and error. Dismiss it manually after reviewing the failure.
+
+## Writing a plugin
+
+A plugin is a TypeScript file with a default function export. Import public SDK types from `@akonwi/kit/plugin`; do not import from Kit source paths such as `src/plugins`.
+
+```ts
+import type { PluginAPI } from "@akonwi/kit/plugin";
+
+export default function MyPlugin(kit: PluginAPI) {
+	kit.registerCommand(
+		"hello-plugin",
+		{ description: "Show a greeting from a plugin" },
+		async (ctx) => {
+			ctx.ui.toast({
+				title: "Hello plugin",
+				lines: ["Loaded from a Kit plugin."],
+				variant: "info",
+			});
+		},
+	);
+}
+```
+
+Plugin functions may return a disposer for resources not registered through Kit:
+
+```ts
+import type { PluginAPI } from "@akonwi/kit/plugin";
+
+export default function WatchPlugin(kit: PluginAPI) {
+	const timer = setInterval(() => {
+		kit.logger.log("tick");
+	}, 1000);
+
+	return () => clearInterval(timer);
+}
+```
+
+Registrations made through `kit` are cleaned up automatically on `/reload`.
+
+## Reloading
+
+Use `/reload` after editing plugin files. Kit re-discovers plugin files and reloads them with cache busting so changed `.ts` contents are picked up.
+
+Plugin modules are loaded synchronously, so top-level `await` is not supported in plugin files. Async command, event, and tool handlers are supported.
+
+`@akonwi/kit/plugin` is a type-only SDK surface in v1. Use `import type`; value imports from `@akonwi/kit/plugin` are not part of the public runtime API.

package/package.json

@@ -0,0 +1,72 @@
+{
+	"name": "@akonwi/kit",
+	"version": "0.1.0",
+	"author": "Akonwi Ngoh <akonwi@gmail.com>",
+	"description": "Standalone kit app with Pi-core compatibility and a custom terminal shell.",
+	"license": "MIT",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/akonwi/kit.git"
+	},
+	"homepage": "https://github.com/akonwi/kit#readme",
+	"bugs": {
+		"url": "https://github.com/akonwi/kit/issues"
+	},
+	"bin": {
+		"kit": "dist/kit"
+	},
+	"exports": {
+		"./plugin": {
+			"types": "./dist/plugin.d.ts",
+			"default": "./dist/plugin.js"
+		}
+	},
+	"typesVersions": {
+		"*": {
+			"plugin": [
+				"dist/plugin.d.ts"
+			]
+		}
+	},
+	"files": [
+		"dist/",
+		"docs/features/plugins.md",
+		"README.md"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"check": "biome check --write .",
+		"lint:staged": "biome check --write --staged --unsafe .",
+		"dev": "bun --preload=@opentui/solid/preload src/app/main.tsx",
+		"start": "bun --preload=@opentui/solid/preload src/app/main.tsx",
+		"build": "bun run script/build.ts",
+		"pack:dry": "npm pack --dry-run",
+		"prepack": "bun run build",
+		"prepublishOnly": "bun run typecheck && bun test",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@mariozechner/pi-agent-core": "^0.73.0",
+		"@mariozechner/pi-ai": "^0.73.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@opentui/core": "0.2.2",
+		"@opentui/solid": "0.2.2",
+		"@pierre/diffs": "^1.1.16",
+		"glob": "^10.5.0",
+		"ignore": "^7.0.5",
+		"solid-js": "1.9.12",
+		"web-tree-sitter": "0.25.10",
+		"yaml": "^2.8.3"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"typescript": "^5.9.0"
+	},
+	"engines": {
+		"bun": ">=1.3.0"
+	}
+}