@elyracode/stack-elyra-framework 0.9.18

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.9.18] - 2026-07-18
+
+### Added
+- Initial release: stack profile for Elyra Framework (Rust + Svelte 5 desktop apps). Ships a deep `elyra-framework` skill (commands, `Ctx`/container, typed bridge/codegen, `EventBus`, `Database`/`#[derive(Model)]`, `Cache`/`Storage`/`Queue` facades, the `elyra::ai` SDK, system integration, and the `rata` CLI) and a `/elyra-framework:info` command.

package/README.md

@@ -0,0 +1,26 @@
+# @elyracode/stack-elyra-framework
+
+Elyra stack profile for [Elyra Framework](https://github.com/kwhorne/elyra-framework) — a Rust + Svelte 5 framework for hyper-responsive desktop apps, with Laravel-inspired ergonomics (container, providers, middleware, a typed bridge) but compiled, binary, and without runtime overhead.
+
+Gives the agent deep, working knowledge of the framework's actual API: `#[command]` handlers, the `Ctx`/container, the typed MessagePack bridge (`rata codegen`), `EventBus`/`channel()`, `#[derive(Model)]` + the query builder, the `Cache`/`Storage`/`Queue` facades, the `elyra::ai` SDK, and the `rata` CLI workflow — so generated Rust and Svelte code matches the framework's real conventions instead of guessing at a generic Tauri-like API.
+
+## Detection
+
+Detected automatically by `/init` when a project has:
+- an `elyra.toml` config file (written by `rata new`), or
+- a `Cargo.toml` with `elyra` as a dependency
+
+## Installation
+
+```bash
+elyra install npm:@elyracode/stack-elyra-framework
+```
+
+## What's included
+
+- **`elyra-framework` skill**: architecture, the `#[command]` + middleware pipeline, `Ctx`/container/providers, the typed bridge (`rata codegen` → generated `api.*`), `EventBus`/`channel()`, `Database`/`#[derive(Model)]`/migrations, `Cache`/`Storage`/`Queue` facades, the `elyra::ai` SDK, system integration (dialogs, tray, shortcuts, updater), and the `rata` CLI workflow.
+- **`/elyra-framework:info`**: quick reference to the loaded skill.
+
+## Learn more
+
+Full documentation lives at [elyracode.com/framework](https://elyracode.com/framework).

package/extensions/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+
+export default function (elyra: ExtensionAPI) {
+	elyra.registerCommand("elyra-framework:info", {
+		description: "Show detected Elyra Framework information",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(
+				"Elyra Framework stack profile loaded. Skills: elyra-framework. Use /skill:elyra-framework for the full reference.",
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@elyracode/stack-elyra-framework",
+  "version": "0.9.18",
+  "description": "Elyra stack profile for Elyra Framework (Rust + Svelte 5 desktop apps, https://github.com/kwhorne/elyra-framework)",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "elyra-framework",
+    "rust",
+    "svelte",
+    "desktop",
+    "ratatosk"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/stack-elyra-framework"
+  },
+  "elyra": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/elyra-framework/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: elyra-framework
+description: Deep knowledge of Elyra Framework - a Rust + Svelte 5 framework for compiled, binary desktop apps with Laravel-inspired ergonomics. Use when working on Elyra Framework projects, #[command] handlers, the typed MessagePack bridge, EventBus/channel(), Database models, Cache/Storage/Queue facades, the elyra::ai SDK, or the rata CLI.
+---
+
+# Elyra Framework Reference
+
+Elyra Framework (crate: `elyra`, CLI: `rata`/Ratatosk) is a Rust + Svelte 5 framework for desktop apps. It brings Laravel's ergonomics — container, providers, middleware, a typed bridge — to a compiled, binary app with no runtime overhead (no Electron, no Node runtime bundled).
+
+Not to be confused with the Elyra coding agent itself (`@elyracode/coding-agent`) — this skill is about the separate Rust desktop framework of the same name, at https://github.com/kwhorne/elyra-framework, docs at elyracode.com/framework.
+
+## Architecture
+
+```
+elyra-framework/
+├── framework/   # crate: elyra        — App, Container/Ctx, Command, events, shell (tao+wry)
+├── macros/      # crate: elyra-macros — #[command] and #[derive(Model)]
+├── database/    # crate: elyra-db     — Database, migrations, models (GUI-free)
+├── ratatosk/    # crate: ratatosk     — the `rata` CLI
+├── runtime/     # npm: @elyra/runtime — invoke(), channel(), generated api.*
+└── example/     # crate: elyra-example — demo app / DX benchmark
+```
+
+The Rust side (root, Yggdrasil) talks to the Svelte side (crown) over **binary IPC**: MessagePack over an `elyra://localhost` custom protocol, not JSON over stdin/HTTP. `rata` is the CLI that runs messages up and down between the two — hence "Ratatosk," the squirrel of Norse myth.
+
+## Commands: the core request/response primitive
+
+A command is an async function annotated `#[command]`, dispatched through a middleware pipeline with dependency injection from the container:
+
+```rust
+use elyra::{command, commands, App, Ctx};
+
+#[command]
+async fn greet(_ctx: Ctx, name: String) -> String {
+    format!("Hello, {name}!")
+}
+
+fn main() -> elyra::Result<()> {
+    App::new()
+        .commands(commands![greet])
+        .assets(elyra::asset_resolver::<Assets>())
+        .run()
+}
+```
+
+Frontend calls it through the generated, typed facade (never hand-written fetch/JSON):
+
+```ts
+import { api } from "./bindings"; // generated by `rata codegen`
+const greeting = await api.greet("World"); // (name: string) => Promise<string>
+```
+
+Rules of thumb:
+- Register every command in `commands![...]` inside `App::new()`. An un-registered `#[command]` function is dead code the frontend can't call.
+- The first parameter is always `Ctx` (or a type resolvable from it) — the container-provided context, analogous to a Laravel controller's dependency-injected services.
+- Errors: return `Result<T, E>` where `E` implements the framework's error trait so failures surface as typed rejections on the frontend, not opaque strings.
+- After adding, removing, or changing the signature of a `#[command]` function, **always re-run `rata codegen`** before touching the frontend — the generated `api.*` facade and its TS types are the source of truth for what the frontend can call, and stale bindings are a common source of "why doesn't this compile" confusion.
+
+## The typed bridge (codegen)
+
+`rata codegen` inspects `#[command]` functions and any `specta`-derived types, then emits:
+- TypeScript types for every command's parameters and return type
+- A typed `api.*` facade in the frontend bindings file
+
+Never hand-author the bridge types or the `api.*` facade — they are generated output. If a type looks wrong on the frontend, fix the Rust type (often a missing `#[derive(specta::Type)]` or an unhandled enum variant) and re-run `rata codegen`, rather than patching the generated file.
+
+## Events: Rust → frontend push
+
+`EventBus` plus `channel()` lets Rust push data to the frontend without the frontend polling — batched per flush over a long-poll, so the UI thread never blocks:
+
+```rust
+// Rust: emit
+ctx.events().emit("progress", ProgressPayload { percent: 42 });
+```
+
+```ts
+// Svelte: subscribe
+import { channel } from "@elyra/runtime";
+const unlisten = await channel("progress", (payload) => {
+  progress = payload.percent;
+});
+```
+
+Use events for anything long-running or streaming (file operations, background jobs, AI SDK streaming responses) — commands are request/response and block the caller until they resolve; events are the push side.
+
+## Database: `Database`, `#[derive(Model)]`, migrations
+
+One `Database` abstraction over SQLite/MySQL/Postgres, with Active Record-style models:
+
+```rust
+use elyra_db::{derive::Model, Database};
+
+#[derive(Model)]
+#[model(table = "users")]
+struct User {
+    id: i64,
+    name: String,
+    email: String,
+}
+
+// Query builder + relations, Eloquent-flavored:
+let user = User::query().where_eq("email", &email).first(&db).await?;
+```
+
+- `rata migrate` runs migrations, mirroring `php artisan migrate`'s workflow.
+- `database` is a Cargo feature — enable it in `Cargo.toml` before `Database`/`#[derive(Model)]`/`App::database` are available.
+- The database layer (`elyra-db`) is GUI-free by design, so it can be tested and used headlessly (e.g. in a sidecar process) without pulling in `tao`/`wry`.
+
+## Shared facades: `Cache`, `Storage`, `Queue`
+
+Mirror the Askr/Laravel side's surface, over local backends — same ergonomics, different runtime:
+
+```rust
+Cache::put("key", value, Duration::from_secs(60)).await?;
+let value: Option<T> = Cache::get("key").await?;
+
+Storage::disk("local").put("path/file.txt", bytes).await?;
+
+Queue::push(SomeJob { ... }).await?;
+```
+
+Reach for these instead of hand-rolling a cache/queue/storage layer — they're the "one ecosystem, two worlds" pitch: the same facade shape whether you're on the Laravel/PHP side of a project or the Rust desktop side.
+
+## AI SDK (`elyra::ai`, feature `ai`)
+
+A Laravel-inspired AI SDK: agents, tools, sub-agents (`CanActAsTool`), structured output, streaming, provider tools, images, audio, embeddings, RAG, plus retries/failover/caching — over Anthropic and OpenAI.
+
+```rust
+use elyra::ai::{Agent, Tool};
+
+let agent = Agent::new("assistant")
+    .instructions("You are a helpful assistant.")
+    .tools(vec![my_tool]);
+
+let response = agent.run("What's the weather?").await?;
+```
+
+Requires the `ai` Cargo feature. Prefer streaming (events, not a blocking command) for chat-style UIs so the frontend can render tokens as they arrive instead of waiting for the full response.
+
+## System integration and UI components
+
+Behind feature flags, `App` exposes:
+- **`system`**: native dialogs, shell-open, clipboard, notifications, paths
+- **`tray`**: system tray
+- **`shortcuts`**: OS-level global keyboard shortcuts
+- **`updater`**: ed25519-verified auto-updater
+- Built-in UI: themed About dialog, auto-update toast, dialogs/toasts/⌘K command palette/context menu
+- Window control + file drop + state persistence, native app menu, a settings store, autostart, sidecar processes, single-instance + deep-linking
+
+```toml
+[dependencies]
+elyra = { version = "0.5", features = ["database", "tray", "updater", "system", "shortcuts"] }
+```
+
+Only enable the features a project actually uses — each one pulls in its own native bindings and increases binary size.
+
+## CLI workflow (`rata`)
+
+```bash
+rata new myapp                 # scaffold a new project (writes elyra.toml)
+cd myapp
+(cd app && npm install && npm run build)
+rata codegen                   # generate typed bindings from #[command]s
+cargo run                      # launch
+rata migrate                   # run database migrations (feature: database)
+```
+
+`elyra.toml` at the project root is the framework's own config file, written by `rata new` — its presence is the most reliable signal that a project uses Elyra Framework (more reliable than grepping `Cargo.toml`, which could reference the crate without the project having been scaffolded via `rata`).
+
+To try the framework itself without scaffolding a project:
+
+```bash
+cargo run -p elyra-example   # bundled demo app, no npm needed
+```
+
+## Working in an Elyra Framework project — checklist
+
+1. **New backend capability → `#[command]`.** Register it in `commands![...]`, run `rata codegen`, then wire the frontend against the generated `api.*` — never hand-write the IPC call.
+2. **Long-running/streaming work → `EventBus`/`channel()`**, not a command that blocks until done.
+3. **Persistent data → `Database`/`#[derive(Model)]`**, not ad-hoc file I/O — enable the `database` feature first.
+4. **Cross-cutting cache/storage/queue needs → the shared facades**, not a bespoke implementation.
+5. **After any change to a `#[command]` signature or a `specta`-derived type, re-run `rata codegen` before touching Svelte code.**
+6. **Only enable the Cargo features you need** (`database`, `tray`, `updater`, `system`, `shortcuts`, `ai`) — each has a real footprint.
+7. For deeper topics (window management specifics, the full `elyra::ai` API surface, migration syntax), point the user to elyracode.com/framework — this skill covers the architecture and the common patterns, not the exhaustive API reference.