staticx 0.1.2 → 0.1.5

package/README.md

@@ -14,11 +14,13 @@ npm install -g staticx
 staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
 staticx whoami
 staticx guide
+staticx mcp
 ```
 
 `staticx login` stores the credentials locally, verifies them with `GET /user`, and prints the active user, token scope, access level, expiry, and next safe commands.
 
 Use `staticx guide` or `staticx commands` when you want the full command map from the terminal.
+Use `staticx mcp` when you want copy-safe MCP snippets for Claude, Cursor, Codex, Cline, Windsurf, Zed, and generic clients.
 
 ## Core commands
 
@@ -30,9 +32,47 @@ staticx create --workspace-id WORKSPACE_ID --name "Marketing Site"
 staticx create --name "Imported Site" --archive site.zip
 staticx create --name "Imported Site" --source-url "https://example.com"
 staticx deploy --site-id SITE_ID --dir dist
+staticx domain --site-id SITE_ID --domain app.example.com
+staticx domain-status --site-id SITE_ID
 staticx logs --site-id SITE_ID
+staticx mcp
 ```
 
+## Custom domains
+
+Use the CLI when you want to connect a domain without opening the dashboard.
+
+```bash
+staticx domain --site-id SITE_ID --domain app.example.com
+```
+
+The command moves the site to that domain and prints the single DNS record to create. After the DNS record is added, StaticX detects it and activates SSL automatically.
+
+Check progress any time:
+
+```bash
+staticx domain-status --site-id SITE_ID
+```
+
+## Machine-readable sources
+
+Use these when you want the same contract that the dashboard, CLI, and agents share:
+
+- https://staticx.site/llms.txt
+- https://staticx.site/llms-full.txt
+- https://staticx.site/api/v1/openapi.json
+
+## Plan limits
+
+StaticX enforces the same limits through the dashboard, API, CLI, MCP, URL imports, and hosted forms runtime.
+
+| Plan | Sites | Storage | Max upload | Form entries |
+| --- | ---: | ---: | ---: | ---: |
+| Free | 1 | 500 MB | 500 MB | 10,000 |
+| Unlimited | Unlimited | Unlimited | 50 GB | Unlimited |
+
+If a command receives `PLAN_QUOTA_EXCEEDED`, stop and return the exact message. Clean up files/form entries or upgrade before retrying.
+
 ## Token scopes
 
 - Global token: account-wide access for internal operator tools.
@@ -45,8 +85,35 @@ Generate those tokens from:
 - `Project Settings → Agent deploy` for Site
 - `Workspace → Agent deploy` for Workspace
 
+## MCP for AI agents
+
+StaticX MCP uses the separate public package `staticx-mcp-server` and the same scoped API tokens as the CLI.
+
+```json
+{
+  "mcpServers": {
+    "staticx": {
+      "command": "npx",
+      "args": ["-y", "staticx-mcp-server"],
+      "env": {
+        "STATICX_API_TOKEN": "sx_replace_with_your_token",
+        "STATICX_API_BASE_URL": "https://staticx.site/api/v1"
+      }
+    }
+  }
+}
+```
+
+For local HTTP debugging:
+
+```bash
+STATICX_API_TOKEN=sx_replace_with_your_token npx staticx-mcp-server http
+```
+
 ## Notes
 
 - `staticx login` stores the base URL and bearer token locally.
 - `staticx whoami` verifies the token with `GET /user`.
 - `staticx deploy` zips the contents of the given build directory, uploads them, and publishes a new release. The directory must contain `index.html` or `index.htm` plus `404.html` at its root.
