webspresso 0.0.95 → 0.0.96

package/templates/skills/webspresso-usage/REFERENCE-kernel.md

@@ -1,93 +0,0 @@
-# Webspresso — application kernel (event bus, flows, views)
-
-This layer must **not** be confused with Express SSR. The package root **`createApp`** sets up file-based SSR; **`kernel.createApp`** is a lightweight in-process API with an event bus, optional view resolver, and flow registry.
-
-## Name clash
-
-| API | Purpose |
-|-----|---------|
-| `require('webspresso').createApp(...)` | SSR — `pages/`, Nunjucks, Express |
-| `require('webspresso').kernel.createApp(...)` | Kernel — `events`, `registerPlugin`, `registerFlow`, `view` |
-
-## Usage
-
-```javascript
-const { kernel } = require('webspresso');
-const app = kernel.createApp({
-  paths: {
-    appViews: './views', // optional app override root
-    themeViews: './themes/default',
-  },
-});
-```
-
-Module layout (source repo): [`core/kernel/`](../../../core/kernel/).
-
-## Event bus
-
-- **`events.dispatch(name, ctx)`** — Handlers for the same name run **sequentially** with `await`; `ctx` is mutable; errors stop the caller.
-- **`events.publish(name, ctx)`** — Handlers run concurrently via **`Promise.all`** (side effects / “after” events).
-- **`events.on(name, handler)`** / **`off`** — Subscribe / unsubscribe.
-- **`events.buildContext(payload, { source, requestId?, userId? })`** → `{ payload, meta: { source, createdAt, … } }`; `source`: `'orm' | 'auth' | 'route' | 'plugin' | 'system'`.
-
-Standalone bus: `kernel.createEventBus()`.
-
-## Simulated repository (ORM lifecycle)
-
-`kernel.BaseRepository` — in-memory store; events named by `resource`: `orm.<resource>.beforeCreate`, `afterCreate`, `beforeUpdate`, …
-
-Implementation: [`core/kernel/base-repository.js`](../../../core/kernel/base-repository.js).
-
-## Plugin shell
-
-```javascript
-const { kernel } = require('webspresso');
-const myPlugin = kernel.definePlugin({
-  name: 'my-plugin',
-  events(app) {
-    app.events.on('orm.post.afterCreate', async (ctx) => { /* ... */ });
-  },
-  views() {
-    return {
-      namespace: 'blog',
-      layouts: {},
-      pages: { home: '<h1>{{ title }}</h1>' },
-      partials: {},
-    };
-  },
-});
-app.registerPlugin(myPlugin);
-```
-
-## View resolver
-
-- Name shape: **`namespace::page`** (e.g. `blog::home`).
-- Resolution order: app file overrides → theme file overrides → inline plugin templates.
-- **`app.view.renderView('ns::id', data, { layout: 'ns::layoutName' })`**
-- **`app.view.renderPartial(...)`**
-- Minimal templates: `{{ field }}` interpolation.
-
-## Flow
-
-```javascript
-app.registerFlow(
-  kernel.defineFlow({
-    trigger: 'orm.post.afterCreate',
-    when: (ctx) => ctx.payload.record?.status === 'published',
-    actions: [async (ctx, kernApp) => { /* run in order */ }],
-  }),
-);
-```
-
-## Demo
-
-From the repo: `node core/kernel/run-demo.js` — plugin, flow, and view example.
-
-## When to read this file
-
-- Event-driven domain logic, “on afterCreate do X” automation.
-- When you want this minimal kernel instead of SSR routes or Knex ORM `ModelEvents` alone.
-
-Types: npm package **`index.d.ts`** (`kernel`, `KernelAppShell`, …).
-
-HTML section: **[`doc/index.html#application-kernel`](../../../doc/index.html#application-kernel)**.

package/templates/skills/webspresso-usage/SKILL.md

@@ -1,48 +0,0 @@
----
-name: webspresso-usage
-description: >-
-  Webspresso: SSR file routes (createApp), ORM, auth, plugins, CLI; plus optional in-process
-  kernel (kernel.createApp: event bus, flows, view resolver). Read REFERENCE-framework.md for
-  pages/api/ORM/auth; REFERENCE-kernel.md for kernel. Use in this repo or Webspresso apps.
----
-
-# Webspresso — agent skill (overview)
-
-There are **three** files in this folder; open the reference that matches the task.
-
-## Which file should I read?
-
-| Need | File | Notes |
-|------|------|-------|
-| `pages/`, `views/`, API, `load()`, hooks, i18n, `fsy` | [`REFERENCE-framework.md`](./REFERENCE-framework.md) | SSR **`createApp`** — the main framework. |
-| `createApp({ db })`, `ctx.db`, `defineModel`, migrations | [`REFERENCE-framework.md`](./REFERENCE-framework.md) § ORM | Knex ORM in `core/orm`. |
-| `createAuth`, `quickAuth`, `middleware: ['auth']` | [`REFERENCE-framework.md`](./REFERENCE-framework.md) § Auth | **`webspresso/core/auth`**. |
-| Admin, sitemap, upload, redirect, data-exchange plugins | [`REFERENCE-framework.md`](./REFERENCE-framework.md) § Plugins | Framework plugin API (`createApp({ plugins })`). |
-| Greenfield project, `webspresso new`, `dev`, `db:migrate`, `doctor` | [`REFERENCE-framework.md`](./REFERENCE-framework.md) § CLI | Full command table there. |
-| Event bus, `kernel.createApp`, `defineFlow`, `definePlugin`, simulated `BaseRepository`, namespaced minimal views | [`REFERENCE-kernel.md`](./REFERENCE-kernel.md) | **Not** SSR **`createApp`** — [`doc/index.html#application-kernel`](../../../doc/index.html#application-kernel). |
-| Long-form narrative, all options | [`README.md`](../../../README.md), [`doc/index.html`](../../../doc/index.html) | Single-page HTML docs. |
-| System structure, feature sets, C4 map | [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) | **Update when adding plugins, CLI commands, or extension points.** |
-
-## CLI cheat sheet
-
-| Command | Purpose |
-|---------|---------|
-| `webspresso new [name]` or `webspresso new .` | Scaffold a new app (Tailwind, i18n, optional DB). |
-| `webspresso new . --yes` | Non-interactive scaffold (CI / agents). |
-| `webspresso new . --yes -i` | Scaffold + install deps / CSS build. |
-| `webspresso dev` | Dev server (watch). |
-| `webspresso db:migrate` / `db:rollback` / `db:status` | ORM migrations. |
-| `webspresso doctor` | Environment / project sanity checks. |
-| `webspresso skill --preset webspresso` | Copies this skill bundle under `.agents/skills/webspresso-usage/` (`SKILL.md` + `REFERENCE-*.md`). |
-
-
-## When to use this skill
-
-- **`REFERENCE-framework.md`:** Routes, APIs, ORM, auth, plugins, i18n, hooks, client runtime (Alpine/swup), `setupRoutes`, 404 ordering.
-- **`REFERENCE-kernel.md`:** `kernel`, domain events, `dispatch` / `publish`, `registerFlow`, `definePlugin` inside the kernel.
-
-They are independent: most apps only need SSR **`createApp`**; the kernel is optional.
-
-## Architecture maintenance
-
-When you add or materially change a **plugin**, **CLI command**, **extension point**, or **request-pipeline rule**, update [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) (feature-set section + changelog).