@agent-native/core 0.4.2 → 0.4.3

package/src/templates/default/AGENTS.md

@@ -2,14 +2,14 @@
 
 ## Architecture
 
-This is an **@agent-native/core** application — the AI agent and UI share state through files, not a traditional database.
+This is an **@agent-native/core** application — the AI agent and UI share state through a SQL database, with SSE for real-time sync.
 
 ### Core Principles
 
-1. **Files as database** — All app state lives in files. Both UI and agent read/write the same files.
+1. **Shared SQL database** — All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`.
 2. **All AI through agent chat** — No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Scripts for agent operations** — `pnpm script <name>` dispatches to callable script files in `scripts/`.
-4. **Bidirectional SSE events** — The file watcher keeps the UI in sync when the agent modifies files.
+4. **SSE for real-time sync** — Database writes emit events that keep the UI in sync automatically.
 5. **Agent can update code** — The agent can modify this app's source code directly.
 
 ### Authentication
@@ -25,7 +25,7 @@ Use `getSession(event)` server-side and `useSession()` client-side. See [docs/au
 ### Directory Structure
 
 ```
-client/                # React frontend
+app/                   # React frontend
   root.tsx             # HTML shell + global providers
   entry.client.tsx     # Client hydration entry
   routes.ts            # Route config — flatRoutes()
@@ -48,7 +48,7 @@ scripts/               # Agent-callable scripts
   run.ts               # Script dispatcher
   *.ts                 # Individual scripts (pnpm script <name>)
 
-data/                  # App data files (watched by SSE)
+data/                  # App data (SQLite DB file)
 
 react-router.config.ts # React Router framework config
 .agents/skills/        # Agent skills — detailed guidance for each rule
@@ -73,10 +73,10 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 | Skill                 | When to read                                                   |
 | --------------------- | -------------------------------------------------------------- |
-| `files-as-database`   | Before storing or reading any app state                        |
+| `storing-data`        | Before storing or reading any app state                        |
 | `delegate-to-agent`   | Before adding LLM calls or AI delegation                       |
 | `scripts`             | Before creating or modifying scripts                           |
-| `sse-file-watcher`    | Before wiring up real-time UI sync                             |
+| `real-time-sync`      | Before wiring up real-time UI sync                             |
 | `self-modifying-code` | Before editing source, components, or styles                   |
 | `frontend-design`     | Before building or restyling any UI component, page, or layout |
 
