staticx 0.1.0 → 0.1.2

package/README.md

@@ -13,14 +13,22 @@ 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 logs --site-id SITE_ID
 ```
@@ -41,4 +49,4 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staticx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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,17 @@ 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,
+  printJson,
+  printKeyValue,
+  printLoginSuccess,
+  printTable,
+} from './output.js';
+
+const CLI_VERSION = '0.1.2';
 
 export async function run(argv) {
   const program = new Command();
@@ -14,10 +24,32 @@ export async function run(argv) {
   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();
+    .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
+
+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')
@@ -42,10 +74,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
@@ -60,6 +93,8 @@ export async function run(argv) {
     .command('whoami')
     .description('Verify the stored token and print the current user/token metadata.')
     .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('/user');
@@ -81,6 +116,8 @@ export async function run(argv) {
     .command('workspaces')
     .description('List workspaces visible to the current token.')
     .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('/workspaces');
@@ -104,6 +141,8 @@ export async function run(argv) {
     .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')
+    .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', {
@@ -134,6 +173,8 @@ export async function run(argv) {
     .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')
+    .option('--base-url <url>', 'Override the stored STATICX API base URL')
+    .option('--token <token>', 'Override the stored STATICX bearer token')
     .action(async (options, command) => {
       if (options.archive && options.sourceUrl) {
         throw new Error('Use either --archive or --source-url, not both.');
@@ -167,10 +208,12 @@ 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')
+    .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 zipPath = await createZipFromDirectory(options.dir);
@@ -182,22 +225,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,
         };
 
@@ -208,7 +241,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 {
@@ -222,6 +254,8 @@ export async function run(argv) {
     .requiredOption('--site-id <id>', 'Site ID')
     .option('--limit <number>', 'Maximum number of log rows', '25')
     .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}/logs`, {
@@ -246,7 +280,7 @@ export async function run(argv) {
 }
 
 async function clientFromCommand(command) {
-  const options = command.optsWithGlobals ? command.optsWithGlobals() : command.opts();
+  const options = command.opts();
   const auth = await resolveRuntimeAuth(options);
 
   return new StaticxApiClient(auth);

package/src/output.js

@@ -10,6 +10,88 @@ export function printTable(rows) {
   console.table(rows);
 }
 
+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.'],
+  ]);
+  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('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',
+      ],
+      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 +99,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`;
+}