@agent-native/core 0.2.7 → 0.3.1

package/src/templates/default/AGENTS.md

@@ -1,69 +1,86 @@
-# {{APP_NAME}} — Agent-Native App
-
-## Architecture
-
-This is an **@agent-native/core** application — the AI agent and UI share state through files, not a traditional database.
-
-### Core Principles
-
-1. **Files as database** — All app state lives in files. Both UI and agent read/write the same files.
-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.
-5. **Agent can update code** — The agent can modify this app's source code directly.
-
-### Directory Structure
-
-```
-client/          # React frontend (Vite SPA)
-  App.tsx        # Entry point
-  components/    # UI components
-  hooks/         # React hooks
-  lib/           # Utilities (cn, etc)
-
-server/          # Express backend
-  index.ts       # createAppServer() — routes + middleware
-  node-build.ts  # Production entry point
-
-shared/          # Isomorphic code (imported by both client & server)
-
-scripts/         # Agent-callable scripts
-  run.ts         # Script dispatcher
-  *.ts           # Individual scripts (pnpm script <name>)
-
-data/            # App data files (watched by SSE)
-
-.agents/skills/  # Agent skills — detailed guidance for each rule
-```
-
-Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
-
-### Key Patterns
-
-**Adding an API route:**
-Edit `server/index.ts`, add your route to `createAppServer()`.
-
-**Adding a script:**
-Create `scripts/my-script.ts` exporting `default async function(args: string[])`.
-Run with: `pnpm script my-script --arg value`
-
-**Sending to agent chat from UI:**
-```ts
-import { sendToAgentChat } from "@agent-native/core";
-sendToAgentChat({ message: "Generate something", context: "...", submit: true });
-```
-
-**Sending to agent chat from scripts:**
-```ts
-import { agentChat } from "@agent-native/core";
-agentChat.submit("Generate something");
-```
-
-### Tech Stack
-
-- **Framework:** @agent-native/core
-- **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
-- **Backend:** Express 5
-- **State:** File-based (SSE for real-time updates)
-- **Build:** `pnpm build` (client SPA + server bundle)
-- **Dev:** `pnpm dev` (Vite dev server with Express middleware)
+# {{APP_NAME}} — Agent-Native App
+
+## Architecture
+
+This is an **@agent-native/core** application — the AI agent and UI share state through files, not a traditional database.
+
+### Core Principles
+
+1. **Files as database** — All app state lives in files. Both UI and agent read/write the same files.
+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.
+5. **Agent can update code** — The agent can modify this app's source code directly.
+
+### Directory Structure
+
+```
+client/          # React frontend (Vite SPA)
+  App.tsx        # Entry point
+  components/    # UI components
+  hooks/         # React hooks
+  lib/           # Utilities (cn, etc)
+
+server/          # Express backend
+  index.ts       # createAppServer() — routes + middleware
+  node-build.ts  # Production entry point
+
+shared/          # Isomorphic code (imported by both client & server)
+
+scripts/         # Agent-callable scripts
+  run.ts         # Script dispatcher
+  *.ts           # Individual scripts (pnpm script <name>)
+
+data/            # App data files (watched by SSE)
+
+.agents/skills/  # Agent skills — detailed guidance for each rule
+```
+
+Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
+
+| Skill                 | When to read                                                   |
+| --------------------- | -------------------------------------------------------------- |
+| `files-as-database`   | 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                             |
+| `self-modifying-code` | Before editing source, components, or styles                   |
+| `frontend-design`     | Before building or restyling any UI component, page, or layout |
+
+The **`frontend-design`** skill (sourced from [Anthropic's skills library](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)) enforces distinctive, production-grade aesthetics — committing to a clear visual direction and avoiding generic patterns like purple gradients, overused fonts, and cookie-cutter layouts.
+
+### Key Patterns
+
+**Adding an API route:**
+Edit `server/index.ts`, add your route to `createAppServer()`.
+
+**Adding a script:**
+Create `scripts/my-script.ts` exporting `default async function(args: string[])`.
+Run with: `pnpm script my-script --arg value`
+
+**Sending to agent chat from UI:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+sendToAgentChat({
+  message: "Generate something",
+  context: "...",
+  submit: true,
+});
+```
+
+**Sending to agent chat from scripts:**
+
+```ts
+import { agentChat } from "@agent-native/core";
+agentChat.submit("Generate something");
+```
+
+### Tech Stack
+
+- **Framework:** @agent-native/core
+- **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
+- **Backend:** Express 5
+- **State:** File-based (SSE for real-time updates)
+- **Build:** `pnpm build` (client SPA + server bundle)
+- **Dev:** `pnpm dev` (Vite dev server with Express middleware)

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

@@ -1,54 +1,56 @@
-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>,
-);
+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>,
+);

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

@@ -1,72 +1,75 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --background: 240 6% 4%;
-    --foreground: 240 6% 93%;
-
-    --card: 240 5% 8%;
-    --card-foreground: 240 6% 93%;
-
-    --popover: 240 5% 10%;
-    --popover-foreground: 240 6% 93%;
-
-    --primary: 211 100% 64%;
-    --primary-foreground: 0 0% 0%;
-
-    --secondary: 240 4% 14%;
-    --secondary-foreground: 240 6% 93%;
-
-    --muted: 240 4% 14%;
-    --muted-foreground: 240 4% 55%;
-
-    --accent: 240 4% 14%;
-    --accent-foreground: 240 6% 93%;
-
-    --destructive: 0 72% 51%;
-    --destructive-foreground: 0 0% 100%;
-
-    --border: 240 4% 16%;
-    --input: 240 4% 16%;
-    --ring: 211 100% 64%;
-
-    --radius: 0.5rem;
-
-    --sidebar-background: 240 5% 6%;
-    --sidebar-foreground: 240 6% 93%;
-    --sidebar-primary: 211 100% 64%;
-    --sidebar-primary-foreground: 0 0% 0%;
-    --sidebar-accent: 240 4% 14%;
-    --sidebar-accent-foreground: 240 6% 93%;
-    --sidebar-border: 240 4% 16%;
-    --sidebar-ring: 211 100% 64%;
-  }
-}
-
-@layer base {
-  * {
-    @apply border-border;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-    font-family: system-ui, -apple-system, sans-serif;
-  }
-
-  ::-webkit-scrollbar {
-    width: 6px;
-    height: 6px;
-  }
-  ::-webkit-scrollbar-track {
-    background: transparent;
-  }
-  ::-webkit-scrollbar-thumb {
-    background: hsl(240 4% 20%);
-    border-radius: 3px;
-  }
-  ::-webkit-scrollbar-thumb:hover {
-    background: hsl(240 4% 28%);
-  }
-}
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 240 6% 4%;
+    --foreground: 240 6% 93%;
+
+    --card: 240 5% 8%;
+    --card-foreground: 240 6% 93%;
+
+    --popover: 240 5% 10%;
+    --popover-foreground: 240 6% 93%;
+
+    --primary: 211 100% 64%;
+    --primary-foreground: 0 0% 0%;
+
+    --secondary: 240 4% 14%;
+    --secondary-foreground: 240 6% 93%;
+
+    --muted: 240 4% 14%;
+    --muted-foreground: 240 4% 55%;
+
+    --accent: 240 4% 14%;
+    --accent-foreground: 240 6% 93%;
+
+    --destructive: 0 72% 51%;
+    --destructive-foreground: 0 0% 100%;
+
+    --border: 240 4% 16%;
+    --input: 240 4% 16%;
+    --ring: 211 100% 64%;
+
+    --radius: 0.5rem;
+
+    --sidebar-background: 240 5% 6%;
+    --sidebar-foreground: 240 6% 93%;
+    --sidebar-primary: 211 100% 64%;
+    --sidebar-primary-foreground: 0 0% 0%;
+    --sidebar-accent: 240 4% 14%;
+    --sidebar-accent-foreground: 240 6% 93%;
+    --sidebar-border: 240 4% 16%;
+    --sidebar-ring: 211 100% 64%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+    font-family:
+      system-ui,
+      -apple-system,
+      sans-serif;
+  }
+
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  ::-webkit-scrollbar-thumb {
+    background: hsl(240 4% 20%);
+    border-radius: 3px;
+  }
+  ::-webkit-scrollbar-thumb:hover {
+    background: hsl(240 4% 28%);
+  }
+}

package/src/templates/default/client/lib/utils.ts

@@ -1 +1 @@
-export { cn } from "@agent-native/core";
+export { cn } from "@agent-native/core";

package/src/templates/default/client/vite-env.d.ts

@@ -1 +1 @@
-/// <reference types="vite/client" />
+/// <reference types="vite/client" />

package/src/templates/default/components.json

@@ -1,20 +1,20 @@
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "default",
-  "rsc": false,
-  "tsx": true,
-  "tailwind": {
-    "config": "tailwind.config.ts",
-    "css": "client/global.css",
-    "baseColor": "slate",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  }
-}
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "client/global.css",
+    "baseColor": "slate",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/src/templates/default/index.html

@@ -1,14 +1,14 @@
-<!doctype html>
-<html lang="en" class="dark">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{{APP_TITLE}}</title>
-  </head>
-
-  <body>
-    <div id="root"></div>
-
-    <script type="module" src="/client/App.tsx"></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="en" class="dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+
+    <script type="module" src="/client/App.tsx"></script>
+  </body>
+</html>

package/src/templates/default/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "{{APP_NAME}}",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "agent-native dev",
-    "build": "agent-native build",
-    "start": "agent-native start",
-    "typecheck": "agent-native typecheck",
-    "script": "agent-native script"
-  },
-  "dependencies": {
-    "@agent-native/core": "^0.2.0",
-    "dotenv": "^17.2.1",
-    "express": "^5.1.0"
-  },
-  "devDependencies": {
-    "@tanstack/react-query": "^5.84.2",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.3",
-    "@types/node": "^24.2.1",
-    "@types/react": "^18.3.23",
-    "@types/react-dom": "^18.3.7",
-    "@vitejs/plugin-react-swc": "^4.0.0",
-    "autoprefixer": "^10.4.21",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "cors": "^2.8.5",
-    "lucide-react": "^0.539.0",
-    "postcss": "^8.5.6",
-    "prettier": "^3.6.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-router-dom": "^6.30.1",
-    "sonner": "^1.7.4",
-    "tailwind-merge": "^2.6.0",
-    "tailwindcss": "^3.4.17",
-    "tailwindcss-animate": "^1.0.7",
-    "tsx": "^4.20.3",
-    "typescript": "^5.9.2",
-    "vite": "^7.1.2"
-  }
-}
+{
+  "name": "{{APP_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "agent-native dev",
+    "build": "agent-native build",
+    "start": "agent-native start",
+    "typecheck": "agent-native typecheck",
+    "script": "agent-native script"
+  },
+  "dependencies": {
+    "@agent-native/core": "^0.2.0",
+    "dotenv": "^17.2.1",
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.84.2",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.2.1",
+    "@types/react": "^18.3.23",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react-swc": "^4.0.0",
+    "autoprefixer": "^10.4.21",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cors": "^2.8.5",
+    "lucide-react": "^0.539.0",
+    "postcss": "^8.5.6",
+    "prettier": "^3.6.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.1",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss": "^3.4.17",
+    "tailwindcss-animate": "^1.0.7",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.2"
+  }
+}

package/src/templates/default/postcss.config.js

@@ -1,6 +1,6 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-};
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

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

@@ -1,20 +1,20 @@
-/**
- * Example script — callable via `pnpm script hello`
- *
- * Scripts export a default async function that receives CLI args.
- */
-
-import { parseArgs } from "@agent-native/core";
-import { agentChat } from "@agent-native/core";
-
-export default async function hello(args: string[]) {
-  const parsed = parseArgs(args);
-  const name = parsed.name ?? "world";
-
-  console.log(`Hello, ${name}!`);
-
-  // Example: send a message to agent chat (works in Electron context)
-  if (parsed["send-chat"] === "true") {
-    agentChat.submit(`Hello from the script system! Name: ${name}`);
-  }
-}
+/**
+ * Example script — callable via `pnpm script hello`
+ *
+ * Scripts export a default async function that receives CLI args.
+ */
+
+import { parseArgs } from "@agent-native/core";
+import { agentChat } from "@agent-native/core";
+
+export default async function hello(args: string[]) {
+  const parsed = parseArgs(args);
+  const name = parsed.name ?? "world";
+
+  console.log(`Hello, ${name}!`);
+
+  // Example: send a message to agent chat (works in Electron context)
+  if (parsed["send-chat"] === "true") {
+    agentChat.submit(`Hello from the script system! Name: ${name}`);
+  }
+}

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

@@ -1,9 +1,9 @@
-#!/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";
-
-runScript();
+#!/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";
+
+runScript();