+- `staticx domain` calls `POST /projects/{project}/domain` and returns the DNS record plus activation status.
+- Golden deploy prompt: “Deploy `dist` to StaticX project `SITE_ID` using `STATICX_API_TOKEN`. Build, validate `index.html` + `404.html`, apply StaticX form rules if forms exist, zip `dist` root, upload, deploy, check logs, then return the live URL or the exact API error. If you receive `PLAN_QUOTA_EXCEEDED`, stop and return the exact quota message. Never expose the token.”

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staticx",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Public CLI for STATICX using token-authenticated /api/v1 routes.",
   "type": "module",
   "publishConfig": {

package/src/index.js

@@ -10,13 +10,16 @@ import {
   cliGuideJson,
   formatTokenSummary,
   printCliGuide,
+  printDomainSetup,
   printJson,
   printKeyValue,
   printLoginSuccess,
+  printMcpGuide,
   printTable,
+  mcpGuideJson,
 } from './output.js';
 
-const CLI_VERSION = '0.1.2';
+const CLI_VERSION = '0.1.5';
 
 export async function run(argv) {
   const program = new Command();
@@ -31,7 +34,9 @@ export async function run(argv) {
 Common workflow:
   staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
   staticx guide
+  staticx mcp
   staticx deploy --site-id SITE_ID --dir dist
+  staticx domain --site-id SITE_ID --domain app.example.com
 
 Deploy rule:
   The build directory must contain index.html or index.htm and 404.html at its root.
@@ -51,6 +56,19 @@ Deploy rule:
       printCliGuide();
     });
 
+  program
+    .command('mcp')
+    .description('Print MCP setup snippets for Claude, Cursor, Codex, Cline, Windsurf, Zed, and generic clients.')
+    .option('--json', 'Print JSON output')
+    .action((options) => {
+      if (options.json) {
+        printJson(mcpGuideJson());
+        return;
+      }
+
+      printMcpGuide();
+    });
+
   program
     .command('login')
     .description('Store the base URL and token locally, then verify them with GET /user.')
@@ -276,6 +294,47 @@ Deploy rule:
       })));
     });
 
+  program
+    .command('domain')
+    .description('Move a site to a custom domain and print the one DNS record to create.')
+    .requiredOption('--site-id <id>', 'Site ID')
+    .requiredOption('--domain <domain>', 'Custom domain, for example app.example.com')
+    .option('--json', 'Print JSON output')
+    .option('--base-url <url>', 'Override the stored STATICX API base URL')
+    .option('--token <token>', 'Override the stored STATICX bearer token')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.post(`/projects/${options.siteId}/domain`, {
+        json: { domain: options.domain },
+      });
+
+      if (options.json) {
+        printJson(response);
+        return;
+      }
+
+      printDomainSetup(response);
+    });
+
+  program
+    .command('domain-status')
+    .description('Check the custom domain status for one site.')
+    .requiredOption('--site-id <id>', 'Site ID')
+    .option('--json', 'Print JSON output')
+    .option('--base-url <url>', 'Override the stored STATICX API base URL')
+    .option('--token <token>', 'Override the stored STATICX bearer token')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.get(`/projects/${options.siteId}/domain`);
+
+      if (options.json) {
+        printJson(response);
+        return;
+      }
+
+      printDomainSetup({ message: 'Custom domain status.', data: response?.data ?? response }, { statusOnly: true });
+    });
+
   await program.parseAsync(argv);
 }
 

package/src/output.js

@@ -10,6 +10,46 @@ export function printTable(rows) {
   console.table(rows);
 }
 
+export function printDomainSetup(response, { statusOnly = false } = {}) {
+  const data = response?.data ?? {};
+  const project = data.project ?? {};
+  const domain = data.custom_domain ?? null;
+  const records = data.dns?.records ?? [];
+  const steps = Array.isArray(data.steps) ? data.steps : [];
+
+  console.log(response?.message || (statusOnly ? 'Custom domain status.' : 'Custom domain setup started.'));
+  console.log('');
+  printAlignedRows([
+    ['Site', project.name || project.id || 'Unknown'],
+    ['Current URL', project.public_url || 'Pending'],
+    ['Custom domain', domain?.host || 'Not connected'],
+    ['Status', domain?.status_label || data.status?.label || 'Pending'],
+  ]);
+
+  if (domain?.status_message || data.status?.message) {
+    console.log('');
+    console.log(domain?.status_message || data.status?.message);
+  }
+
+  if (records.length > 0) {
+    console.log('');
+    console.log('Create this DNS record:');
+    printTable(records.map((record) => ({
+      type: record.type,
+      name: record.name,
+      value: record.value,
+    })));
+  }
+
+  if (steps.length > 0) {
+    console.log('');
+    console.log('Next steps');
+    steps.forEach((step, index) => {
+      console.log(`  ${index + 1}. ${step}`);
+    });
+  }
+}
+
 export function printLoginSuccess({ baseUrl, user, token }) {
   printBanner();
   console.log('Successfully authenticated.');
@@ -25,6 +65,7 @@ export function printLoginSuccess({ baseUrl, user, token }) {
     ['staticx guide', 'Show the complete CLI workflow.'],
     ['staticx sites', 'List the sites visible to this token.'],
     ['staticx deploy --site-id SITE_ID --dir dist', 'Upload and publish a build folder.'],
+    ['staticx domain --site-id SITE_ID --domain app.example.com', 'Move a site to a custom domain.'],
   ]);
   console.log('');
   console.log('Build rule: deploy folders must include index.html or index.htm and 404.html at the root.');
