staticx 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# STATICX CLI
+
+`staticx` is the public CLI for STATICX. It uses the same token-authenticated `/api/v1` contract as the dashboard, the agent instructions, and the MCP server.
+
+## Install
+
+```bash
+npm install -g staticx
+```
+
+## Login
+
+```bash
+staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
+staticx whoami
+```
+
+## Core commands
+
+```bash
+staticx workspaces
+staticx sites --workspace-id WORKSPACE_ID
+staticx create --workspace-id WORKSPACE_ID --name "Marketing Site"
+staticx deploy --site-id SITE_ID --dir dist
+staticx logs --site-id SITE_ID
+```
+
+## Token scopes
+
+- Global token: account-wide access for internal operator tools.
+- Site token: one-site deploys, logs, and release verification.
+- Workspace token: several sites inside one workspace.
+
+Generate those tokens from:
+
+- `Settings → API tokens` for Global
+- `Project Settings → Agent deploy` for Site
+- `Workspace → Agent deploy` for Workspace
+
+## 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, runs a build check, and publishes the successful build.

package/bin/staticx.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "staticx",
+  "version": "0.1.0",
+  "description": "Public CLI for STATICX using token-authenticated /api/v1 routes.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/madprodworks-coder/static_site.git",
+    "directory": "packages/staticx-cli"
+  },
+  "homepage": "https://staticx.site/documentation/cli",
+  "bin": {
+    "staticx": "./bin/staticx.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "keywords": [
+    "staticx",
+    "cli",
+    "static-sites",
+    "deployment",
+    "laravel"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yazl": "^3.3.1"
+  }
+}

package/src/archive.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { once } from 'node:events';
+import yazl from 'yazl';
+
+export async function createZipFromDirectory(directoryPath) {
+  const sourceDirectory = path.resolve(directoryPath);
+  const stats = await fsp.stat(sourceDirectory).catch(() => null);
+
+  if (!stats || !stats.isDirectory()) {
+    throw new Error(`Build directory not found: ${sourceDirectory}`);
+  }
+
+  await assertEntryHtmlExists(sourceDirectory);
+
+  const tempPath = path.join(
+    await fsp.mkdtemp(path.join(os.tmpdir(), 'staticx-cli-')),
+    `site-${Date.now()}.zip`,
+  );
+
+  const zipFile = new yazl.ZipFile();
+  const output = fs.createWriteStream(tempPath);
+  zipFile.outputStream.pipe(output);
+
+  for (const filePath of await collectFiles(sourceDirectory)) {
+    const relativePath = path.relative(sourceDirectory, filePath).replaceAll(path.sep, '/');
+    zipFile.addFile(filePath, relativePath);
+  }
+
+  zipFile.end();
+  await once(output, 'close');
+
+  return tempPath;
+}
+
+async function assertEntryHtmlExists(directoryPath) {
+  const candidates = ['index.html', 'index.htm'];
+
+  for (const candidate of candidates) {
+    try {
+      const stats = await fsp.stat(path.join(directoryPath, candidate));
+      if (stats.isFile()) {
+        return;
+      }
+    } catch {
+      // Keep checking.
+    }
+  }
+
+  throw new Error('Build directory must contain index.html or index.htm at its root.');
+}
+
+async function collectFiles(directoryPath) {
+  const entries = await fsp.readdir(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const entryPath = path.join(directoryPath, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(entryPath));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(entryPath);
+    }
+  }
+
+  return files;
+}

package/src/auth.js

@@ -0,0 +1,28 @@
+import { loadConfig, normalizeBaseUrl, saveConfig } from './config.js';
+
+export async function resolveRuntimeAuth(options = {}) {
+  const config = await loadConfig();
+  const baseUrl = options.baseUrl || process.env.STATICX_API_BASE_URL || config.baseUrl;
+  const token = options.token || process.env.STATICX_API_TOKEN || config.token;
+
+  if (!baseUrl) {
+    throw new Error('No STATICX base URL found. Pass --base-url or run `staticx login` first.');
+  }
+
+  if (!token) {
+    throw new Error('No STATICX token found. Pass --token or run `staticx login` first.');
+  }
+
+  return {
+    baseUrl: normalizeBaseUrl(baseUrl),
+    token: String(token).trim(),
+  };
+}
+
+export async function persistLogin(baseUrl, token) {
+  await saveConfig({
+    baseUrl: normalizeBaseUrl(baseUrl),
+    token: String(token).trim(),
+    updatedAt: new Date().toISOString(),
+  });
+}

