@ysdk/create 0.1.0

package/dist/index.js

@@ -0,0 +1,647 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as path2 from "path";
+import * as fs2 from "fs";
+
+// src/scaffold.ts
+import * as fs from "fs";
+import * as path from "path";
+
+// src/templates.ts
+var TEMPLATES = {
+  basic: {
+    description: 'Simple shared counter - the "Hello World" of multiplayer',
+    appTsx: `import { useShared } from '@ysdk/react';
+
+export default function App() {
+  const [count, setCount] = useShared('count', 0);
+
+  return (
+    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40 }}>
+      <h1>Shared Counter</h1>
+      <p style={{ fontSize: 64, textAlign: 'center' }}>{count}</p>
+      <div style={{ display: 'flex', gap: 8, justifyContent: 'center' }}>
+        <button onClick={() => setCount(count - 1)}>-</button>
+        <button onClick={() => setCount(count + 1)}>+</button>
+        <button onClick={() => setCount(0)}>Reset</button>
+      </div>
+      <p style={{ textAlign: 'center', color: '#888', marginTop: 24 }}>
+        Open in another tab to see real-time sync
+      </p>
+    </div>
+  );
+}
+`
+  },
+  todo: {
+    description: "Collaborative to-do list with shared array",
+    appTsx: `import { useState } from 'react';
+import { useSharedArray, usePresence } from '@ysdk/react';
+
+interface Todo {
+  id: string;
+  text: string;
+  done: boolean;
+}
+
+export default function App() {
+  const [todos, ops] = useSharedArray<Todo>('todos');
+  const [input, setInput] = useState('');
+  const { peers, count } = usePresence({ name: 'User' });
+
+  const addTodo = () => {
+    if (!input.trim()) return;
+    ops.push({ id: crypto.randomUUID(), text: input.trim(), done: false });
+    setInput('');
+  };
+
+  const toggleTodo = (index: number) => {
+    const todo = todos[index];
+    ops.delete(index);
+    ops.insert(index, { ...todo, done: !todo.done });
+  };
+
+  const deleteTodo = (index: number) => {
+    ops.delete(index);
+  };
+
+  return (
+    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40 }}>
+      <h1>Shared To-Do List</h1>
+      <p style={{ color: '#888' }}>{count + 1} user(s) connected</p>
+
+      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyDown={(e) => e.key === 'Enter' && addTodo()}
+          placeholder="Add a task..."
+          style={{ flex: 1, padding: 8 }}
+        />
+        <button onClick={addTodo}>Add</button>
+      </div>
+
+      <ul style={{ listStyle: 'none', padding: 0 }}>
+        {todos.map((todo, i) => (
+          <li key={todo.id} style={{ display: 'flex', gap: 8, padding: '8px 0', borderBottom: '1px solid #eee' }}>
+            <input type="checkbox" checked={todo.done} onChange={() => toggleTodo(i)} />
+            <span style={{ flex: 1, textDecoration: todo.done ? 'line-through' : 'none', color: todo.done ? '#aaa' : '#000' }}>
+              {todo.text}
+            </span>
+            <button onClick={() => deleteTodo(i)} style={{ color: 'red', border: 'none', background: 'none', cursor: 'pointer' }}>x</button>
+          </li>
+        ))}
+      </ul>
+
+      {todos.length === 0 && <p style={{ textAlign: 'center', color: '#aaa' }}>No tasks yet</p>}
+    </div>
+  );
+}
+`
+  },
+  whiteboard: {
+    description: "Multiplayer drawing canvas with presence cursors",
+    appTsx: `import { useRef, useEffect, useState, useCallback } from 'react';
+import { useSharedArray, usePresence, useBroadcast } from '@ysdk/react';
+
+interface Point { x: number; y: number }
+interface Stroke { points: Point[]; color: string }
+
+export default function App() {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [strokes, ops] = useSharedArray<Stroke>('strokes');
+  const [drawing, setDrawing] = useState(false);
+  const [color, setColor] = useState('#000000');
+  const currentStroke = useRef<Point[]>([]);
+  const { peers, setPresence } = usePresence<{ name: string; cursor?: Point }>({ name: 'User' });
+  const { broadcast, onMessage } = useBroadcast<{ cursor: Point }>('cursor');
+
+  // Draw all strokes
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d')!;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+
+    for (const stroke of strokes) {
+      if (stroke.points.length < 2) continue;
+      ctx.beginPath();
+      ctx.strokeStyle = stroke.color;
+      ctx.lineWidth = 3;
+      ctx.lineCap = 'round';
+      ctx.lineJoin = 'round';
+      ctx.moveTo(stroke.points[0].x, stroke.points[0].y);
+      for (let i = 1; i < stroke.points.length; i++) {
+        ctx.lineTo(stroke.points[i].x, stroke.points[i].y);
+      }
+      ctx.stroke();
+    }
+  }, [strokes]);
+
+  const getPos = (e: React.MouseEvent): Point => {
+    const rect = canvasRef.current!.getBoundingClientRect();
+    return { x: e.clientX - rect.left, y: e.clientY - rect.top };
+  };
+
+  return (
+    <div style={{ fontFamily: 'system-ui', maxWidth: 640, margin: '0 auto', padding: 40 }}>
+      <h1>Shared Whiteboard</h1>
+      <div style={{ display: 'flex', gap: 8, marginBottom: 8 }}>
+        <input type="color" value={color} onChange={(e) => setColor(e.target.value)} />
+        <button onClick={() => ops.clear()}>Clear</button>
+        <span style={{ color: '#888', marginLeft: 'auto' }}>{peers.length + 1} connected</span>
+      </div>
+      <canvas
+        ref={canvasRef}
+        width={600}
+        height={400}
+        style={{ border: '1px solid #ccc', cursor: 'crosshair' }}
+        onMouseDown={(e) => {
+          setDrawing(true);
+          currentStroke.current = [getPos(e)];
+        }}
+        onMouseMove={(e) => {
+          const pos = getPos(e);
+          broadcast({ cursor: pos });
+          if (!drawing) return;
+          currentStroke.current.push(pos);
+          // Draw locally for smooth feel
+          const ctx = canvasRef.current!.getContext('2d')!;
+          const pts = currentStroke.current;
+          if (pts.length >= 2) {
+            ctx.beginPath();
+            ctx.strokeStyle = color;
+            ctx.lineWidth = 3;
+            ctx.lineCap = 'round';
+            ctx.moveTo(pts[pts.length - 2].x, pts[pts.length - 2].y);
+            ctx.lineTo(pts[pts.length - 1].x, pts[pts.length - 1].y);
+            ctx.stroke();
+          }
+        }}
+        onMouseUp={() => {
+          if (currentStroke.current.length > 1) {
+            ops.push({ points: currentStroke.current, color });
+          }
+          setDrawing(false);
+          currentStroke.current = [];
+        }}
+      />
+    </div>
+  );
+}
+`
+  },
+  chat: {
+    description: "Real-time chat room with presence",
+    appTsx: `import { useState, useRef, useEffect } from 'react';
+import { useSharedArray, usePresence } from '@ysdk/react';
+
+interface Message {
+  id: string;
+  user: string;
+  text: string;
+  time: number;
+}
+
+const COLORS = ['#e74c3c', '#3498db', '#2ecc71', '#f39c12', '#9b59b6', '#1abc9c'];
+
+export default function App() {
+  const [messages, ops] = useSharedArray<Message>('messages');
+  const [input, setInput] = useState('');
+  const [name, setName] = useState(() => 'User-' + Math.random().toString(36).slice(2, 5));
+  const { peers, setPresence, count } = usePresence<{ name: string; typing?: boolean }>({ name });
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages.length]);
+
+  const send = () => {
+    if (!input.trim()) return;
+    ops.push({ id: crypto.randomUUID(), user: name, text: input.trim(), time: Date.now() });
+    setInput('');
+    setPresence({ typing: false });
+  };
+
+  const colorFor = (user: string) => COLORS[Math.abs([...user].reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) % COLORS.length];
+  const typingPeers = peers.filter(p => p.typing).map(p => p.name);
+
+  return (
+    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40, display: 'flex', flexDirection: 'column', height: '100vh' }}>
+      <div style={{ display: 'flex', gap: 8, marginBottom: 16, alignItems: 'center' }}>
+        <h1 style={{ margin: 0, flex: 1 }}>Chat Room</h1>
+        <input
+          value={name}
+          onChange={(e) => { setName(e.target.value); setPresence({ name: e.target.value }); }}
+          style={{ width: 100, padding: 4 }}
+          placeholder="Your name"
+        />
+        <span style={{ color: '#888' }}>{count + 1} online</span>
+      </div>
+
+      <div style={{ flex: 1, overflowY: 'auto', border: '1px solid #eee', borderRadius: 8, padding: 12 }}>
+        {messages.map((msg) => (
+          <div key={msg.id} style={{ marginBottom: 8 }}>
+            <strong style={{ color: colorFor(msg.user) }}>{msg.user}</strong>
+            <span style={{ color: '#aaa', fontSize: 12, marginLeft: 8 }}>{new Date(msg.time).toLocaleTimeString()}</span>
+            <div>{msg.text}</div>
+          </div>
+        ))}
+        <div ref={bottomRef} />
+      </div>
+
+      {typingPeers.length > 0 && (
+        <div style={{ color: '#888', fontSize: 12, padding: 4 }}>
+          {typingPeers.join(', ')} {typingPeers.length === 1 ? 'is' : 'are'} typing...
+        </div>
+      )}
+
+      <div style={{ display: 'flex', gap: 8, marginTop: 8 }}>
+        <input
+          value={input}
+          onChange={(e) => { setInput(e.target.value); setPresence({ typing: e.target.value.length > 0 }); }}
+          onKeyDown={(e) => e.key === 'Enter' && send()}
+          placeholder="Type a message..."
+          style={{ flex: 1, padding: 8 }}
+        />
+        <button onClick={send}>Send</button>
+      </div>
+    </div>
+  );
+}
+`
+  }
+};
+function getTemplateNames() {
+  return Object.keys(TEMPLATES);
+}
+
+// src/claude-md.ts
+function generateClaudeMd(projectName2, room) {
+  return `# CLAUDE.md - ${projectName2}
+
+This is a collaborative React app powered by YSDK. You (Claude) are connected to the same multiplayer room as the browser via MCP tools.
+
+## How It Works
+
+The React app and Claude share the same Yjs CRDT document. When you call \`shared_set\`, the React app's \`useShared\` hook updates instantly. When the user changes state in the browser, you can read it with \`shared_get\`.
+
+**Room:** \`${room}\`
+
+---
+
+## MCP Tools Reference
+
+### Shared State (Y.Map)
+Maps to \`useShared(key, defaultValue)\` in React.
+
+| Tool | Description |
+|------|-------------|
+| \`shared_get(key)\` | Read a value. Returns the current value or "undefined". |
+| \`shared_set(key, value)\` | Write a value. All connected clients update instantly. Value can be any JSON type. |
+| \`shared_delete(key)\` | Remove a key from shared state. |
+| \`shared_keys()\` | List all keys in shared state. |
+
+**Example:**
+\`\`\`
+shared_set(key: "count", value: 42)  ->  useShared('count', 0) returns 42
+shared_get(key: "count")             ->  "42"
+\`\`\`
+
+**Important:** Objects are stored as opaque values (last-write-wins on the whole object). If two users set the same key simultaneously, one write wins. Use shared arrays for concurrent insertions.
+
+### Shared Arrays (Y.Array)
+Maps to \`useSharedArray(key)\` in React. Concurrent insertions merge cleanly (CRDT).
+
+| Tool | Description |
+|------|-------------|
+| \`array_get(key)\` | Read all items in the array. |
+| \`array_push(key, items)\` | Append items to the end. \`items\` is a JSON array. |
+| \`array_insert(key, index, items)\` | Insert items at a position. |
+| \`array_delete(key, index, count?)\` | Delete items starting at index. Count defaults to 1. |
+| \`array_clear(key)\` | Remove all items from the array. |
+
+**Example:**
+\`\`\`
+array_push(key: "todos", items: [{"id": "abc", "text": "Buy milk", "done": false}])
+array_get(key: "todos")  ->  [{"id": "abc", "text": "Buy milk", "done": false}]
+\`\`\`
+
+### Shared Text (Y.Text)
+Maps to \`useSharedText(key, defaultValue)\` in React. Character-by-character CRDT merge.
+
+| Tool | Description |
+|------|-------------|
+| \`text_get(key)\` | Read the text content. |
+| \`text_set(key, value)\` | Replace the entire text. |
+| \`text_insert(key, index, content)\` | Insert text at a character position. |
+| \`text_delete(key, index, length)\` | Delete characters starting at position. |
+
+### Presence & Broadcast
+
+| Tool | Description |
+|------|-------------|
+| \`presence_list()\` | List all connected users and their state. |
+| \`broadcast(channel, data)\` | Send ephemeral message to all clients. Received via \`useBroadcast(channel)\`. Not persisted. |
+
+### Utility
+
+| Tool | Description |
+|------|-------------|
+| \`room_info()\` | Connection status, sync status, client count, document size. |
+| \`document_snapshot()\` | Full dump of all shared data (maps, arrays, texts). |
+
+---
+
+## React Hooks Reference
+
+\`\`\`tsx
+import { YSDKProvider, useShared, useSharedArray, useSharedText, usePresence, useBroadcast } from '@ysdk/react';
+
+// Shared state (like useState but multiplayer)
+const [count, setCount] = useShared('count', 0);
+
+// Shared array (concurrent insertions merge)
+const [items, ops] = useSharedArray<Item>('items');
+ops.push(item);
+ops.delete(index, count?);
+ops.insert(index, item);
+ops.clear();
+
+// Shared text (character-level CRDT)
+const { value, setValue, ytext } = useSharedText('doc', 'initial');
+
+// Presence (who's online + ephemeral state)
+const { peers, setPresence, count } = usePresence<{ name: string }>({ name: 'User' });
+
+// Broadcast (fire-and-forget messages)
+const { broadcast, onMessage } = useBroadcast<T>('channel');
+broadcast(data);
+onMessage((data, senderId) => { ... });
+\`\`\`
+
+---
+
+## How MCP Maps to Hooks
+
+| MCP Tool | React Hook | What Happens |
+|----------|------------|-------------|
+| \`shared_set(key, val)\` | \`useShared(key)\` | Hook re-renders with new value |
+| \`array_push(key, items)\` | \`useSharedArray(key)\` | Hook re-renders with new array |
+| \`text_set(key, val)\` | \`useSharedText(key)\` | Hook re-renders with new text |
+| \`broadcast(ch, data)\` | \`useBroadcast(ch)\` | \`onMessage\` callback fires |
+| \`presence_list()\` | \`usePresence()\` | Shows all peers including Claude |
+
+---
+
+## Common Patterns
+
+### Counter
+\`\`\`
+shared_get(key: "count")          # Read current value
+shared_set(key: "count", value: 5) # Set to 5
+\`\`\`
+
+### Todo List
+\`\`\`
+array_get(key: "todos")           # Read all todos
+array_push(key: "todos", items: [{"id": "...", "text": "New task", "done": false}])
+array_delete(key: "todos", index: 2)  # Delete 3rd item
+\`\`\`
+
+### Collaborative Text
+\`\`\`
+text_get(key: "document")         # Read full text
+text_set(key: "document", value: "Hello World")  # Replace
+text_insert(key: "document", index: 5, content: ",")  # Insert comma
+\`\`\`
+
+---
+
+## Rules
+
+1. **React 18+ required** - hooks use modern React patterns
+2. **All hooks must be inside \`<YSDKProvider>\`** - this provides the Yjs document context
+3. **Objects in shared state are LWW** (last-write-wins) - use arrays for concurrent insertions
+4. **Presence is ephemeral** - disappears when user disconnects
+5. **Broadcast is fire-and-forget** - no persistence, no delivery guarantee
+
+## Verifying Changes
+
+After making changes via MCP tools, you can verify:
+1. \`shared_get\` / \`array_get\` / \`text_get\` - read back what you wrote
+2. \`document_snapshot\` - see ALL shared data at once
+3. \`presence_list\` - confirm you're connected (look for "Claude (MCP)")
+`;
+}
+
+// src/mcp-json.ts
+function generateMcpJson(opts) {
+  const env = {
+    YSDK_ROOM: opts.room
+  };
+  if (opts.apiKey) {
+    env.YSDK_API_KEY = opts.apiKey;
+  }
+  const config = {
+    mcpServers: {
+      ysdk: {
+        command: "npx",
+        args: ["@ysdk/mcp"],
+        env
+      }
+    }
+  };
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
+// src/scaffold.ts
+function scaffold(opts) {
+  const { name, dir, template: template2, apiKey: apiKey2 } = opts;
+  const tpl2 = TEMPLATES[template2];
+  if (!tpl2) {
+    throw new Error(`Unknown template: ${template2}. Available: ${Object.keys(TEMPLATES).join(", ")}`);
+  }
+  const room = name;
+  fs.mkdirSync(path.join(dir, "src"), { recursive: true });
+  writeFile(dir, "package.json", JSON.stringify({
+    name,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "vite",
+      build: "vite build",
+      preview: "vite preview"
+    },
+    dependencies: {
+      react: "^18.2.0",
+      "react-dom": "^18.2.0",
+      "@ysdk/react": "^0.1.0"
+    },
+    devDependencies: {
+      "@types/react": "^18.2.0",
+      "@types/react-dom": "^18.2.0",
+      "@vitejs/plugin-react": "^4.0.0",
+      typescript: "^5.0.0",
+      vite: "^5.0.0"
+    }
+  }, null, 2) + "\n");
+  writeFile(dir, "tsconfig.json", JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      useDefineForClassFields: true,
+      lib: ["ES2020", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      skipLibCheck: true,
+      moduleResolution: "bundler",
+      allowImportingTsExtensions: true,
+      isolatedModules: true,
+      moduleDetection: "force",
+      noEmit: true,
+      jsx: "react-jsx",
+      strict: true,
+      noUnusedLocals: false,
+      noUnusedParameters: false
+    },
+    include: ["src"]
+  }, null, 2) + "\n");
+  writeFile(dir, "vite.config.ts", `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});
+`);
+  writeFile(dir, "index.html", `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`);
+  const providerProps = apiKey2 ? `cloud={{ room: '${room}', apiKey: '${apiKey2}' }}` : `url="ws://localhost:1234" room="${room}"`;
+  writeFile(dir, "src/main.tsx", `import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { YSDKProvider } from '@ysdk/react';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <YSDKProvider ${providerProps}>
+      <App />
+    </YSDKProvider>
+  </React.StrictMode>,
+);
+`);
+  writeFile(dir, "src/App.tsx", tpl2.appTsx);
+  writeFile(dir, ".mcp.json", generateMcpJson({ room, apiKey: apiKey2 }));
+  writeFile(dir, "CLAUDE.md", generateClaudeMd(name, room));
+  writeFile(dir, ".gitignore", `node_modules
+dist
+.env
+.env.local
+`);
+}
+function writeFile(dir, filename, content) {
+  fs.writeFileSync(path.join(dir, filename), content);
+}
+
+// src/index.ts
+var args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+  console.log(`
+  Usage: npx @ysdk/create <project-name> [options]
+
+  Options:
+    --template <name>   App template (default: basic)
+                        Available: ${getTemplateNames().join(", ")}
+    --api-key <key>     YSDK cloud API key (optional, uses localhost without)
+    --help, -h          Show this help
+
+  Examples:
+    npx @ysdk/create my-app
+    npx @ysdk/create my-app --template todo
+    npx @ysdk/create my-app --template chat --api-key ysdk_live_...
+`);
+  process.exit(0);
+}
+var projectName = args[0];
+if (!projectName || projectName.startsWith("-")) {
+  console.error("Error: Please provide a project name.\n  npx @ysdk/create my-app");
+  process.exit(1);
+}
+function getFlag(name) {
+  const idx = args.indexOf(name);
+  if (idx === -1) return void 0;
+  return args[idx + 1];
+}
+var template = getFlag("--template") || "basic";
+var apiKey = getFlag("--api-key");
+if (!TEMPLATES[template]) {
+  console.error(`Error: Unknown template "${template}". Available: ${getTemplateNames().join(", ")}`);
+  process.exit(1);
+}
+var targetDir = path2.resolve(process.cwd(), projectName);
+if (fs2.existsSync(targetDir)) {
+  const contents = fs2.readdirSync(targetDir);
+  if (contents.length > 0) {
+    console.error(`Error: Directory "${projectName}" already exists and is not empty.`);
+    process.exit(1);
+  }
+}
+console.log(`
+Creating ${projectName} with "${template}" template...
+`);
+try {
+  scaffold({
+    name: projectName,
+    dir: targetDir,
+    template,
+    apiKey
+  });
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}
+var tpl = TEMPLATES[template];
+var useYarn = process.env.npm_config_user_agent?.startsWith("yarn");
+var usePnpm = process.env.npm_config_user_agent?.startsWith("pnpm");
+var pm = usePnpm ? "pnpm" : useYarn ? "yarn" : "npm";
+console.log(`  Created files:
+    package.json
+    tsconfig.json
+    vite.config.ts
+    index.html
+    src/main.tsx
+    src/App.tsx          (${tpl.description})
+    .mcp.json            (Claude MCP config)
+    CLAUDE.md            (AI assistant guide)
+    .gitignore
+`);
+console.log(`  Next steps:
+`);
+console.log(`    cd ${projectName}`);
+console.log(`    ${pm} install`);
+if (!apiKey) {
+  console.log(`    npx y-websocket               (start local sync server)`);
+}
+console.log(`    ${pm} run dev                    (start dev server)
+`);
+if (apiKey) {
+  console.log(`  Cloud sync configured with API key.`);
+} else {
+  console.log(`  Using local sync (ws://localhost:1234).`);
+  console.log(`  Add --api-key for cloud sync.
+`);
+}
+console.log(`  Open in Claude Code for God Mode - .mcp.json is ready.
+`);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/scaffold.ts","../src/templates.ts","../src/claude-md.ts","../src/mcp-json.ts"],"sourcesContent":["import * as path from 'node:path';\r\nimport * as fs from 'node:fs';\r\nimport { scaffold } from './scaffold.js';\r\nimport { getTemplateNames, TEMPLATES } from './templates.js';\r\n\r\n// Parse CLI args\r\nconst args = process.argv.slice(2);\r\n\r\nif (args.includes('--help') || args.includes('-h') || args.length === 0) {\r\n  console.log(`\r\n  Usage: npx @ysdk/create <project-name> [options]\r\n\r\n  Options:\r\n    --template <name>   App template (default: basic)\r\n                        Available: ${getTemplateNames().join(', ')}\r\n    --api-key <key>     YSDK cloud API key (optional, uses localhost without)\r\n    --help, -h          Show this help\r\n\r\n  Examples:\r\n    npx @ysdk/create my-app\r\n    npx @ysdk/create my-app --template todo\r\n    npx @ysdk/create my-app --template chat --api-key ysdk_live_...\r\n`);\r\n  process.exit(0);\r\n}\r\n\r\n// Parse project name and flags\r\nconst projectName = args[0];\r\n\r\nif (!projectName || projectName.startsWith('-')) {\r\n  console.error('Error: Please provide a project name.\\n  npx @ysdk/create my-app');\r\n  process.exit(1);\r\n}\r\n\r\nfunction getFlag(name: string): string | undefined {\r\n  const idx = args.indexOf(name);\r\n  if (idx === -1) return undefined;\r\n  return args[idx + 1];\r\n}\r\n\r\nconst template = getFlag('--template') || 'basic';\r\nconst apiKey = getFlag('--api-key');\r\n\r\n// Validate template\r\nif (!TEMPLATES[template]) {\r\n  console.error(`Error: Unknown template \"${template}\". Available: ${getTemplateNames().join(', ')}`);\r\n  process.exit(1);\r\n}\r\n\r\n// Create project directory\r\nconst targetDir = path.resolve(process.cwd(), projectName);\r\n\r\nif (fs.existsSync(targetDir)) {\r\n  const contents = fs.readdirSync(targetDir);\r\n  if (contents.length > 0) {\r\n    console.error(`Error: Directory \"${projectName}\" already exists and is not empty.`);\r\n    process.exit(1);\r\n  }\r\n}\r\n\r\nconsole.log(`\\nCreating ${projectName} with \"${template}\" template...\\n`);\r\n\r\ntry {\r\n  scaffold({\r\n    name: projectName,\r\n    dir: targetDir,\r\n    template,\r\n    apiKey,\r\n  });\r\n} catch (err: any) {\r\n  console.error(`Error: ${err.message}`);\r\n  process.exit(1);\r\n}\r\n\r\n// Print next steps\r\nconst tpl = TEMPLATES[template];\r\nconst useYarn = process.env.npm_config_user_agent?.startsWith('yarn');\r\nconst usePnpm = process.env.npm_config_user_agent?.startsWith('pnpm');\r\nconst pm = usePnpm ? 'pnpm' : useYarn ? 'yarn' : 'npm';\r\n\r\nconsole.log(`  Created files:\r\n    package.json\r\n    tsconfig.json\r\n    vite.config.ts\r\n    index.html\r\n    src/main.tsx\r\n    src/App.tsx          (${tpl.description})\r\n    .mcp.json            (Claude MCP config)\r\n    CLAUDE.md            (AI assistant guide)\r\n    .gitignore\r\n`);\r\n\r\nconsole.log(`  Next steps:\\n`);\r\nconsole.log(`    cd ${projectName}`);\r\nconsole.log(`    ${pm} install`);\r\n\r\nif (!apiKey) {\r\n  console.log(`    npx y-websocket               (start local sync server)`);\r\n}\r\n\r\nconsole.log(`    ${pm} run dev                    (start dev server)\\n`);\r\n\r\nif (apiKey) {\r\n  console.log(`  Cloud sync configured with API key.`);\r\n} else {\r\n  console.log(`  Using local sync (ws://localhost:1234).`);\r\n  console.log(`  Add --api-key for cloud sync.\\n`);\r\n}\r\n\r\nconsole.log(`  Open in Claude Code for God Mode - .mcp.json is ready.\\n`);\r\n","import * as fs from 'node:fs';\r\nimport * as path from 'node:path';\r\nimport { TEMPLATES } from './templates.js';\r\nimport { generateClaudeMd } from './claude-md.js';\r\nimport { generateMcpJson } from './mcp-json.js';\r\n\r\nexport interface ScaffoldOptions {\r\n  name: string;\r\n  dir: string;\r\n  template: string;\r\n  apiKey?: string;\r\n}\r\n\r\nexport function scaffold(opts: ScaffoldOptions) {\r\n  const { name, dir, template, apiKey } = opts;\r\n  const tpl = TEMPLATES[template];\r\n  if (!tpl) {\r\n    throw new Error(`Unknown template: ${template}. Available: ${Object.keys(TEMPLATES).join(', ')}`);\r\n  }\r\n\r\n  const room = name; // Use project name as default room\r\n\r\n  // Create directory structure\r\n  fs.mkdirSync(path.join(dir, 'src'), { recursive: true });\r\n\r\n  // package.json\r\n  writeFile(dir, 'package.json', JSON.stringify({\r\n    name,\r\n    version: '0.1.0',\r\n    private: true,\r\n    type: 'module',\r\n    scripts: {\r\n      dev: 'vite',\r\n      build: 'vite build',\r\n      preview: 'vite preview',\r\n    },\r\n    dependencies: {\r\n      react: '^18.2.0',\r\n      'react-dom': '^18.2.0',\r\n      '@ysdk/react': '^0.1.0',\r\n    },\r\n    devDependencies: {\r\n      '@types/react': '^18.2.0',\r\n      '@types/react-dom': '^18.2.0',\r\n      '@vitejs/plugin-react': '^4.0.0',\r\n      typescript: '^5.0.0',\r\n      vite: '^5.0.0',\r\n    },\r\n  }, null, 2) + '\\n');\r\n\r\n  // tsconfig.json\r\n  writeFile(dir, 'tsconfig.json', JSON.stringify({\r\n    compilerOptions: {\r\n      target: 'ES2020',\r\n      useDefineForClassFields: true,\r\n      lib: ['ES2020', 'DOM', 'DOM.Iterable'],\r\n      module: 'ESNext',\r\n      skipLibCheck: true,\r\n      moduleResolution: 'bundler',\r\n      allowImportingTsExtensions: true,\r\n      isolatedModules: true,\r\n      moduleDetection: 'force',\r\n      noEmit: true,\r\n      jsx: 'react-jsx',\r\n      strict: true,\r\n      noUnusedLocals: false,\r\n      noUnusedParameters: false,\r\n    },\r\n    include: ['src'],\r\n  }, null, 2) + '\\n');\r\n\r\n  // vite.config.ts\r\n  writeFile(dir, 'vite.config.ts', `import { defineConfig } from 'vite';\r\nimport react from '@vitejs/plugin-react';\r\n\r\nexport default defineConfig({\r\n  plugins: [react()],\r\n});\r\n`);\r\n\r\n  // index.html\r\n  writeFile(dir, 'index.html', `<!DOCTYPE html>\r\n<html lang=\"en\">\r\n  <head>\r\n    <meta charset=\"UTF-8\" />\r\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\r\n    <title>${name}</title>\r\n  </head>\r\n  <body>\r\n    <div id=\"root\"></div>\r\n    <script type=\"module\" src=\"/src/main.tsx\"></script>\r\n  </body>\r\n</html>\r\n`);\r\n\r\n  // src/main.tsx\r\n  const providerProps = apiKey\r\n    ? `cloud={{ room: '${room}', apiKey: '${apiKey}' }}`\r\n    : `url=\"ws://localhost:1234\" room=\"${room}\"`;\r\n\r\n  writeFile(dir, 'src/main.tsx', `import React from 'react';\r\nimport ReactDOM from 'react-dom/client';\r\nimport { YSDKProvider } from '@ysdk/react';\r\nimport App from './App';\r\n\r\nReactDOM.createRoot(document.getElementById('root')!).render(\r\n  <React.StrictMode>\r\n    <YSDKProvider ${providerProps}>\r\n      <App />\r\n    </YSDKProvider>\r\n  </React.StrictMode>,\r\n);\r\n`);\r\n\r\n  // src/App.tsx\r\n  writeFile(dir, 'src/App.tsx', tpl.appTsx);\r\n\r\n  // .mcp.json\r\n  writeFile(dir, '.mcp.json', generateMcpJson({ room, apiKey }));\r\n\r\n  // CLAUDE.md\r\n  writeFile(dir, 'CLAUDE.md', generateClaudeMd(name, room));\r\n\r\n  // .gitignore\r\n  writeFile(dir, '.gitignore', `node_modules\r\ndist\r\n.env\r\n.env.local\r\n`);\r\n}\r\n\r\nfunction writeFile(dir: string, filename: string, content: string) {\r\n  fs.writeFileSync(path.join(dir, filename), content);\r\n}\r\n","// App.tsx content for each project template\r\n\r\nexport const TEMPLATES: Record<string, { description: string; appTsx: string }> = {\r\n  basic: {\r\n    description: 'Simple shared counter - the \"Hello World\" of multiplayer',\r\n    appTsx: `import { useShared } from '@ysdk/react';\r\n\r\nexport default function App() {\r\n  const [count, setCount] = useShared('count', 0);\r\n\r\n  return (\r\n    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40 }}>\r\n      <h1>Shared Counter</h1>\r\n      <p style={{ fontSize: 64, textAlign: 'center' }}>{count}</p>\r\n      <div style={{ display: 'flex', gap: 8, justifyContent: 'center' }}>\r\n        <button onClick={() => setCount(count - 1)}>-</button>\r\n        <button onClick={() => setCount(count + 1)}>+</button>\r\n        <button onClick={() => setCount(0)}>Reset</button>\r\n      </div>\r\n      <p style={{ textAlign: 'center', color: '#888', marginTop: 24 }}>\r\n        Open in another tab to see real-time sync\r\n      </p>\r\n    </div>\r\n  );\r\n}\r\n`,\r\n  },\r\n\r\n  todo: {\r\n    description: 'Collaborative to-do list with shared array',\r\n    appTsx: `import { useState } from 'react';\r\nimport { useSharedArray, usePresence } from '@ysdk/react';\r\n\r\ninterface Todo {\r\n  id: string;\r\n  text: string;\r\n  done: boolean;\r\n}\r\n\r\nexport default function App() {\r\n  const [todos, ops] = useSharedArray<Todo>('todos');\r\n  const [input, setInput] = useState('');\r\n  const { peers, count } = usePresence({ name: 'User' });\r\n\r\n  const addTodo = () => {\r\n    if (!input.trim()) return;\r\n    ops.push({ id: crypto.randomUUID(), text: input.trim(), done: false });\r\n    setInput('');\r\n  };\r\n\r\n  const toggleTodo = (index: number) => {\r\n    const todo = todos[index];\r\n    ops.delete(index);\r\n    ops.insert(index, { ...todo, done: !todo.done });\r\n  };\r\n\r\n  const deleteTodo = (index: number) => {\r\n    ops.delete(index);\r\n  };\r\n\r\n  return (\r\n    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40 }}>\r\n      <h1>Shared To-Do List</h1>\r\n      <p style={{ color: '#888' }}>{count + 1} user(s) connected</p>\r\n\r\n      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>\r\n        <input\r\n          value={input}\r\n          onChange={(e) => setInput(e.target.value)}\r\n          onKeyDown={(e) => e.key === 'Enter' && addTodo()}\r\n          placeholder=\"Add a task...\"\r\n          style={{ flex: 1, padding: 8 }}\r\n        />\r\n        <button onClick={addTodo}>Add</button>\r\n      </div>\r\n\r\n      <ul style={{ listStyle: 'none', padding: 0 }}>\r\n        {todos.map((todo, i) => (\r\n          <li key={todo.id} style={{ display: 'flex', gap: 8, padding: '8px 0', borderBottom: '1px solid #eee' }}>\r\n            <input type=\"checkbox\" checked={todo.done} onChange={() => toggleTodo(i)} />\r\n            <span style={{ flex: 1, textDecoration: todo.done ? 'line-through' : 'none', color: todo.done ? '#aaa' : '#000' }}>\r\n              {todo.text}\r\n            </span>\r\n            <button onClick={() => deleteTodo(i)} style={{ color: 'red', border: 'none', background: 'none', cursor: 'pointer' }}>x</button>\r\n          </li>\r\n        ))}\r\n      </ul>\r\n\r\n      {todos.length === 0 && <p style={{ textAlign: 'center', color: '#aaa' }}>No tasks yet</p>}\r\n    </div>\r\n  );\r\n}\r\n`,\r\n  },\r\n\r\n  whiteboard: {\r\n    description: 'Multiplayer drawing canvas with presence cursors',\r\n    appTsx: `import { useRef, useEffect, useState, useCallback } from 'react';\r\nimport { useSharedArray, usePresence, useBroadcast } from '@ysdk/react';\r\n\r\ninterface Point { x: number; y: number }\r\ninterface Stroke { points: Point[]; color: string }\r\n\r\nexport default function App() {\r\n  const canvasRef = useRef<HTMLCanvasElement>(null);\r\n  const [strokes, ops] = useSharedArray<Stroke>('strokes');\r\n  const [drawing, setDrawing] = useState(false);\r\n  const [color, setColor] = useState('#000000');\r\n  const currentStroke = useRef<Point[]>([]);\r\n  const { peers, setPresence } = usePresence<{ name: string; cursor?: Point }>({ name: 'User' });\r\n  const { broadcast, onMessage } = useBroadcast<{ cursor: Point }>('cursor');\r\n\r\n  // Draw all strokes\r\n  useEffect(() => {\r\n    const canvas = canvasRef.current;\r\n    if (!canvas) return;\r\n    const ctx = canvas.getContext('2d')!;\r\n    ctx.clearRect(0, 0, canvas.width, canvas.height);\r\n\r\n    for (const stroke of strokes) {\r\n      if (stroke.points.length < 2) continue;\r\n      ctx.beginPath();\r\n      ctx.strokeStyle = stroke.color;\r\n      ctx.lineWidth = 3;\r\n      ctx.lineCap = 'round';\r\n      ctx.lineJoin = 'round';\r\n      ctx.moveTo(stroke.points[0].x, stroke.points[0].y);\r\n      for (let i = 1; i < stroke.points.length; i++) {\r\n        ctx.lineTo(stroke.points[i].x, stroke.points[i].y);\r\n      }\r\n      ctx.stroke();\r\n    }\r\n  }, [strokes]);\r\n\r\n  const getPos = (e: React.MouseEvent): Point => {\r\n    const rect = canvasRef.current!.getBoundingClientRect();\r\n    return { x: e.clientX - rect.left, y: e.clientY - rect.top };\r\n  };\r\n\r\n  return (\r\n    <div style={{ fontFamily: 'system-ui', maxWidth: 640, margin: '0 auto', padding: 40 }}>\r\n      <h1>Shared Whiteboard</h1>\r\n      <div style={{ display: 'flex', gap: 8, marginBottom: 8 }}>\r\n        <input type=\"color\" value={color} onChange={(e) => setColor(e.target.value)} />\r\n        <button onClick={() => ops.clear()}>Clear</button>\r\n        <span style={{ color: '#888', marginLeft: 'auto' }}>{peers.length + 1} connected</span>\r\n      </div>\r\n      <canvas\r\n        ref={canvasRef}\r\n        width={600}\r\n        height={400}\r\n        style={{ border: '1px solid #ccc', cursor: 'crosshair' }}\r\n        onMouseDown={(e) => {\r\n          setDrawing(true);\r\n          currentStroke.current = [getPos(e)];\r\n        }}\r\n        onMouseMove={(e) => {\r\n          const pos = getPos(e);\r\n          broadcast({ cursor: pos });\r\n          if (!drawing) return;\r\n          currentStroke.current.push(pos);\r\n          // Draw locally for smooth feel\r\n          const ctx = canvasRef.current!.getContext('2d')!;\r\n          const pts = currentStroke.current;\r\n          if (pts.length >= 2) {\r\n            ctx.beginPath();\r\n            ctx.strokeStyle = color;\r\n            ctx.lineWidth = 3;\r\n            ctx.lineCap = 'round';\r\n            ctx.moveTo(pts[pts.length - 2].x, pts[pts.length - 2].y);\r\n            ctx.lineTo(pts[pts.length - 1].x, pts[pts.length - 1].y);\r\n            ctx.stroke();\r\n          }\r\n        }}\r\n        onMouseUp={() => {\r\n          if (currentStroke.current.length > 1) {\r\n            ops.push({ points: currentStroke.current, color });\r\n          }\r\n          setDrawing(false);\r\n          currentStroke.current = [];\r\n        }}\r\n      />\r\n    </div>\r\n  );\r\n}\r\n`,\r\n  },\r\n\r\n  chat: {\r\n    description: 'Real-time chat room with presence',\r\n    appTsx: `import { useState, useRef, useEffect } from 'react';\r\nimport { useSharedArray, usePresence } from '@ysdk/react';\r\n\r\ninterface Message {\r\n  id: string;\r\n  user: string;\r\n  text: string;\r\n  time: number;\r\n}\r\n\r\nconst COLORS = ['#e74c3c', '#3498db', '#2ecc71', '#f39c12', '#9b59b6', '#1abc9c'];\r\n\r\nexport default function App() {\r\n  const [messages, ops] = useSharedArray<Message>('messages');\r\n  const [input, setInput] = useState('');\r\n  const [name, setName] = useState(() => 'User-' + Math.random().toString(36).slice(2, 5));\r\n  const { peers, setPresence, count } = usePresence<{ name: string; typing?: boolean }>({ name });\r\n  const bottomRef = useRef<HTMLDivElement>(null);\r\n\r\n  useEffect(() => {\r\n    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });\r\n  }, [messages.length]);\r\n\r\n  const send = () => {\r\n    if (!input.trim()) return;\r\n    ops.push({ id: crypto.randomUUID(), user: name, text: input.trim(), time: Date.now() });\r\n    setInput('');\r\n    setPresence({ typing: false });\r\n  };\r\n\r\n  const colorFor = (user: string) => COLORS[Math.abs([...user].reduce((h, c) => (h * 31 + c.charCodeAt(0)) | 0, 0)) % COLORS.length];\r\n  const typingPeers = peers.filter(p => p.typing).map(p => p.name);\r\n\r\n  return (\r\n    <div style={{ fontFamily: 'system-ui', maxWidth: 480, margin: '0 auto', padding: 40, display: 'flex', flexDirection: 'column', height: '100vh' }}>\r\n      <div style={{ display: 'flex', gap: 8, marginBottom: 16, alignItems: 'center' }}>\r\n        <h1 style={{ margin: 0, flex: 1 }}>Chat Room</h1>\r\n        <input\r\n          value={name}\r\n          onChange={(e) => { setName(e.target.value); setPresence({ name: e.target.value }); }}\r\n          style={{ width: 100, padding: 4 }}\r\n          placeholder=\"Your name\"\r\n        />\r\n        <span style={{ color: '#888' }}>{count + 1} online</span>\r\n      </div>\r\n\r\n      <div style={{ flex: 1, overflowY: 'auto', border: '1px solid #eee', borderRadius: 8, padding: 12 }}>\r\n        {messages.map((msg) => (\r\n          <div key={msg.id} style={{ marginBottom: 8 }}>\r\n            <strong style={{ color: colorFor(msg.user) }}>{msg.user}</strong>\r\n            <span style={{ color: '#aaa', fontSize: 12, marginLeft: 8 }}>{new Date(msg.time).toLocaleTimeString()}</span>\r\n            <div>{msg.text}</div>\r\n          </div>\r\n        ))}\r\n        <div ref={bottomRef} />\r\n      </div>\r\n\r\n      {typingPeers.length > 0 && (\r\n        <div style={{ color: '#888', fontSize: 12, padding: 4 }}>\r\n          {typingPeers.join(', ')} {typingPeers.length === 1 ? 'is' : 'are'} typing...\r\n        </div>\r\n      )}\r\n\r\n      <div style={{ display: 'flex', gap: 8, marginTop: 8 }}>\r\n        <input\r\n          value={input}\r\n          onChange={(e) => { setInput(e.target.value); setPresence({ typing: e.target.value.length > 0 }); }}\r\n          onKeyDown={(e) => e.key === 'Enter' && send()}\r\n          placeholder=\"Type a message...\"\r\n          style={{ flex: 1, padding: 8 }}\r\n        />\r\n        <button onClick={send}>Send</button>\r\n      </div>\r\n    </div>\r\n  );\r\n}\r\n`,\r\n  },\r\n};\r\n\r\nexport function getTemplateNames(): string[] {\r\n  return Object.keys(TEMPLATES);\r\n}\r\n","// Generates CLAUDE.md for the scaffolded project\r\n\r\nexport function generateClaudeMd(projectName: string, room: string): string {\r\n  return `# CLAUDE.md - ${projectName}\r\n\r\nThis is a collaborative React app powered by YSDK. You (Claude) are connected to the same multiplayer room as the browser via MCP tools.\r\n\r\n## How It Works\r\n\r\nThe React app and Claude share the same Yjs CRDT document. When you call \\`shared_set\\`, the React app's \\`useShared\\` hook updates instantly. When the user changes state in the browser, you can read it with \\`shared_get\\`.\r\n\r\n**Room:** \\`${room}\\`\r\n\r\n---\r\n\r\n## MCP Tools Reference\r\n\r\n### Shared State (Y.Map)\r\nMaps to \\`useShared(key, defaultValue)\\` in React.\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| \\`shared_get(key)\\` | Read a value. Returns the current value or \"undefined\". |\r\n| \\`shared_set(key, value)\\` | Write a value. All connected clients update instantly. Value can be any JSON type. |\r\n| \\`shared_delete(key)\\` | Remove a key from shared state. |\r\n| \\`shared_keys()\\` | List all keys in shared state. |\r\n\r\n**Example:**\r\n\\`\\`\\`\r\nshared_set(key: \"count\", value: 42)  ->  useShared('count', 0) returns 42\r\nshared_get(key: \"count\")             ->  \"42\"\r\n\\`\\`\\`\r\n\r\n**Important:** Objects are stored as opaque values (last-write-wins on the whole object). If two users set the same key simultaneously, one write wins. Use shared arrays for concurrent insertions.\r\n\r\n### Shared Arrays (Y.Array)\r\nMaps to \\`useSharedArray(key)\\` in React. Concurrent insertions merge cleanly (CRDT).\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| \\`array_get(key)\\` | Read all items in the array. |\r\n| \\`array_push(key, items)\\` | Append items to the end. \\`items\\` is a JSON array. |\r\n| \\`array_insert(key, index, items)\\` | Insert items at a position. |\r\n| \\`array_delete(key, index, count?)\\` | Delete items starting at index. Count defaults to 1. |\r\n| \\`array_clear(key)\\` | Remove all items from the array. |\r\n\r\n**Example:**\r\n\\`\\`\\`\r\narray_push(key: \"todos\", items: [{\"id\": \"abc\", \"text\": \"Buy milk\", \"done\": false}])\r\narray_get(key: \"todos\")  ->  [{\"id\": \"abc\", \"text\": \"Buy milk\", \"done\": false}]\r\n\\`\\`\\`\r\n\r\n### Shared Text (Y.Text)\r\nMaps to \\`useSharedText(key, defaultValue)\\` in React. Character-by-character CRDT merge.\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| \\`text_get(key)\\` | Read the text content. |\r\n| \\`text_set(key, value)\\` | Replace the entire text. |\r\n| \\`text_insert(key, index, content)\\` | Insert text at a character position. |\r\n| \\`text_delete(key, index, length)\\` | Delete characters starting at position. |\r\n\r\n### Presence & Broadcast\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| \\`presence_list()\\` | List all connected users and their state. |\r\n| \\`broadcast(channel, data)\\` | Send ephemeral message to all clients. Received via \\`useBroadcast(channel)\\`. Not persisted. |\r\n\r\n### Utility\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| \\`room_info()\\` | Connection status, sync status, client count, document size. |\r\n| \\`document_snapshot()\\` | Full dump of all shared data (maps, arrays, texts). |\r\n\r\n---\r\n\r\n## React Hooks Reference\r\n\r\n\\`\\`\\`tsx\r\nimport { YSDKProvider, useShared, useSharedArray, useSharedText, usePresence, useBroadcast } from '@ysdk/react';\r\n\r\n// Shared state (like useState but multiplayer)\r\nconst [count, setCount] = useShared('count', 0);\r\n\r\n// Shared array (concurrent insertions merge)\r\nconst [items, ops] = useSharedArray<Item>('items');\r\nops.push(item);\r\nops.delete(index, count?);\r\nops.insert(index, item);\r\nops.clear();\r\n\r\n// Shared text (character-level CRDT)\r\nconst { value, setValue, ytext } = useSharedText('doc', 'initial');\r\n\r\n// Presence (who's online + ephemeral state)\r\nconst { peers, setPresence, count } = usePresence<{ name: string }>({ name: 'User' });\r\n\r\n// Broadcast (fire-and-forget messages)\r\nconst { broadcast, onMessage } = useBroadcast<T>('channel');\r\nbroadcast(data);\r\nonMessage((data, senderId) => { ... });\r\n\\`\\`\\`\r\n\r\n---\r\n\r\n## How MCP Maps to Hooks\r\n\r\n| MCP Tool | React Hook | What Happens |\r\n|----------|------------|-------------|\r\n| \\`shared_set(key, val)\\` | \\`useShared(key)\\` | Hook re-renders with new value |\r\n| \\`array_push(key, items)\\` | \\`useSharedArray(key)\\` | Hook re-renders with new array |\r\n| \\`text_set(key, val)\\` | \\`useSharedText(key)\\` | Hook re-renders with new text |\r\n| \\`broadcast(ch, data)\\` | \\`useBroadcast(ch)\\` | \\`onMessage\\` callback fires |\r\n| \\`presence_list()\\` | \\`usePresence()\\` | Shows all peers including Claude |\r\n\r\n---\r\n\r\n## Common Patterns\r\n\r\n### Counter\r\n\\`\\`\\`\r\nshared_get(key: \"count\")          # Read current value\r\nshared_set(key: \"count\", value: 5) # Set to 5\r\n\\`\\`\\`\r\n\r\n### Todo List\r\n\\`\\`\\`\r\narray_get(key: \"todos\")           # Read all todos\r\narray_push(key: \"todos\", items: [{\"id\": \"...\", \"text\": \"New task\", \"done\": false}])\r\narray_delete(key: \"todos\", index: 2)  # Delete 3rd item\r\n\\`\\`\\`\r\n\r\n### Collaborative Text\r\n\\`\\`\\`\r\ntext_get(key: \"document\")         # Read full text\r\ntext_set(key: \"document\", value: \"Hello World\")  # Replace\r\ntext_insert(key: \"document\", index: 5, content: \",\")  # Insert comma\r\n\\`\\`\\`\r\n\r\n---\r\n\r\n## Rules\r\n\r\n1. **React 18+ required** - hooks use modern React patterns\r\n2. **All hooks must be inside \\`<YSDKProvider>\\`** - this provides the Yjs document context\r\n3. **Objects in shared state are LWW** (last-write-wins) - use arrays for concurrent insertions\r\n4. **Presence is ephemeral** - disappears when user disconnects\r\n5. **Broadcast is fire-and-forget** - no persistence, no delivery guarantee\r\n\r\n## Verifying Changes\r\n\r\nAfter making changes via MCP tools, you can verify:\r\n1. \\`shared_get\\` / \\`array_get\\` / \\`text_get\\` - read back what you wrote\r\n2. \\`document_snapshot\\` - see ALL shared data at once\r\n3. \\`presence_list\\` - confirm you're connected (look for \"Claude (MCP)\")\r\n`;\r\n}\r\n","// Generates .mcp.json for the scaffolded project\r\n\r\nexport interface McpJsonOptions {\r\n  room: string;\r\n  apiKey?: string;\r\n}\r\n\r\nexport function generateMcpJson(opts: McpJsonOptions): string {\r\n  const env: Record<string, string> = {\r\n    YSDK_ROOM: opts.room,\r\n  };\r\n\r\n  if (opts.apiKey) {\r\n    env.YSDK_API_KEY = opts.apiKey;\r\n  }\r\n\r\n  const config = {\r\n    mcpServers: {\r\n      ysdk: {\r\n        command: 'npx',\r\n        args: ['@ysdk/mcp'],\r\n        env,\r\n      },\r\n    },\r\n  };\r\n\r\n  return JSON.stringify(config, null, 2) + '\\n';\r\n}\r\n"],"mappings":"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","names":["path","fs","projectName","template","apiKey","tpl"]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ysdk/create",
+  "version": "0.1.0",
+  "description": "Create a new YSDK collaborative app with Claude integration.",
+  "type": "module",
+  "bin": {
+    "create-ysdk": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aoatkinson/ysdk"
+  },
+  "keywords": [
+    "yjs",
+    "crdt",
+    "create",
+    "scaffold",
+    "collaborative",
+    "multiplayer"
+  ]
+}