@@ -53,13 +94,64 @@ export function printCliGuide() {
     ['staticx deploy --site-id SITE_ID --dir dist', 'Zip, upload, and publish a build folder.'],
   ]);
   console.log('');
+  printCommandGroup('Custom domains', [
+    ['staticx domain --site-id SITE_ID --domain app.example.com', 'Move a site to a custom domain and print the DNS record.'],
+    ['staticx domain-status --site-id SITE_ID', 'Check DNS, SSL, and activation status.'],
+  ]);
+  console.log('');
   printCommandGroup('Inspect', [
     ['staticx logs --site-id SITE_ID', 'Read recent site activity.'],
     ['staticx logs --site-id SITE_ID --limit 50', 'Read more rows.'],
   ]);
   console.log('');
+  printCommandGroup('Machine-readable sources', [
+    ['https://staticx.site/llms.txt', 'Short index for agents and crawlers.'],
+    ['https://staticx.site/llms-full.txt', 'Expanded agent playbook with prompts and curl examples.'],
+    ['https://staticx.site/api/v1/openapi.json', 'Canonical OpenAPI schema for the public API.'],
+  ]);
+  console.log('');
   console.log('Token scopes: use Site tokens for one-site deploys, Workspace tokens for client workspaces, and Global tokens only for broad operator workflows.');
   console.log('Build rule: deploy folders must include index.html or index.htm and 404.html at the root.');
+  console.log('Plan limits: Free includes 1 site, 500 MB storage, 500 MB uploads, and 10,000 form entries. Unlimited includes 50 GB uploads with unlimited sites, storage, and form entries.');
+  console.log('Quota rule: stop on PLAN_QUOTA_EXCEEDED and return the exact API message before retrying.');
+}
+
+export function printMcpGuide() {
+  printBanner();
+  console.log('MCP setup for AI agents');
+  console.log('');
+  printCommandGroup('Install and test', [
+    ['npx -y staticx-mcp-server', 'Run the stdio MCP server from any compatible client.'],
+    ['STATICX_API_TOKEN=sx_xxxxx npx staticx-mcp-server http', 'Start local HTTP mode at http://localhost:3100/mcp for debugging.'],
+  ]);
+  console.log('');
+  console.log('Standard MCP config');
+  console.log(JSON.stringify(mcpGuideJson().config, null, 2));
+  console.log('');
+  console.log('Use a site-scoped token for one-site deploys. Rollback and delete tools require explicit confirmation.');
+}
+
+export function mcpGuideJson() {
+  return {
+    package: 'staticx-mcp-server',
+    auth: 'Scoped API token through STATICX_API_TOKEN.',
+    config: {
+      mcpServers: {
+        staticx: {
+          command: 'npx',
+          args: ['-y', 'staticx-mcp-server'],
+          env: {
+            STATICX_API_TOKEN: 'sx_replace_with_your_token',
+            STATICX_API_BASE_URL: 'https://staticx.site/api/v1',
+          },
+        },
+      },
+    },
+    local_http: {
+      command: 'STATICX_API_TOKEN=sx_replace_with_your_token npx staticx-mcp-server http',
+      url: 'http://localhost:3100/mcp',
+    },
+  };
 }
 
 export function cliGuideJson() {
@@ -82,13 +174,31 @@ export function cliGuideJson() {
         'staticx create --name "Imported Site" --source-url "https://example.com"',
         'staticx deploy --site-id SITE_ID --dir dist',
       ],
+      domains: [
+        'staticx domain --site-id SITE_ID --domain app.example.com',
+        'staticx domain-status --site-id SITE_ID',
+      ],
       inspect: [
         'staticx logs --site-id SITE_ID',
         'staticx logs --site-id SITE_ID --limit 50',
       ],
+      mcp: [
+        'staticx mcp',
+        'npx -y staticx-mcp-server',
+      ],
     },
+    machine_readable: [
+      'https://staticx.site/llms.txt',
+      'https://staticx.site/llms-full.txt',
+      'https://staticx.site/api/v1/openapi.json',
+    ],
     build_rule: 'Deploy folders must include index.html or index.htm and 404.html at the root.',
     token_scopes: 'Use Site tokens for one-site deploys, Workspace tokens for client workspaces, and Global tokens only for broad operator workflows.',
+    plan_limits: {
+      free: '1 site, 500 MB storage, 500 MB max upload, 10,000 form entries.',
+      unlimited: 'Unlimited sites, unlimited storage, 50 GB max upload, unlimited form entries.',
+    },
+    quota_rule: 'Stop on PLAN_QUOTA_EXCEEDED and return the exact API message.',
   };
 }