package/src/config.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const APP_DIR = 'staticx';
+const CONFIG_FILE = 'config.json';
+
+export function resolveConfigDir() {
+  if (process.env.STATICX_CONFIG_DIR) {
+    return process.env.STATICX_CONFIG_DIR;
+  }
+
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), APP_DIR);
+  }
+
+  if (process.env.XDG_CONFIG_HOME) {
+    return path.join(process.env.XDG_CONFIG_HOME, APP_DIR);
+  }
+
+  return path.join(os.homedir(), '.config', APP_DIR);
+}
+
+export function resolveConfigPath() {
+  return path.join(resolveConfigDir(), CONFIG_FILE);
+}
+
+export async function loadConfig() {
+  try {
+    const content = await fs.readFile(resolveConfigPath(), 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return {};
+    }
+
+    throw new Error(`Could not read STATICX CLI config: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export async function saveConfig(config) {
+  const configDir = resolveConfigDir();
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.writeFile(resolveConfigPath(), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+export async function clearConfig() {
+  try {
+    await fs.unlink(resolveConfigPath());
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return;
+    }
+
+    throw error;
+  }
+}
+
+export function normalizeBaseUrl(baseUrl) {
+  const value = String(baseUrl || '').trim().replace(/\/+$/, '');
+
+  if (value === '') {
+    throw new Error('STATICX base URL is required. Pass --base-url or run `staticx login` first.');
+  }
+
+  try {
+    const url = new URL(value);
+
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw new Error('STATICX base URL must use http or https.');
+    }
+
+    return url.toString().replace(/\/+$/, '');
+  } catch (error) {
+    throw new Error(`Invalid STATICX base URL: ${value}`);
+  }
+}

package/src/files.js

@@ -0,0 +1,10 @@
+import fs from 'node:fs/promises';
+
+export async function fileToBlob(filePath, type = 'application/octet-stream') {
+  if (typeof fs.openAsBlob === 'function') {
+    return fs.openAsBlob(filePath, { type });
+  }
+
+  const buffer = await fs.readFile(filePath);
+  return new Blob([buffer], { type });
+}

package/src/http.js

@@ -0,0 +1,101 @@
+export class StaticxApiError extends Error {
+  constructor(message, { status, payload } = {}) {
+    super(message);
+    this.name = 'StaticxApiError';
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export class StaticxApiClient {
+  constructor({ baseUrl, token, fetchImpl = fetch }) {
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.token = token;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async get(path, options = {}) {
+    return this.request(path, { method: 'GET', ...options });
+  }
+
+  async post(path, options = {}) {
+    return this.request(path, { method: 'POST', ...options });
+  }
+
+  async delete(path, options = {}) {
+    return this.request(path, { method: 'DELETE', ...options });
+  }
+
+  async request(path, { method = 'GET', query, json, formData } = {}) {
+    const url = new URL(path.replace(/^\//, ''), `${this.baseUrl}/`);
+
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === '') {
+          continue;
+        }
+
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const headers = {
+      Accept: 'application/json',
+      Authorization: `Bearer ${this.token}`,
+    };
+
+    let body;
+
+    if (formData) {
+      body = formData;
+    } else if (json !== undefined) {
+      body = JSON.stringify(json);
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const response = await this.fetchImpl(url, {
+      method,
+      headers,
+      body,
+    });
+
+    const payload = await parsePayload(response);
+
+    if (!response.ok) {
+      throw new StaticxApiError(apiErrorMessage(payload, response), {
+        status: response.status,
+        payload,
+      });
+    }
+
+    return payload;
+  }
+}
+
+async function parsePayload(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+
+  if (text === '') {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+function apiErrorMessage(payload, response) {
+  if (payload && typeof payload === 'object' && 'message' in payload && payload.message) {
+    return String(payload.message);
+  }
+
+  return `${response.status} ${response.statusText}`.trim();
+}

package/src/index.js

@@ -0,0 +1,283 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Command } from 'commander';
+import { createZipFromDirectory } from './archive.js';
+import { resolveRuntimeAuth, persistLogin } from './auth.js';
+import { clearConfig, normalizeBaseUrl } from './config.js';
+import { fileToBlob } from './files.js';
+import { StaticxApiClient } from './http.js';
+import { formatTokenSummary, printJson, printKeyValue, printTable } from './output.js';
+
+export async function run(argv) {
+  const program = new Command();
+
+  program
+    .name('staticx')
+    .description('Public CLI for STATICX using token-authenticated /api/v1 routes.')
+    .version('0.1.0')
+    .option('--base-url <url>', 'STATICX API base URL, for example https://staticx.site/api/v1')
+    .option('--token <token>', 'STATICX bearer token')
+    .showHelpAfterError();
+
+  program
+    .command('login')
+    .description('Store the base URL and token locally, then verify them with GET /user.')
+    .requiredOption('--base-url <url>', 'STATICX API base URL')
+    .requiredOption('--token <token>', 'STATICX bearer token')
+    .option('--json', 'Print JSON output')
+    .action(async (options) => {
+      const baseUrl = normalizeBaseUrl(options.baseUrl);
+      const token = String(options.token).trim();
+      const client = new StaticxApiClient({ baseUrl, token });
+      const response = await client.get('/user');
+
+      await persistLogin(baseUrl, token);
+
+      if (options.json) {
+        printJson({
+          message: 'Login successful.',
+          base_url: baseUrl,
+          user: response?.data ?? null,
+        });
+        return;
+      }
+
+      console.log('Login successful.');
+      printKeyValue('Base URL', baseUrl);
+      printKeyValue('User', response?.data?.email || response?.data?.name || 'Unknown');
+      printKeyValue('Token', formatTokenSummary(response?.data?.current_token || response?.data?.token));
+    });
+
+  program
+    .command('logout')
+    .description('Remove the locally stored STATICX CLI credentials.')
+    .action(async () => {
+      await clearConfig();
+      console.log('Local STATICX CLI credentials removed.');
+    });
+
+  program
+    .command('whoami')
+    .description('Verify the stored token and print the current user/token metadata.')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.get('/user');
+
+      if (options.json) {
+        printJson(response?.data ?? null);
+        return;
+      }
+
+      const user = response?.data ?? {};
+      console.log(user.name || user.email || 'Unknown user');
+      if (user.email) {
+        printKeyValue('Email', user.email);
+      }
+      printKeyValue('Token', formatTokenSummary(user.current_token || user.token));
+    });
+
+  program
+    .command('workspaces')
+    .description('List workspaces visible to the current token.')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.get('/workspaces');
+      const workspaces = response?.data ?? [];
+
+      if (options.json) {
+        printJson(workspaces);
+        return;
+      }
+
+      printTable(workspaces.map((workspace) => ({
+        id: workspace.id,
+        name: workspace.name,
+        role: workspace.role,
+        sites: workspace.projects_count,
+      })));
+    });
+
+  program
+    .command('sites')
+    .description('List sites visible to the current token, optionally filtered by workspace.')
+    .option('--workspace-id <id>', 'Filter by workspace ID')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.get('/projects', {
+        query: options.workspaceId ? { workspace_id: options.workspaceId } : undefined,
+      });
+      const sites = response?.data ?? [];
+
+      if (options.json) {
+        printJson(sites);
+        return;
+      }
+
+      printTable(sites.map((site) => ({
+        id: site.id,
+        name: site.name,
+        host: site.host,
+        workspace: site.workspace?.name || '',
+        status: site.status,
+      })));
+    });
+
+  program
+    .command('create')
+    .description('Create a new site, optionally inside a workspace or from a ZIP/source URL.')
+    .requiredOption('--name <name>', 'Site name')
+    .option('--workspace-id <id>', 'Workspace ID')
+    .option('--description <description>', 'Site description')
+    .option('--archive <path>', 'ZIP archive path to seed the site')
+    .option('--source-url <url>', 'Public URL to import into the site')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      if (options.archive && options.sourceUrl) {
+        throw new Error('Use either --archive or --source-url, not both.');
+      }
+
+      const client = await clientFromCommand(command);
+      const response = options.archive || options.sourceUrl
+        ? await client.post('/projects', {
+            formData: await createProjectFormData(options),
+          })
+        : await client.post('/projects', {
+            json: compactObject({
+              workspace_id: options.workspaceId,
+              name: options.name,
+              description: options.description,
+            }),
+          });
+
+      if (options.json) {
+        printJson(response);
+        return;
+      }
+
+      const project = response?.data ?? {};
+      console.log('Site created.');
+      printKeyValue('ID', project.id ?? 'Unknown');
+      printKeyValue('Name', project.name ?? options.name);
+      printKeyValue('Host', project.host || 'Pending');
+      printKeyValue('Public URL', project.public_url || 'Pending');
+    });
+
+  program
+    .command('deploy')
+    .description('Zip a local build directory, upload it, build-check it, and publish it to one site.')
+    .requiredOption('--site-id <id>', 'Site ID')
+    .requiredOption('--dir <path>', 'Built site directory, for example dist')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const zipPath = await createZipFromDirectory(options.dir);
+
+      try {
+        const uploadFormData = new FormData();
+        uploadFormData.set('mode', 'zip');
+        uploadFormData.set('overwrite_confirmed', '1');
+        uploadFormData.set('archive', await fileToBlob(zipPath, 'application/zip'), path.basename(zipPath));
+
+        const upload = await client.post(`/projects/${options.siteId}/files`, { formData: uploadFormData });
+        const build = await client.post(`/projects/${options.siteId}/builds`);
+        const buildId = build?.data?.id;
+
+        if (!buildId) {
+          throw new Error('Build response did not include a build ID.');
+        }
+
+        const deployment = await client.post(`/projects/${options.siteId}/deployments`, {
+          json: { build_id: buildId },
+        });
+        const project = await client.get(`/projects/${options.siteId}`);
+
+        const result = {
+          project: project?.data ?? null,
+          upload: upload?.data ?? null,
+          build: build?.data ?? null,
+          deployment: deployment?.data ?? null,
+        };
+
+        if (options.json) {
+          printJson(result);
+          return;
+        }
+
+        console.log('Deployment completed.');
+        printKeyValue('Site', result.project?.name || options.siteId);
+        printKeyValue('Build', result.build?.id || 'Unknown');
+        printKeyValue('Deployment', result.deployment?.id || 'Unknown');
+        printKeyValue('Public URL', result.project?.public_url || 'Pending');
+      } finally {
+        await fs.rm(path.dirname(zipPath), { recursive: true, force: true });
+      }
+    });
+
+  program
+    .command('logs')
+    .description('Read recent activity logs for one site.')
+    .requiredOption('--site-id <id>', 'Site ID')
+    .option('--limit <number>', 'Maximum number of log rows', '25')
+    .option('--json', 'Print JSON output')
+    .action(async (options, command) => {
+      const client = await clientFromCommand(command);
+      const response = await client.get(`/projects/${options.siteId}/logs`, {
+        query: { limit: options.limit },
+      });
+      const logs = response?.data ?? [];
+
+      if (options.json) {
+        printJson(logs);
+        return;
+      }
+
+      printTable(logs.map((entry) => ({
+        time: entry.created_at,
+        level: entry.level,
+        event: entry.event,
+        message: entry.message,
+      })));
+    });
+
+  await program.parseAsync(argv);
+}
+
+async function clientFromCommand(command) {
+  const options = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
+  const auth = await resolveRuntimeAuth(options);
+
+  return new StaticxApiClient(auth);
+}
+
+async function createProjectFormData(options) {
+  const formData = new FormData();
+  formData.set('name', options.name);
+
+  if (options.workspaceId) {
+    formData.set('workspace_id', String(options.workspaceId));
+  }
+
+  if (options.description) {
+    formData.set('description', options.description);
+  }
+
+  if (options.archive) {
+    const archivePath = path.resolve(options.archive);
+    formData.set('archive', await fileToBlob(archivePath, 'application/zip'), path.basename(archivePath));
+  }
+
+  if (options.sourceUrl) {
+    formData.set('source_url', options.sourceUrl);
+  }
+
+  return formData;
+}
+
+function compactObject(values) {
+  return Object.fromEntries(
+    Object.entries(values).filter(([, value]) => value !== undefined && value !== null && value !== ''),
+  );
+}

package/src/output.js

@@ -0,0 +1,23 @@
+export function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function printKeyValue(label, value) {
+  console.log(`${label}: ${value}`);
+}
+
+export function printTable(rows) {
+  console.table(rows);
+}
+
+export function formatTokenSummary(token) {
+  if (!token) {
+    return 'No token metadata returned.';
+  }
+
+  const scope = token.scope_label || token.scope_type || token.kind || 'Unknown scope';
+  const preset = token.preset_label || token.preset || 'Unknown access level';
+  const expiry = token.expires_at || 'Never expires';
+
+  return `${scope} · ${preset} · ${expiry}`;
+}