@@ -87,14 +87,14 @@ The **`frontend-design`** skill (sourced from [Anthropic's skills library](https
 **SSR-first framework, CSR-by-default content:** This app uses React Router v7 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). All real data fetching and rendering happens on the client via React Query hooks. Server-side data fetching is the exception — only used for public pages that need SEO/og tags.
 
 **Adding a page:**
-Create a file in `client/routes/`. The filename determines the URL path:
+Create a file in `app/routes/`. The filename determines the URL path:
 
 ```
-client/routes/_index.tsx              → /
-client/routes/settings.tsx            → /settings
-client/routes/inbox.tsx               → /inbox
-client/routes/inbox.$threadId.tsx     → /inbox/:threadId
-client/routes/$id.tsx                 → /:id (dynamic param)
+app/routes/_index.tsx              → /
+app/routes/settings.tsx            → /settings
+app/routes/inbox.tsx               → /inbox
+app/routes/inbox.$threadId.tsx     → /inbox/:threadId
+app/routes/$id.tsx                 → /:id (dynamic param)
 ```
 
 Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
@@ -135,7 +135,7 @@ server/routes/api/items/[id].patch.ts   → PATCH /api/items/:id
 Each file exports a default `defineEventHandler`.
 
 **Adding a server plugin:**
-Startup logic (file watcher, file sync, auth) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
+Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
 
 ```ts
 import { defineNitroPlugin } from "@agent-native/core";
@@ -147,14 +147,15 @@ export default defineNitroPlugin(async (nitroApp) => {
 
 **Key imports from `@agent-native/core`:**
 
-| Import                                       | Purpose                                           |
-| -------------------------------------------- | ------------------------------------------------- |
-| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)   |
-| `createFileWatcher`                          | Watch data directory for changes                  |
-| `createSSEHandler`                           | Create SSE endpoint for real-time updates         |
-| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)          |
-| `sendToAgentChat`                            | Send messages to agent from UI (client-side)      |
-| `agentChat`                                  | Send messages to agent from scripts (server-side) |
+| Import                                       | Purpose                                                                    |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
+| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
+| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
+| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
+| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
+| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
+| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
 
 **Adding a script:**
 Create `scripts/my-script.ts` exporting `default async function(args: string[])`.
@@ -178,42 +179,16 @@ import { agentChat } from "@agent-native/core";
 agentChat.submit("Generate something");
 ```
 
-### File Sync (Multi-User Collaboration)
+### Database (Cloud Deployment)
 
-File sync is **opt-in** — enabled when `FILE_SYNC_ENABLED=true` is set in `.env`.
+By default, data is stored in SQLite at `data/app.db`. For production/cloud deployment, set `DATABASE_URL` to point to a remote database (Turso, Neon, Supabase, D1).
 
 **Environment variables:**
 
-| Variable                         | Required      | Description                                          |
-| -------------------------------- | ------------- | ---------------------------------------------------- |
-| `FILE_SYNC_ENABLED`              | No            | Set to `"true"` to enable sync                       |
-| `FILE_SYNC_BACKEND`              | When enabled  | `"firestore"`, `"supabase"`, or `"convex"`           |
-| `SUPABASE_URL`                   | For Supabase  | Project URL                                          |
-| `SUPABASE_PUBLISHABLE_KEY`       | For Supabase  | Publishable key (or legacy `SUPABASE_ANON_KEY`)      |
-| `GOOGLE_APPLICATION_CREDENTIALS` | For Firestore | Path to service account JSON                         |
-| `CONVEX_URL`                     | For Convex    | Deployment URL from `npx convex dev` (must be HTTPS) |
-
-**How sync works:**
-
-- `createFileSync()` factory in `server/plugins/file-sync.ts` reads env vars and initializes sync
-- Files matching `sync-config.json` patterns are synced to/from the remote database
-- Sync events flow through SSE (`source: "sync"`) alongside file change events
-- Conflicts produce `.conflict` sidecar files and notify the agent
-
-**Checking sync status:**
-
-- Read `data/.sync-status.json` for current sync state (connected, conflicts, retry queue)
-- Read `data/.sync-failures.json` for permanently failed sync operations
-
-**Handling conflicts:**
-
-- When `application-state/sync-conflict.json` appears, a sync conflict needs resolution
-- Read the `.conflict` file alongside the original to understand both versions
-- Edit the original file to resolve, then delete the `.conflict` file
-
-**Scratch files (not synced):**
-
-- Prefix temporary files with `_tmp-` (e.g., `data/_tmp-scratch.json`) to exclude from sync
+| Variable              | Required         | Description                                                |
+| --------------------- | ---------------- | ---------------------------------------------------------- |
+| `DATABASE_URL`        | No (has default) | Database connection string (default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | For remote DBs   | Auth token for Turso or other remote databases             |
 
 ### Tech Stack
 
@@ -221,7 +196,7 @@ File sync is **opt-in** — enabled when `FILE_SYNC_ENABLED=true` is set in `.en
 - **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
 - **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
 - **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
-- **State:** File-based (SSE for real-time updates)
+- **State:** SQL-backed (SSE for real-time updates)
 - **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
 - **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
 - **Start:** `node .output/server/index.mjs` (production)

package/src/templates/default/app/global.css

@@ -0,0 +1,95 @@
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap");
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 220 10% 10%;
+    --card: 0 0% 100%;
+    --card-foreground: 220 10% 10%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 220 10% 10%;
+    --primary: 220 10% 15%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 10% 95%;
+    --secondary-foreground: 220 10% 15%;
+    --muted: 220 10% 95%;
+    --muted-foreground: 220 5% 45%;
+    --accent: 220 10% 95%;
+    --accent-foreground: 220 10% 15%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 220 10% 90%;
+    --input: 220 10% 90%;
+    --ring: 220 10% 40%;
+    --radius: 0.5rem;
+    --sidebar-background: 220 10% 97%;
+    --sidebar-foreground: 220 5% 45%;
+    --sidebar-primary: 220 10% 15%;
+    --sidebar-primary-foreground: 0 0% 100%;
+    --sidebar-accent: 220 10% 95%;
+    --sidebar-accent-foreground: 220 10% 15%;
+    --sidebar-border: 220 10% 90%;
+    --sidebar-ring: 220 10% 40%;
+  }
+
+  .dark {
+    --background: 220 6% 6%;
+    --foreground: 0 0% 90%;
+    --card: 220 5% 6%;
+    --card-foreground: 0 0% 90%;
+    --popover: 220 5% 6%;
+    --popover-foreground: 0 0% 90%;
+    --primary: 0 0% 75%;
+    --primary-foreground: 220 6% 6%;
+    --secondary: 220 4% 12%;
+    --secondary-foreground: 0 0% 90%;
+    --muted: 220 4% 10%;
+    --muted-foreground: 220 4% 50%;
+    --accent: 220 4% 13%;
+    --accent-foreground: 0 0% 90%;
+    --destructive: 0 63% 51%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 220 4% 14%;
+    --input: 220 4% 14%;
+    --ring: 0 0% 60%;
+    --radius: 0.5rem;
+    --sidebar-background: 220 6% 4%;
+    --sidebar-foreground: 220 4% 50%;
+    --sidebar-primary: 0 0% 75%;
+    --sidebar-primary-foreground: 220 6% 6%;
+    --sidebar-accent: 220 4% 10%;
+    --sidebar-accent-foreground: 0 0% 90%;
+    --sidebar-border: 220 4% 10%;
+    --sidebar-ring: 0 0% 60%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-family: "Inter", sans-serif;
+    font-feature-settings: "cv02", "cv03", "cv04", "cv11";
+  }
+}
+
+::-webkit-scrollbar {
+  width: 5px;
+  height: 5px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: hsl(var(--border));
+  border-radius: 3px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: hsl(var(--muted-foreground) / 0.4);
+}

package/src/templates/default/{client → app}/root.tsx

@@ -12,12 +12,14 @@ import {
   QueryClientProvider,
   useQueryClient,
 } from "@tanstack/react-query";
+import { ThemeProvider } from "next-themes";
 import { useFileWatcher } from "@agent-native/core";
+import { Toaster } from "sonner";
 import "./global.css";
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang="en" className="dark">
+    <html lang="en" suppressHydrationWarning>
       <head>
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -33,20 +35,27 @@ export function Layout({ children }: { children: React.ReactNode }) {
   );
 }
 
-function FileWatcher({ children }: { children: React.ReactNode }) {
+function FileWatcherSetup() {
   const qc = useQueryClient();
-  useFileWatcher({ queryClient: qc, queryKeys: ["files"] });
-  return <>{children}</>;
+  useFileWatcher({ queryClient: qc, queryKeys: ["files", "data"] });
+  return null;
 }
 
 export default function Root() {
   const [queryClient] = useState(() => new QueryClient());
   return (
-    <QueryClientProvider client={queryClient}>
-      <FileWatcher>
+    <ThemeProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      <QueryClientProvider client={queryClient}>
+        <FileWatcherSetup />
         <Outlet />
-      </FileWatcher>
-    </QueryClientProvider>
+        <Toaster />
+      </QueryClientProvider>
+    </ThemeProvider>
   );
 }
 
@@ -61,7 +70,11 @@ export function ErrorBoundary({ error }: { error: unknown }) {
       error.status === 404
         ? "The requested page could not be found."
         : error.statusText || details;
-  } else if (import.meta.env.DEV && error instanceof Error) {
+  } else if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV !== "production" &&
+    error instanceof Error
+  ) {
     details = error.message;
     stack = error.stack;
   }

package/src/templates/default/app/routes/_index.tsx

@@ -0,0 +1,62 @@
+import { useTheme } from "next-themes";
+
+export function meta() {
+  return [{ title: "{{APP_TITLE}}" }];
+}
+
+export function HydrateFallback() {
+  return (
+    <div className="flex items-center justify-center h-screen">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
+    </div>
+  );
+}
+
+export default function IndexPage() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen px-6">
+      <div className="max-w-md w-full space-y-8 text-center">
+        <div className="space-y-3">
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            Your app is running
+          </h1>
+          <p className="text-[14px] text-muted-foreground leading-relaxed">
+            Start building by editing{" "}
+            <code className="text-[13px] bg-muted px-1.5 py-0.5 rounded font-mono">
+              app/routes/_index.tsx
+            </code>
+          </p>
+        </div>
+
+        <div className="h-px bg-border" />
+
+        <div className="grid grid-cols-2 gap-3 text-left">
+          <a
+            href="https://agent-native.dev/docs"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              Documentation
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              Learn the framework
+            </p>
+          </a>
+          <button
+            onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+            className="rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors text-left"
+          >
+            <p className="text-[13px] font-medium text-foreground">Theme</p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              Toggle dark / light
+            </p>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/templates/default/components.json

@@ -5,7 +5,7 @@
   "tsx": true,
   "tailwind": {
     "config": "tailwind.config.ts",
-    "css": "client/global.css",
+    "css": "app/global.css",
     "baseColor": "slate",
     "cssVariables": true,
     "prefix": ""

package/src/templates/default/data/sync-config.json

@@ -0,0 +1 @@
+{ "patterns": ["data/**/*.json"] }

package/src/templates/default/package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@agent-native/core": "^0.4.1",
-    "dotenv": "^17.2.1",
+    "h3": "^1.13.0",
     "isbot": "^5"
   },
   "devDependencies": {
@@ -25,6 +25,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.539.0",
+    "next-themes": "^0.4.6",
     "postcss": "^8.5.6",
     "prettier": "^3.6.2",
     "react": "^18.3.1",

package/src/templates/default/react-router.config.ts

@@ -1,6 +1,6 @@
 import type { Config } from "@react-router/dev/config";
 
 export default {
-  appDirectory: "client",
+  appDirectory: "app",
   ssr: true,
 } satisfies Config;

package/src/templates/default/scripts/run.ts

@@ -1,9 +1,2 @@
-#!/usr/bin/env tsx
-/**
- * Script dispatcher — runs any script in the scripts/ folder.
- * Usage: pnpm script <script-name> [--args]
- */
-
-import { runScript } from "@agent-native/core";
-
+import { runScript } from "@agent-native/core/scripts";
 runScript();

package/src/templates/default/server/plugins/agent-chat.ts

@@ -0,0 +1 @@
+export { defaultAgentChatPlugin as default } from "@agent-native/core/server";

package/src/templates/default/server/plugins/auth.ts

@@ -1,5 +1 @@
-import { defineNitroPlugin, autoMountAuth } from "@agent-native/core";
-
-export default defineNitroPlugin((nitroApp: any) => {
-  autoMountAuth(nitroApp.h3App);
-});
+export { defaultAuthPlugin as default } from "@agent-native/core/server";

package/src/templates/default/server/plugins/file-sync.ts

@@ -1,39 +1 @@
-import "dotenv/config";
-import fs from "fs";
-import { defineNitroPlugin } from "@agent-native/core";
-import { createFileSync } from "@agent-native/core/adapters/sync";
-import { setSyncResult } from "../lib/watcher";
-
-export default defineNitroPlugin(async () => {
-  const result = await createFileSync({ contentRoot: "./data" });
-  setSyncResult(result);
-
-  if (result.status === "error") {
-    console.warn(`[app] File sync failed: ${result.reason}`);
-  }
-
-  // Graceful shutdown
-  process.on("SIGTERM", async () => {
-    if (result.status === "ready") await result.shutdown();
-    process.exit(0);
-  });
-
-  // Notify agent of sync conflicts
-  if (result.status === "ready") {
-    result.fileSync.syncEvents.on("sync", (event: any) => {
-      try {
-        if (event.type === "conflict-needs-llm") {
-          fs.mkdirSync("application-state", { recursive: true });
-          fs.writeFileSync(
-            "application-state/sync-conflict.json",
-            JSON.stringify(event, null, 2),
-          );
-        } else if (event.type === "conflict-resolved") {
-          fs.rmSync("application-state/sync-conflict.json", { force: true });
-        }
-      } catch {
-        /* best-effort */
-      }
-    });
-  }
-});
+export { defaultFileSyncPlugin as default } from "@agent-native/core/server";

package/src/templates/default/server/plugins/terminal.ts

@@ -0,0 +1 @@
+export { defaultTerminalPlugin as default } from "@agent-native/core/server";

package/src/templates/default/server/routes/api/events.get.ts

@@ -1,7 +1,3 @@
-import { createSSEHandler } from "@agent-native/core";
-import { watcher, sseExtraEmitters } from "../../lib/watcher";
+import { createDefaultSSEHandler } from "@agent-native/core/server";
 
-export default createSSEHandler(watcher, {
-  extraEmitters: sseExtraEmitters,
-  contentRoot: "./data",
-});
+export default createDefaultSSEHandler();

package/src/templates/default/server/routes/api/file-sync/status.get.ts

@@ -1,13 +1,4 @@
 import { defineEventHandler } from "h3";
-import { syncResult } from "../../../lib/watcher";
+import { defaultSyncStatusHandler } from "@agent-native/core/server";
 
-export default defineEventHandler(() => {
-  if (syncResult.status !== "ready") {
-    return { enabled: false, conflicts: 0 };
-  }
-  return {
-    enabled: true,
-    connected: true,
-    conflicts: syncResult.fileSync.conflictCount,
-  };
-});
+export default defineEventHandler(() => defaultSyncStatusHandler());

package/src/templates/default/tailwind.config.ts

@@ -3,5 +3,5 @@ import preset from "@agent-native/core/tailwind";
 
 export default {
   presets: [preset],
-  content: ["./client/**/*.{ts,tsx}"],
+  content: ["./app/**/*.{ts,tsx}"],
 } satisfies Config;

package/src/templates/default/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "extends": "@agent-native/core/tsconfig.base.json",
   "include": [
-    "client/**/*",
+    "app/**/*",
     "server/**/*",
     "shared/**/*",
     "vite.config.ts",

package/tsconfig.base.json

@@ -27,13 +27,13 @@
     "rootDirs": [".", "./.react-router/types"],
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./client/*"],
+      "@/*": ["./app/*"],
       "@shared/*": ["./shared/*"]
     },
     "types": ["vite/client"]
   },
   "include": [
-    "client/**/*",
+    "app/**/*",
     "server/**/*",
     "shared/**/*",
     "vite.config.ts",

package/src/templates/default/client/App.tsx

@@ -1,56 +0,0 @@
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { useFileWatcher } from "@agent-native/core";
-import "./global.css";
-
-const queryClient = new QueryClient();
-
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <Main />
-    </QueryClientProvider>
-  );
-}
-
-function Main() {
-  useFileWatcher({ queryClient });
-
-  return (
-    <div className="min-h-screen bg-background text-foreground flex items-center justify-center">
-      <div className="text-center space-y-4">
-        <h1 className="text-4xl font-bold">Agent-Native App</h1>
-        <p className="text-muted-foreground">
-          Edit{" "}
-          <code className="bg-muted px-2 py-1 rounded">client/App.tsx</code> to
-          get started.
-        </p>
-        <p className="text-sm text-muted-foreground">
-          API health: <HealthCheck />
-        </p>
-      </div>
-    </div>
-  );
-}
-
-function HealthCheck() {
-  return (
-    <span
-      className="text-primary cursor-pointer hover:underline"
-      onClick={async () => {
-        const res = await fetch("/api/ping");
-        const data = await res.json();
-        alert(data.message);
-      }}
-    >
-      /api/ping
-    </span>
-  );
-}
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-);