shsu 0.0.6 → 0.0.8

package/README.md

@@ -171,6 +171,7 @@ Add to `.cursor/mcp.json` in your project:
 - `restart` - Restart edge-runtime
 - `new` - Create new function from template
 - `config` - Show current configuration
+- `docs` - Get setup documentation
 
 ## Releasing
 

package/bin/shsu.mjs

@@ -428,6 +428,11 @@ async function cmdMcp() {
       description: 'Run SQL migrations on the database. Syncs migration files via rsync and executes them via psql.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'docs',
+      description: 'Get documentation on how to set up and use shsu for deploying Supabase Edge Functions.',
+      inputSchema: { type: 'object', properties: {} },
+    },
   ];
 
   const serverInfo = {
@@ -460,7 +465,18 @@ async function cmdMcp() {
     switch (name) {
       case 'deploy': {
         if (!config.server || !config.remotePath) {
-          return { content: [{ type: 'text', text: 'Error: server and remotePath must be configured. Run "shsu init" first.' }] };
+          return { content: [{ type: 'text', text: `Error: server and remotePath must be configured.
+
+To fix, add to package.json:
+{
+  "shsu": {
+    "server": "root@your-server.com",
+    "remotePath": "/data/coolify/services/xxx/volumes/functions"
+  }
+}
+
+Find remotePath by running on your server:
+  docker inspect $(docker ps -q --filter 'name=edge') | grep -A 5 "Mounts"` }] };
         }
         const funcName = args.name;
         const noRestart = args.noRestart || false;
@@ -471,7 +487,9 @@ async function cmdMcp() {
         } else {
           const funcPath = join(config.localPath, funcName);
           if (!existsSync(funcPath)) {
-            return { content: [{ type: 'text', text: `Error: Function not found: ${funcPath}` }] };
+            return { content: [{ type: 'text', text: `Error: Function not found: ${funcPath}
+
+To fix, create the function first using the 'new' tool with name: "${funcName}"` }] };
           }
           output = captureExec(`rsync -avz "${funcPath}/" "${config.server}:${config.remotePath}/${funcName}/"`);
         }
@@ -485,7 +503,18 @@ async function cmdMcp() {
 
       case 'list': {
         if (!config.server || !config.remotePath) {
-          return { content: [{ type: 'text', text: 'Error: server and remotePath must be configured.' }] };
+          return { content: [{ type: 'text', text: `Error: server and remotePath must be configured.
+
+To fix, add to package.json:
+{
+  "shsu": {
+    "server": "root@your-server.com",
+    "remotePath": "/data/coolify/services/xxx/volumes/functions"
+  }
+}
+
+Find remotePath by running on your server:
+  docker inspect $(docker ps -q --filter 'name=edge') | grep -A 5 "Mounts"` }] };
         }
         const remote = captureExec(`ssh ${config.server} "ls -1 ${config.remotePath} 2>/dev/null"`) || '(none)';
         let local = '(none)';
@@ -500,10 +529,19 @@ async function cmdMcp() {
 
       case 'invoke': {
         if (!config.url) {
-          return { content: [{ type: 'text', text: 'Error: url must be configured for invoke.' }] };
+          return { content: [{ type: 'text', text: `Error: url must be configured for invoke.
+
+To fix, add to package.json:
+{
+  "shsu": {
+    "url": "https://your-supabase.example.com"
+  }
+}` }] };
         }
         if (!args.name) {
-          return { content: [{ type: 'text', text: 'Error: function name is required.' }] };
+          return { content: [{ type: 'text', text: `Error: function name is required.
+
+Usage: invoke tool with { "name": "function-name", "data": "{\\"key\\": \\"value\\"}" }` }] };
         }
         const data = args.data || '{}';
         const output = captureExec(`curl -s -X POST "${config.url}/functions/v1/${args.name}" -H "Content-Type: application/json" -d '${data}'`);
@@ -512,7 +550,14 @@ async function cmdMcp() {
 
       case 'restart': {
         if (!config.server) {
-          return { content: [{ type: 'text', text: 'Error: server must be configured.' }] };
+          return { content: [{ type: 'text', text: `Error: server must be configured.
+
+To fix, add to package.json:
+{
+  "shsu": {
+    "server": "root@your-server.com"
+  }
+}` }] };
         }
         const output = captureExec(`ssh ${config.server} "docker restart \\$(docker ps -q --filter 'name=${config.edgeContainer}')"`);
         return { content: [{ type: 'text', text: `Restarted edge-runtime\n\n${output}` }] };
@@ -520,11 +565,15 @@ async function cmdMcp() {
 
       case 'new': {
         if (!args.name) {
-          return { content: [{ type: 'text', text: 'Error: function name is required.' }] };
+          return { content: [{ type: 'text', text: `Error: function name is required.
+
+Usage: new tool with { "name": "my-function-name" }` }] };
         }
         const funcPath = join(config.localPath, args.name);
         if (existsSync(funcPath)) {
-          return { content: [{ type: 'text', text: `Error: Function already exists: ${args.name}` }] };
+          return { content: [{ type: 'text', text: `Error: Function already exists: ${args.name}
+
+The function already exists at ${funcPath}. To update it, edit the code and use the 'deploy' tool.` }] };
         }
         mkdirSync(funcPath, { recursive: true });
         writeFileSync(
@@ -560,16 +609,35 @@ async function cmdMcp() {
 
       case 'migrate': {
         if (!config.server) {
-          return { content: [{ type: 'text', text: 'Error: server must be configured.' }] };
+          return { content: [{ type: 'text', text: `Error: server must be configured.
+
+To fix, add to package.json:
+{
+  "shsu": {
+    "server": "root@your-server.com"
+  }
+}` }] };
         }
         if (!existsSync(config.migrationsPath)) {
-          return { content: [{ type: 'text', text: `Error: Migrations folder not found: ${config.migrationsPath}` }] };
+          return { content: [{ type: 'text', text: `Error: Migrations folder not found: ${config.migrationsPath}
+
+To fix, create the migrations directory and add .sql files:
+  mkdir -p ${config.migrationsPath}
+
+Then add migration files like:
+  ${config.migrationsPath}/001_create_tables.sql
+  ${config.migrationsPath}/002_add_indexes.sql` }] };
         }
         const migrations = readdirSync(config.migrationsPath)
           .filter((f) => f.endsWith('.sql'))
           .sort();
         if (migrations.length === 0) {
-          return { content: [{ type: 'text', text: 'No migration files found.' }] };
+          return { content: [{ type: 'text', text: `No migration files found in ${config.migrationsPath}
+
+Add .sql files to the migrations folder, e.g.:
+  ${config.migrationsPath}/001_create_tables.sql
+
+Files are executed alphabetically, so use numeric prefixes for ordering.` }] };
         }
         let output = `Found ${migrations.length} migration(s): ${migrations.join(', ')}\n\n`;
         // Sync migrations
@@ -577,7 +645,17 @@ async function cmdMcp() {
         // Find db container
         const dbContainer = captureExec(`ssh ${config.server} "docker ps -q --filter 'name=${config.dbContainer}'"`);
         if (!dbContainer) {
-          return { content: [{ type: 'text', text: `Error: Database container not found (filter: ${config.dbContainer})` }] };
+          return { content: [{ type: 'text', text: `Error: Database container not found (filter: ${config.dbContainer})
+
+To fix:
+1. SSH to your server and run: docker ps
+2. Find the postgres container name (e.g., abc123-supabase-db-1)
+3. Update dbContainer in package.json to match a unique part of the name:
+{
+  "shsu": {
+    "dbContainer": "supabase-db"
+  }
+}` }] };
         }
         // Run migrations
         for (const migration of migrations) {
@@ -588,6 +666,93 @@ async function cmdMcp() {
         return { content: [{ type: 'text', text: output }] };
       }
 
+      case 'docs': {
+        return {
+          content: [{
+            type: 'text',
+            text: `# shsu - Self-Hosted Supabase Utilities
+
+Deploy and manage Supabase Edge Functions on Coolify-hosted Supabase.
+
+## Project Setup
+
+1. **Configure shsu** by adding to package.json:
+\`\`\`json
+{
+  "shsu": {
+    "server": "root@your-coolify-server",
+    "remotePath": "/data/coolify/services/YOUR_SERVICE_ID/volumes/functions",
+    "url": "https://your-supabase.example.com",
+    "edgeContainer": "edge",
+    "dbContainer": "postgres"
+  }
+}
+\`\`\`
+
+Or run \`npx shsu init\` for interactive setup.
+
+2. **Find configuration values** by SSH'ing to your server:
+   - Container names: \`docker ps\` (Coolify uses pattern \`<service>-<uuid>\`)
+   - Remote path: \`docker inspect $(docker ps -q --filter 'name=edge') | grep -A 5 "Mounts"\`
+
+## Directory Structure
+
+\`\`\`
+your-project/
+├── package.json          # Contains shsu config
+├── supabase/
+│   ├── functions/        # Edge functions (default localPath)
+│   │   ├── hello-world/
+│   │   │   └── index.ts
+│   │   └── another-func/
+│   │       └── index.ts
+│   └── migrations/       # SQL migrations (default migrationsPath)
+│       ├── 001_create_users.sql
+│       └── 002_add_indexes.sql
+\`\`\`
+
+## Configuration Options
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| server | Yes | - | SSH host (e.g., root@server.com) |
+| remotePath | Yes | - | Remote path to functions directory |
+| url | For invoke | - | Supabase URL |
+| localPath | No | ./supabase/functions | Local functions path |
+| migrationsPath | No | ./supabase/migrations | Local migrations path |
+| edgeContainer | No | edge | Edge runtime container filter |
+| dbContainer | No | postgres | Database container filter |
+
+## Edge Function Template
+
+Use \`new\` tool to create functions. Each function needs an index.ts:
+
+\`\`\`typescript
+Deno.serve(async (req) => {
+  const { name } = await req.json()
+  return new Response(
+    JSON.stringify({ message: \`Hello \${name}!\` }),
+    { headers: { "Content-Type": "application/json" } }
+  )
+})
+\`\`\`
+
+## Workflow
+
+1. Create function: \`new\` tool with function name
+2. Edit the function code in supabase/functions/<name>/index.ts
+3. Deploy: \`deploy\` tool (syncs via rsync, restarts edge-runtime)
+4. Test: \`invoke\` tool with JSON data
+5. Debug: Check logs on the server
+
+## Migrations
+
+Place .sql files in supabase/migrations/. They execute alphabetically.
+Use \`migrate\` tool to run all migrations via psql in the database container.`,
+          }],
+        };
+      }
+
       default:
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shsu",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "CLI for deploying and managing Supabase Edge Functions on self-hosted Supabase (Coolify, Docker Compose). Sync functions via rsync, stream logs, and invoke endpoints.",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"