@mosaicsite/claude-skill 1.0.0

package/CLAUDE.md

@@ -0,0 +1,286 @@
+# Mosaic Platform Skill
+
+**Mosaic is your full-stack app development co-platform** - Database, Vector, Auth, Storage, Git, and Compute in one API.
+
+---
+
+## ⚡ The 5 Steps to Ship an App
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. CREATE PROJECT  →  Get slug + git repo + database       │
+│  2. BUILD CODE      →  Clone repo, add files, git push      │
+│  3. REQUEST DEPLOY  →  POST /{slug}/deploy                  │
+│  4. CHECK STATUS    →  Poll until status = "running"        │
+│  5. DONE!           →  Live at https://{slug}.mosaic.site   │
+└─────────────────────────────────────────────────────────────┘
+
+Need help? → Submit a ticket: POST /tickets
+Want a feature? → Request it: POST /tickets with "Feature Request:" prefix
+```
+
+---
+
+## 🔑 Authentication
+
+**Base URL**: `https://api.mosaic.site/v1/project`
+
+**Every request needs**: `X-API-Key: mk_xxxxx` header
+
+---
+
+## Step 1: CREATE PROJECT
+
+```bash
+curl -X POST https://api.mosaic.site/v1/project/projects \
+  -H "X-API-Key: $MOSAIC_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My App"}'
+```
+
+**Response** (save these!):
+```json
+{
+  "id": "uuid-here",
+  "name": "My App",
+  "slug": "myapp-x4k2",          ← Use this for all API calls!
+  "database": {
+    "host": "10.0.50.3",
+    "port": 6432,
+    "user": "tenant_myapp_x4k2",
+    "password": "auto-generated"
+  },
+  "git_repo_url": "https://git.mosaic.site/user/myapp-x4k2.git"  ← Clone this!
+}
+```
+
+**Optional: Create database tables now**
+```bash
+curl -X POST https://api.mosaic.site/v1/project/{slug}/sql \
+  -H "X-API-Key: $MOSAIC_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "CREATE TABLE users (id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), email TEXT UNIQUE, name TEXT)", "params": []}'
+```
+
+---
+
+## Step 2: BUILD CODE
+
+```bash
+# Clone your repo
+git clone https://git.mosaic.site/{user}/{slug}.git
+cd {slug}
+
+# Add your files (see Stack Detection below)
+# ... create index.html, package.json, etc ...
+
+# Commit and push
+git add .
+git commit -m "My awesome app"
+git push
+```
+
+### Stack Detection - What Files to Create
+
+| If you create... | Mosaic runs... | Dependencies |
+|------------------|----------------|--------------|
+| `index.html` only | nginx (static) | None needed! |
+| `package.json` | Node.js | `npm install` automatic! |
+| `requirements.txt` | Python | `pip install` automatic! |
+| `go.mod` | Go | `go build` automatic! |
+| `Cargo.toml` | Rust | `cargo build` automatic! |
+
+**You don't install dependencies** - Mosaic does it during deploy!
+
+---
+
+## Step 3: REQUEST DEPLOY
+
+```bash
+curl -X POST https://api.mosaic.site/v1/project/{slug}/deploy \
+  -H "X-API-Key: $MOSAIC_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"repo_url": "https://git.mosaic.site/{user}/{slug}.git", "branch": "main"}'
+```
+
+**Response**:
+```json
+{
+  "deployment_id": "deploy-myapp-x4k2-20240101120000",
+  "status": "pending",
+  "message": "Deployment started",
+  "url": "https://myapp-x4k2.mosaic.site"
+}
+```
+
+---
+
+## Step 4: CHECK STATUS
+
+```bash
+curl https://api.mosaic.site/v1/project/{slug}/deploy/status \
+  -H "X-API-Key: $MOSAIC_API_KEY"
+```
+
+**Poll this until status = "running"** (usually 15-30 seconds)
+
+```json
+{
+  "status": "running",      ← When you see this, you're live!
+  "container_name": "deploy-myapp-x4k2",
+  "url": "https://myapp-x4k2.mosaic.site"
+}
+```
+
+**If status = "failed"**, check logs:
+```bash
+curl https://api.mosaic.site/v1/project/{slug}/deploy/logs \
+  -H "X-API-Key: $MOSAIC_API_KEY"
+```
+
+---
+
+## Step 5: DONE! 🎉
+
+**Your app is live at**: `https://{slug}.mosaic.site`
+
+---
+
+## 🆘 Submit a Support Ticket
+
+Something not working? Submit a ticket:
+
+```bash
+curl -X POST https://api.mosaic.site/v1/project/tickets \
+  -H "X-API-Key: $MOSAIC_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "subject": "Deploy failing for myapp-x4k2",
+    "message": "Getting error: container not starting. Logs show..."
+  }'
+```
+
+---
+
+## 💡 Request a Feature
+
+Want something new? Prefix with "Feature Request:":
+
+```bash
+curl -X POST https://api.mosaic.site/v1/project/tickets \
+  -H "X-API-Key: $MOSAIC_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "subject": "Feature Request: Custom domain support",
+    "message": "Would love to use my own domain mydomain.com instead of slug.mosaic.site"
+  }'
+```
+
+---
+
+## 📚 Full API Reference
+
+### Projects
+```
+GET  /projects              → List all your projects
+POST /projects              → Create: {"name": "..."}
+GET  /{slug}/info           → Project details
+GET  /{slug}/credentials    → Database connection info
+```
+
+### Database (PostgreSQL + pgvector)
+```
+POST /{slug}/sql            → {"query": "...", "params": [...]}
+```
+Extensions: `pgvector`, `uuid-ossp`, `pgcrypto`
+
+### Deployment
+```
+POST /{slug}/deploy         → {"repo_url": "...", "branch": "main"}
+GET  /{slug}/deploy/status  → Check if running
+GET  /{slug}/deploy/logs    → Build + runtime logs
+POST /{slug}/restart        → Restart container
+POST /{slug}/stop           → Stop container
+POST /{slug}/start          → Start stopped container
+```
+
+### Storage (S3)
+```
+GET  /{slug}/storage/files           → List files
+POST /{slug}/storage/upload          → Get upload URL
+GET  /{slug}/storage/files/{name}    → Download URL
+DELETE /{slug}/storage/files/{name}  → Delete file
+```
+
+### Authentication (Magic Links)
+```
+POST /{slug}/auth/send-magic-link    → {"email": "...", "redirect_url": "..."}
+GET  /{slug}/auth/verify             → Verify token
+GET  /{slug}/auth/users              → List authenticated users
+```
+
+### Support
+```
+GET  /tickets               → List your tickets
+POST /tickets               → {"subject": "...", "message": "..."}
+GET  /tickets/{id}          → Ticket details
+```
+
+---
+
+## 🏷️ Plan Limits
+
+| Resource | Free | Starter | Pro | Enterprise |
+|----------|------|---------|-----|------------|
+| Database | 2 GB | 10 GB | 50 GB | 500 GB |
+| Storage | 5 GB | 20 GB | 100 GB | 1 TB |
+| SQL queries/hr | 1,000 | 10,000 | 100,000 | 1,000,000 |
+| Magic links/day | 10 | 100 | 1,000 | 10,000 |
+| Container RAM | 512 MB | 1 GB | 2 GB | 8 GB |
+| Container CPU | 0.5 | 1 | 2 | 4 |
+
+### Check Database Usage
+
+```bash
+curl https://api.mosaic.site/v1/project/{slug}/database/usage \
+  -H "X-API-Key: $MOSAIC_API_KEY"
+```
+
+Returns: size, limit, usage_percent, remaining space
+
+---
+
+## 🔗 URLs
+
+| Service | URL |
+|---------|-----|
+| Dashboard | https://mosaic.site/dashboard |
+| API | https://api.mosaic.site |
+| Git | https://git.mosaic.site |
+| Your Sites | https://{slug}.mosaic.site |
+| This Skill | https://api.mosaic.site/skill.md |
+
+---
+
+## 💡 Tips
+
+1. **Save the slug!** You need it for every API call
+2. **Don't install deps** - Mosaic does it automatically
+3. **Use $1, $2 in SQL** - Never concatenate strings
+4. **Poll deploy status** - Wait for "running"
+5. **Check logs on failure** - Shows exactly what went wrong
+6. **Submit tickets freely** - We're here to help!
+
+---
+
+## 🔄 Keep This Skill Updated
+
+```bash
+curl -s https://api.mosaic.site/skill.md > CLAUDE.md
+```
+
+New features are added regularly. Re-fetch to get the latest!
+
+---
+
+*Mosaic: Ship apps in minutes, not months. One API, infinite possibilities.*

