@alashi/cli 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alashi/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "alashi host: install, manage, and run Claude Code-powered apps",
   "type": "module",
   "license": "MIT",

package/templates/basic-app/AGENTS.md

@@ -0,0 +1,95 @@
+# Agent guide: __APP_NAME__ (an alashi app)
+
+This repo is an **alashi app**: one directory the [alashi](https://github.com/alashi-dev/alashi)
+host installs and runs. The default export of `index.mjs` is `defineApp({...})`
+from `@alashi/apps-sdk`. The full annotated guide lives in
+`node_modules/@alashi/apps-sdk/README.md`; exact types in
+`node_modules/@alashi/apps-sdk/dist/index.d.mts`. Read those before adding
+manifest surface — the schema is strict (unknown keys are rejected at install).
+
+## The contract (`defineApp` fields)
+
+Manifest (all optional except name/version):
+
+| Field | What it is |
+|---|---|
+| `name` | `^[a-z0-9][a-z0-9-]{0,63}$`; becomes `/app/<name>/` |
+| `version`, `description`, `sdkVersion` | semver; `sdkVersion` is an engines-style range checked at install |
+| `ui` | static assets dir (default `ui/`), served at `/app/<name>/` |
+| `instructions` | system prompt applied to **every** AI session the app opens |
+| `config` | declared user-facing keys: `{ description, label?, required?, secret?, default?, group? }` — rendered on the host settings page (`group` makes sections, `secret` masks, boolean defaults render checkboxes) |
+| `configDefaults` | lowest layer of the config merge (defaults < global < per-app user config) |
+| `mcpServers` | stdio (`{command, args?, env?}`) or remote (`{type: 'http'\|'sse', url, headers?}`); values may use `${config.*}` placeholders; `optional: true` = integration is absent until its config keys are set (app must degrade gracefully) |
+| `skills` | relative dirs each containing a `SKILL.md` the engine loads |
+| `agents` | named subagents: `{ description, prompt, model?, tools? }` |
+| `permissions.allowedTools` | tool allowlist, e.g. `mcp__grafana__*`; deny by default, never interactive |
+| `jobs` | `[{ name, schedule (cron), description? }]` — host runs them; every job needs a matching `jobHandlers[name]` |
+
+Beside the manifest: `routes` (fetch-style `(Request, ctx) => Response`) and
+`jobHandlers` (`{ [name]: (ctx) => Promise<void> }`).
+
+Known gap: `onInstall`/`onUpdate` exist in the SDK but the host never calls
+them — create DB schema lazily (`CREATE TABLE IF NOT EXISTS` on first open).
+
+## Runtime surface (`ctx`)
+
+- `ctx.dataDir` — the **only** writable directory. SQLite DB and files go
+  here (`node:sqlite` `DatabaseSync`). Treat the repo itself as read-only at
+  runtime.
+- `ctx.config` — merged config (readonly).
+- `ctx.state` — small key/value store; `ctx.logger` — log here, not console.
+- `ctx.ai.createSession()` — an agent session, pre-scoped by the host
+  (instructions, configured mcpServers, allowedTools, agents, skills,
+  cwd = dataDir). Works from routes **and** job handlers; chat is just one
+  caller. `session.send(text)` yields `AgentEvent`s:
+  `session | text | thinking | tool_use | tool_result | result (ok, costUsd, error)`.
+  Always `close()` in a `finally`. Resume with `createSession({ resume: id })`.
+- Persist **session id pointers only**, never transcripts — the engine owns
+  those (the host's history endpoint reads them back).
+
+## What the host already provides (do not rebuild)
+
+- `POST /api/apps/<name>/chat` — SSE chat turns (`x-conversation-id` header)
+- `GET/POST /api/apps/<name>/chat/conversations` — list; POST
+  `{sessionId, title?}` adopts an existing engine session as a conversation
+- `GET /api/apps/<name>/chat/<id>/history` — transcript view
+- `GET /api/apps/<name>/jobs`, `POST .../jobs/<name>/run` — job state + manual runs
+- `/settings/<name>` — generated settings page from declared `config`
+- **System UI, served not bundled**: `/assets/v1/system.css` (theme via
+  `:root { --accent: ... }` token overrides only) and `/assets/v1/chat.js` —
+  the `<alashi-chat>` web component (conversations, SSE streaming, safe
+  markdown incl. images, tool status, cost). Attributes: `app`,
+  `placeholder`. Methods: `adoptSession(sessionId, title?)`,
+  `openConversation(id)`, `newChat()`. Bubbling events: `alashi-chat:turn`
+  (`{ok, costUsd, error, conversationId}`), `alashi-chat:conversation`.
+  Never vendor or fork system UI; breaking changes ship as `/assets/v2/`.
+
+## App routes
+
+`routes` is mounted at `/app/<name>/api/*` (prefix stripped). Static files in
+`ui/` win; unmatched paths fall through to `routes`, so server-rendering works.
+
+## Conventions
+
+- Never `innerHTML` external or model-derived data in the UI — build DOM via
+  the `el()` helper / `textContent`. Markdown rendering belongs to
+  `<alashi-chat>`, which is escape-first.
+- Validate at boundaries (webhooks, user input): JSON only, cap body sizes,
+  4xx on garbage. Model output is a boundary too — parse defensively.
+- Secrets come from declared `config` keys (`secret: true`), referenced as
+  `${config.key}` in `mcpServers` env/headers. Never read them from env or
+  commit them.
+- AI calls from webhooks/routes should be fire-and-forget with error capture
+  (`void run().catch(...)`), status tracked in the app's DB.
+
+## Dev loop
+
+```sh
+npm install
+alashi install .   # local installs are symlinked in place
+alashi             # http://localhost:4141
+```
+
+UI edits are live on refresh. `index.mjs` changes need an `alashi` restart.
+The app's container lives at `~/.alashi/apps/<name>/` (`data/`, `config.json`);
+deleting that directory uninstalls it cleanly.

package/templates/basic-app/README.md

@@ -19,6 +19,7 @@ your changes are live.
 |---|---|
 | `index.mjs` | The app: manifest, API routes, job handlers |
 | `ui/index.html` | The web UI, served at `/app/__APP_NAME__/` |
+| `AGENTS.md` | The platform contract, written for coding agents working in this repo |
 
 Static files in `ui/` win; any path without a matching file falls through to
 your `routes` handler, so you can also server-render pages.