staticx 0.1.1 → 0.1.3

package/README.md

@@ -13,18 +13,44 @@ npm install -g staticx
 ```bash
 staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
 staticx whoami
+staticx guide
 ```
 
+`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.
+
 ## Core commands
 
 ```bash
+staticx guide
 staticx workspaces
 staticx sites --workspace-id WORKSPACE_ID
 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
 ```
 
+## 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
+```
+
 ## Token scopes
 
 - Global token: account-wide access for internal operator tools.
@@ -41,4 +67,5 @@ Generate those tokens from:
 
 - `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.
+- `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staticx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Public CLI for STATICX using token-authenticated /api/v1 routes.",
   "type": "module",
   "publishConfig": {
@@ -35,7 +35,7 @@
     "node": ">=18.17"
   },
   "dependencies": {
-    "commander": "^12.1.0",
+    "commander": "^13.1.0",
     "yazl": "^3.3.1"
   }
 }

package/src/archive.js

@@ -13,7 +13,7 @@ export async function createZipFromDirectory(directoryPath) {
     throw new Error(`Build directory not found: ${sourceDirectory}`);
   }
 
-  await assertEntryHtmlExists(sourceDirectory);
+  await assertRequiredRootFilesExist(sourceDirectory);
 
   const tempPath = path.join(
     await fsp.mkdtemp(path.join(os.tmpdir(), 'staticx-cli-')),
@@ -35,21 +35,37 @@ export async function createZipFromDirectory(directoryPath) {
   return tempPath;
 }
 
-async function assertEntryHtmlExists(directoryPath) {
-  const candidates = ['index.html', 'index.htm'];
+async function assertRequiredRootFilesExist(directoryPath) {
+  const hasEntryHtml = await fileExists(directoryPath, ['index.html', 'index.htm']);
+  const hasNotFoundHtml = await fileExists(directoryPath, ['404.html']);
+  const missing = [];
 
+  if (!hasEntryHtml) {
+    missing.push('index.html or index.htm');
+  }
+
+  if (!hasNotFoundHtml) {
+    missing.push('404.html');
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Build directory must contain required root files: ${missing.join(', ')}.`);
+  }
+}
+
+async function fileExists(directoryPath, candidates) {
   for (const candidate of candidates) {
     try {
       const stats = await fsp.stat(path.join(directoryPath, candidate));
       if (stats.isFile()) {
-        return;
+        return true;
       }
     } catch {
       // Keep checking.
     }
   }
 
-  throw new Error('Build directory must contain index.html or index.htm at its root.');
+  return false;
 }
 
 async function collectFiles(directoryPath) {

package/src/index.js

@@ -6,7 +6,18 @@ 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';
+import {
+  cliGuideJson,
+  formatTokenSummary,
+  printCliGuide,
+  printDomainSetup,
+  printJson,
+  printKeyValue,
+  printLoginSuccess,
+  printTable,
+} from './output.js';
+
+const CLI_VERSION = '0.1.3';
 
 export async function run(argv) {
   const program = new Command();
@@ -14,8 +25,33 @@ export async function run(argv) {
   program
     .name('staticx')
     .description('Public CLI for STATICX using token-authenticated /api/v1 routes.')
-    .version('0.1.1')
-    .showHelpAfterError();
+    .version(CLI_VERSION)
+    .showHelpAfterError()
+    .addHelpText('after', `
+
+Common workflow:
+  staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
+  staticx guide
+  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.
+`);
+
+  program
+    .command('guide')
+    .alias('commands')
+    .description('Explain the STATICX CLI commands and the recommended release workflow.')
+    .option('--json', 'Print JSON output')
+    .action((options) => {
+      if (options.json) {
+        printJson(cliGuideJson());
+        return;
+      }
+
+      printCliGuide();
+    });
 
   program
     .command('login')
@@ -40,10 +76,11 @@ export async function run(argv) {
         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));
+      printLoginSuccess({
+        baseUrl,
+        user: response?.data ?? null,
+        token: response?.data?.current_token || response?.data?.token,
+      });
     });
 
   program
@@ -173,7 +210,7 @@ export async function run(argv) {
 
   program
     .command('deploy')
-    .description('Zip a local build directory, upload it, build-check it, and publish it to one site.')
+    .description('Zip a local build directory, upload 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')
@@ -190,22 +227,12 @@ export async function run(argv) {
         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 deployment = await client.post(`/projects/${options.siteId}/deployments`);
         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,
         };
 
@@ -216,7 +243,6 @@ export async function run(argv) {
 
         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 {
@@ -252,6 +278,47 @@ export async function run(argv) {
       })));
     });
 
+  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,138 @@ 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.');
+  console.log('');
+  printAlignedRows([
+    ['Base URL', baseUrl],
+    ['User', user?.email || user?.name || 'Unknown'],
+    ['Token', formatTokenSummary(token)],
+  ]);
+  console.log('');
+  printCommandGroup('Next commands', [
+    ['staticx whoami', 'Verify the stored 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.');
+}
+
+export function printCliGuide() {
+  printBanner();
+  console.log('Command guide');
+  console.log('');
+  printCommandGroup('Authenticate', [
+    ['staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"', 'Store and verify a token.'],
+    ['staticx whoami', 'Print the current user and token scope.'],
+    ['staticx logout', 'Remove local CLI credentials.'],
+  ]);
+  console.log('');
+  printCommandGroup('Browse account state', [
+    ['staticx workspaces', 'List visible workspaces.'],
+    ['staticx sites', 'List visible sites.'],
+    ['staticx sites --workspace-id WORKSPACE_ID', 'List sites inside one workspace.'],
+  ]);
+  console.log('');
+  printCommandGroup('Create and publish', [
+    ['staticx create --workspace-id WORKSPACE_ID --name "Marketing Site"', 'Create a site.'],
+    ['staticx create --name "Imported Site" --archive site.zip', 'Create a site from a ZIP archive.'],
+    ['staticx create --name "Imported Site" --source-url "https://example.com"', 'Import from a public URL.'],
+    ['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('');
+  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.');
+}
+
+export function cliGuideJson() {
+  return {
+    install: 'npm install -g staticx',
+    commands: {
+      authenticate: [
+        'staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"',
+        'staticx whoami',
+        'staticx logout',
+      ],
+      browse: [
+        'staticx workspaces',
+        'staticx sites',
+        'staticx sites --workspace-id WORKSPACE_ID',
+      ],
+      publish: [
+        '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',
+      ],
+      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',
+      ],
+    },
+    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.',
+  };
+}
+
 export function formatTokenSummary(token) {
   if (!token) {
     return 'No token metadata returned.';
@@ -17,7 +149,48 @@ export function formatTokenSummary(token) {
 
   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';
+  const expiry = formatTokenExpiry(token.expires_at);
 
   return `${scope} · ${preset} · ${expiry}`;
 }
+
+function printBanner() {
+  console.log('  ____  _        _   _      __  __');
+  console.log(' / ___|| |_ __ _| |_(_) ___ \\ \\/ /');
+  console.log(' \\___ \\| __/ _` | __| |/ __| \\  /');
+  console.log('  ___) | || (_| | |_| | (__  /  \\');
+  console.log(' |____/ \\__\\__,_|\\__|_|\\___|/_/\\_\\');
+  console.log('');
+}
+
+function printAlignedRows(rows) {
+  const width = Math.max(...rows.map(([label]) => label.length));
+
+  for (const [label, value] of rows) {
+    console.log(`${label.padEnd(width)}  ${value}`);
+  }
+}
+
+function printCommandGroup(title, rows) {
+  console.log(title);
+
+  const width = Math.max(...rows.map(([command]) => command.length));
+
+  for (const [command, description] of rows) {
+    console.log(`  ${command.padEnd(width)}  ${description}`);
+  }
+}
+
+function formatTokenExpiry(expiresAt) {
+  if (!expiresAt) {
+    return 'Never expires';
+  }
+
+  const date = new Date(expiresAt);
+
+  if (Number.isNaN(date.getTime())) {
+    return String(expiresAt);
+  }
+
+  return `expires ${date.toISOString().slice(0, 16).replace('T', ' ')} UTC`;
+}