package/README.md

@@ -0,0 +1,98 @@
+# @mosaicsite/claude-skill
+
+**Mosaic: Your full-stack app development co-platform.**
+
+Give your AI assistant the complete skill to build and deploy production apps - Database, Vector Store, Auth, Storage, Git, and Compute, all unified in one friendly API.
+
+## Installation
+
+```bash
+npx @mosaicsite/claude-skill
+```
+
+The installer auto-detects your AI tools and installs appropriately:
+
+| Tool | Install Location |
+|------|-----------------|
+| Claude Code | `CLAUDE.md` or `~/.claude/skills/mosaic.md` |
+| Cursor | `.cursorrules` or `.cursor/mosaic.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Gemini | `GEMINI.md` |
+| Generic | `AI_INSTRUCTIONS.md` |
+
+## What Your AI Learns
+
+After installation, your AI assistant can:
+
+1. **Create projects** with PostgreSQL + pgvector + Git repo
+2. **Design schemas** and execute SQL with vector search
+3. **Build apps** - Auto-detects Node.js, Python, Go, Rust, static
+4. **Deploy** - Push to Git, trigger deploy, live in 30 seconds
+5. **Manage auth** via magic links
+6. **Upload files** to S3 storage
+7. **Submit tickets** when help is needed
+
+## Usage
+
+1. Get your API key from https://mosaic.site/dashboard
+2. Tell your AI: *"Build me a todo app on Mosaic"*
+3. Provide your API key when asked
+4. AI handles: project creation → database → code → Git → deploy → live URL
+
+## Example Conversation
+
+```
+You: Build me a blog on Mosaic. My API key is mk_xxxxx
+
+AI: I'll build your blog on Mosaic...
+
+1. Creating project "blog"...
+   → Slug: blog-a1b2
+   → Git: https://git.mosaic.site/you/blog-a1b2.git
+
+2. Setting up database...
+   → Created tables: posts, authors
+
+3. Building the app...
+   → Created: package.json, server.js, public/index.html
+
+4. Pushing to Git...
+   → Committed and pushed
+
+5. Deploying...
+   → Status: running
+
+✅ Your blog is live at https://blog-a1b2.mosaic.site
+```
+
+## Manual Installation
+
+If auto-detect doesn't work:
+
+```bash
+# Fetch latest skill
+curl -s https://api.mosaic.site/skill.md >> CLAUDE.md
+```
+
+Or copy `CLAUDE.md` from this package to your project.
+
+## Keep Updated
+
+```bash
+# Re-run installer to get latest
+npx @mosaicsite/claude-skill
+
+# Or fetch directly
+curl -s https://api.mosaic.site/skill.md > CLAUDE.md
+```
+
+## Links
+
+- **Dashboard**: https://mosaic.site/dashboard
+- **API Docs**: https://api.mosaic.site
+- **Full Skill**: https://api.mosaic.site/skill.md
+- **Support**: https://mosaic.site/support
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const skillContent = fs.readFileSync(
+  path.join(__dirname, '..', 'CLAUDE.md'),
+  'utf8'
+);
+
+// Detect which AI tools are present and install appropriately
+const tools = [];
+
+// Check for Claude Code
+const claudeDir = path.join(os.homedir(), '.claude');
+if (fs.existsSync(claudeDir) || process.env.CLAUDE_CODE) {
+  tools.push({
+    name: 'Claude Code',
+    paths: [
+      path.join(process.cwd(), 'CLAUDE.md'),
+      path.join(os.homedir(), '.claude', 'skills', 'mosaic.md'),
+    ],
+    append: true, // Append to existing CLAUDE.md
+  });
+}
+
+// Check for Cursor
+const cursorRules = path.join(process.cwd(), '.cursorrules');
+if (fs.existsSync(cursorRules) || fs.existsSync(path.join(os.homedir(), '.cursor'))) {
+  tools.push({
+    name: 'Cursor',
+    paths: [
+      path.join(process.cwd(), '.cursor', 'mosaic.md'),
+      cursorRules,
+    ],
+    append: true,
+  });
+}
+
+// Check for GitHub Copilot
+const copilotDir = path.join(process.cwd(), '.github');
+if (fs.existsSync(copilotDir)) {
+  tools.push({
+    name: 'GitHub Copilot',
+    paths: [
+      path.join(copilotDir, 'copilot-instructions.md'),
+    ],
+    append: true,
+  });
+}
+
+// Check for Gemini
+if (process.env.GEMINI_API_KEY || fs.existsSync(path.join(os.homedir(), '.config', 'gemini'))) {
+  tools.push({
+    name: 'Gemini',
+    paths: [
+      path.join(process.cwd(), 'GEMINI.md'),
+      path.join(os.homedir(), '.config', 'gemini', 'mosaic.md'),
+    ],
+    append: false,
+  });
+}
+
+// Default: Create a generic AI context file if no specific tool detected
+if (tools.length === 0) {
+  tools.push({
+    name: 'Generic AI',
+    paths: [
+      path.join(process.cwd(), 'AI_INSTRUCTIONS.md'),
+      path.join(process.cwd(), 'CLAUDE.md'),
+    ],
+    append: false,
+  });
+}
+
+// Header for appended content
+const appendHeader = `
+
+---
+
+<!-- Mosaic Platform Skill - Added by @mosaic/claude-skill -->
+
+`;
+
+let installed = [];
+
+for (const tool of tools) {
+  for (const location of tool.paths) {
+    try {
+      const dir = path.dirname(location);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+
+      if (tool.append && fs.existsSync(location)) {
+        // Check if already installed
+        const existing = fs.readFileSync(location, 'utf8');
+        if (existing.includes('Mosaic Platform')) {
+          console.log(`⏭️  ${tool.name}: Already has Mosaic skill`);
+          break;
+        }
+        // Append to existing file
+        fs.appendFileSync(location, appendHeader + skillContent);
+        installed.push({ tool: tool.name, path: location, mode: 'appended' });
+      } else {
+        // Create new file
+        fs.writeFileSync(location, skillContent);
+        installed.push({ tool: tool.name, path: location, mode: 'created' });
+      }
+      break; // Successfully installed for this tool
+    } catch (err) {
+      // Try next location
+      continue;
+    }
+  }
+}
+
+// Output results
+console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║                   🚀 Mosaic Skill Installed                   ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+
+if (installed.length > 0) {
+  console.log('Installed for:\n');
+  for (const i of installed) {
+    console.log(`  ✅ ${i.tool}`);
+    console.log(`     ${i.path} (${i.mode})\n`);
+  }
+} else {
+  console.log('  ⚠️  Could not auto-detect AI tools.');
+  console.log('     Copy the skill manually from:');
+  console.log('     https://api.mosaic.site/skill.md\n');
+}
+
+console.log(`
+Your AI assistant now knows how to:
+  • Create Mosaic projects with PostgreSQL + pgvector
+  • Design database schemas and execute SQL
+  • Build apps (Node.js, Python, Go, Rust, static, etc.)
+  • Push to Git and deploy to production
+  • Manage storage, auth, and support tickets
+
+Get your API key: https://mosaic.site/dashboard
+
+Usage: Tell your AI "build me an app on Mosaic" and provide your API key.
+`);
+
+// Also offer to fetch latest from URL
+console.log(`
+💡 Tip: Keep the skill updated with:
+   curl -s https://api.mosaic.site/skill.md > CLAUDE.md
+`);

package/index.js

@@ -0,0 +1,65 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Get the Mosaic skill content for AI assistants
+ */
+function getSkillContent() {
+  return fs.readFileSync(
+    path.join(__dirname, 'CLAUDE.md'),
+    'utf8'
+  );
+}
+
+/**
+ * Mosaic API helper for programmatic use
+ */
+class MosaicClient {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    this.baseUrl = 'https://api.mosaic.site/v1/project';
+  }
+
+  async request(method, endpoint, body = null) {
+    const fetch = (await import('node-fetch')).default;
+    const options = {
+      method,
+      headers: {
+        'X-API-Key': this.apiKey,
+        'Content-Type': 'application/json',
+      },
+    };
+    if (body) options.body = JSON.stringify(body);
+
+    const response = await fetch(`${this.baseUrl}${endpoint}`, options);
+    return response.json();
+  }
+
+  // Projects
+  listProjects() { return this.request('GET', '/projects'); }
+  createProject(name) { return this.request('POST', '/projects', { name }); }
+
+  // SQL
+  executeSQL(slug, query, params = []) {
+    return this.request('POST', `/${slug}/sql`, { query, params });
+  }
+
+  // Deploy
+  deploy(slug, repoUrl, branch = 'main') {
+    return this.request('POST', `/${slug}/deploy`, { repo_url: repoUrl, branch });
+  }
+
+  deployStatus(slug) {
+    return this.request('GET', `/${slug}/deploy/status`);
+  }
+
+  // Tickets
+  createTicket(subject, message) {
+    return this.request('POST', '/tickets', { subject, message });
+  }
+}
+
+module.exports = {
+  getSkillContent,
+  MosaicClient,
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mosaicsite/claude-skill",
+  "version": "1.0.0",
+  "description": "Mosaic Platform skill for Claude Code - build and deploy apps instantly",
+  "main": "index.js",
+  "bin": {
+    "mosaic-skill": "./bin/install.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/install.js"
+  },
+  "keywords": [
+    "mosaic",
+    "mosaicsite",
+    "claude",
+    "claude-code",
+    "skill",
+    "paas",
+    "deployment",
+    "supabase-alternative",
+    "ai-coding"
+  ],
+  "author": "Mosaic Platform <support@mosaic.site>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaic.site/mosaic/claude-skill.git"
+  },
+  "homepage": "https://mosaic.site",
+  "bugs": {
+    "url": "https://mosaic.site/support"
+  }
+}