wayfront 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wayfront
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Wayfront CLI
+
+Pull and push Twig templates from your [Wayfront](https://wayfront.com) workspace.
+
+## Quick start
+
+```
+npx wayfront
+```
+
+This will walk you through connecting your workspace. Enter your username and paste your API token.
+
+## Workflow
+
+```bash
+# 1. Pull templates from your workspace
+wayfront templates:pull
+
+# 2. Edit templates locally in ./templates
+#    Use your editor, commit to git, review in PRs — whatever your flow is
+
+# 3. Push your changes back
+wayfront templates:push        # only pushes templates that changed
+
+# 4. Commit your work
+git add templates/
+git commit -m "Update invoice template"
+```
+
+The `templates/` folder is yours to version control. Pull once, make changes over time, push when ready.
+
+## Commands
+
+```
+wayfront                        Show connection status
+wayfront init [workspace]       Connect a workspace
+wayfront use <workspace>        Switch active workspace
+wayfront templates:pull [name]  Pull templates (or one by name)
+wayfront templates:push [name]  Push changed templates (or one by name)
+wayfront templates:reset [name] Reset modified templates to default
+```
+
+## Template naming
+
+Templates use dot-notation that maps to folders:
+
+```
+portal.invoices.show  →  templates/portal/invoices/show.twig
+email.invoice_paid    →  templates/email/invoice_paid.twig
+```
+
+## Multiple workspaces
+
+Each workspace is identified by its Wayfront username. You can connect more than one and switch between them:
+
+```bash
+wayfront init clientco    # connect a second workspace
+wayfront use acme         # switch back
+```
+
+## Requirements
+
+Node.js 18+

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "wayfront",
+  "version": "0.1.0",
+  "description": "CLI for managing Wayfront templates",
+  "type": "module",
+  "bin": {
+    "wayfront": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "wayfront",
+    "templates",
+    "twig",
+    "cli"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayfronthq/wayfront-cli.git"
+  },
+  "homepage": "https://github.com/wayfronthq/wayfront-cli",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "ora": "^9.3.0"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,96 @@
+import { exec } from 'node:child_process';
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../lib/config.js';
+import { prompt, confirm } from '../lib/prompt.js';
+
+function openUrl(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open';
+  exec(`${cmd} '${url}'`);
+}
+
+export function parseInput(input) {
+  if (/^https?:\/\//.test(input)) {
+    const parsed = new URL(input);
+    const wayfrontMatch = parsed.hostname.match(/^([^.]+)\.wayfront\.com$/);
+    if (wayfrontMatch) {
+      return { workspace: wayfrontMatch[1], url: null };
+    }
+    return { workspace: parsed.hostname.split('.')[0], url: `${parsed.protocol}//${parsed.host}` };
+  }
+
+  const wayfrontMatch = input.match(/^([^.]+)\.wayfront\.com$/);
+  if (wayfrontMatch) {
+    return { workspace: wayfrontMatch[1], url: null };
+  }
+
+  if (input.includes('.')) {
+    return { workspace: input.split('.')[0], url: `https://${input}` };
+  }
+
+  return { workspace: input, url: null };
+}
+
+export async function runInit(input) {
+  const { workspace, url } = input ? parseInput(input) : { workspace: null, url: null };
+  const config = loadConfig();
+  config.workspaces ??= {};
+
+  let finalWorkspace = workspace;
+  let finalUrl = url;
+  if (!finalWorkspace) {
+    console.log(chalk.dim('  Your Wayfront username, e.g. acme'));
+    const answer = await prompt('Workspace: ');
+    if (!answer) {
+      console.error('No workspace provided.');
+      process.exit(1);
+    }
+    const parsed = parseInput(answer);
+    finalWorkspace = parsed.workspace;
+    finalUrl = parsed.url;
+  }
+
+  const baseUrl = finalUrl || `https://${finalWorkspace}.wayfront.com`;
+  const existing = config.workspaces[finalWorkspace];
+
+  if (existing) {
+    config.default = finalWorkspace;
+    saveConfig(config);
+    console.log(chalk.green('✓') + ` Switched to "${finalWorkspace}" (${baseUrl})`);
+
+    const update = await confirm('Update API token?');
+    if (!update) return;
+  }
+
+  const tokenUrl = `${baseUrl}/settings/templates/api-token`;
+
+  openUrl(tokenUrl);
+  console.log(`\nOpening ${chalk.cyan(tokenUrl)}\n`);
+
+  const token = await prompt('Paste your token: ');
+
+  if (!token) {
+    console.error('No token provided.');
+    process.exit(1);
+  }
+
+  config.workspaces[finalWorkspace] = {
+    token,
+    ...(finalUrl ? { url: finalUrl } : {}),
+  };
+
+  config.default = finalWorkspace;
+  saveConfig(config);
+
+  console.log(chalk.green('✓') + ` Workspace "${finalWorkspace}" configured (${baseUrl})`);
+}
+
+export function registerInit(program) {
+  program
+    .command('init [workspace]')
+    .description('Connect a workspace')
+    .action(async (input) => {
+      await runInit(input);
+    });
+}

package/src/commands/templates-pull.js

@@ -0,0 +1,48 @@
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiGet } from '../lib/api.js';
+import { nameToPath, elapsed } from '../lib/files.js';
+
+function writeTemplate(template, dir) {
+  const filePath = nameToPath(template.name, dir);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, template.data || '');
+  return filePath;
+}
+
+export function registerTemplatesPull(program) {
+  program
+    .command('templates:pull [name]')
+    .description('Pull templates from the API (or one by name)')
+    .action(async (name) => {
+      const dir = './templates';
+      const isFirstPull = !existsSync(dir) || !existsSync(`${dir}/.gitignore`);
+      const start = Date.now();
+      const spinner = ora(name ? `Pulling ${name}…` : 'Pulling templates…').start();
+
+      try {
+        if (name) {
+          const template = await apiGet(`/api/templates/${name}`);
+          const filePath = writeTemplate(template, dir);
+          spinner.succeed(`${template.name} → ${filePath} ${elapsed(start)}`);
+        } else {
+          const templates = await apiGet('/api/templates');
+
+          for (const t of templates) {
+            writeTemplate(t, dir);
+          }
+
+          spinner.succeed(`Pulled ${templates.length} template(s) to ${dir} ${elapsed(start)}`);
+
+          if (isFirstPull) {
+            console.log(chalk.dim('\n  Edit templates locally, then push changes with: wayfront templates:push'));
+          }
+        }
+      } catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/templates-push.js

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiGet, apiPut } from '../lib/api.js';
+import { nameToPath, pathToName, findTemplateFiles, formatName, elapsed } from '../lib/files.js';
+
+export function registerTemplatesPush(program) {
+  program
+    .command('templates:push [name]')
+    .description('Push templates to the API (or one by name)')
+    .action(async (name) => {
+      const dir = './templates';
+
+      try {
+        if (name) {
+          const filePath = nameToPath(name, dir);
+          const start = Date.now();
+          const spinner = ora(`Pushing ${name}…`).start();
+
+          let content;
+          try {
+            content = readFileSync(filePath, 'utf8');
+          } catch {
+            spinner.fail(`File not found: ${filePath}`);
+            process.exit(1);
+          }
+
+          await apiPut(`/api/templates/${name}`, { data: content });
+          spinner.succeed(`Pushed ${name} ${elapsed(start)}`);
+        } else {
+          const files = findTemplateFiles(dir);
+
+          if (files.length === 0) {
+            console.log(`No .twig files found in ${dir}`);
+            return;
+          }
+
+          const start = Date.now();
+          const spinner = ora('Comparing templates…').start();
+
+          // Fetch remote state to diff against
+          const remote = await apiGet('/api/templates');
+          const remoteByName = {};
+          for (const t of remote) {
+            remoteByName[t.name] = t.data || '';
+          }
+
+          // Find changed templates
+          const changed = [];
+          for (const filePath of files) {
+            const templateName = pathToName(filePath, dir);
+            const local = readFileSync(filePath, 'utf8');
+            if (local !== remoteByName[templateName]) {
+              changed.push({ name: templateName, content: local });
+            }
+          }
+
+          const unchanged = files.length - changed.length;
+
+          if (changed.length === 0) {
+            spinner.succeed(`Everything's in sync — ${chalk.dim(`${unchanged} template(s) unchanged`)} ${elapsed(start)}`);
+            return;
+          }
+
+          spinner.text = `Pushing ${changed.length} changed template(s)…`;
+          let count = 0;
+          const errors = [];
+
+          for (const t of changed) {
+            try {
+              await apiPut(`/api/templates/${t.name}`, { data: t.content });
+              count++;
+            } catch (err) {
+              errors.push({ name: t.name, message: err.message });
+            }
+            spinner.text = `Pushing templates… (${count + errors.length}/${changed.length})`;
+          }
+
+          if (errors.length === 0) {
+            spinner.succeed(`Pushed ${count}, ${unchanged} unchanged ${elapsed(start)}`);
+            for (const t of changed) {
+              console.log(`  ${formatName(t.name)}`);
+            }
+          } else {
+            spinner.warn(`Pushed ${count} template(s), ${errors.length} failed`);
+            for (const e of errors) {
+              console.error(`  ✗ ${e.name}: ${e.message}`);
+            }
+            process.exit(1);
+          }
+        }
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/templates-reset.js

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiGet, apiDelete } from '../lib/api.js';
+import { confirm } from '../lib/prompt.js';
+import { formatName, elapsed } from '../lib/files.js';
+
+export function registerTemplatesReset(program) {
+  program
+    .command('templates:reset [name]')
+    .description('Reset templates to default (or one by name)')
+    .action(async (name) => {
+      try {
+        if (name) {
+          const ok = await confirm(`Reset "${name}" to default?`);
+          if (!ok) return;
+
+          const start = Date.now();
+          const spinner = ora(`Resetting ${name}…`).start();
+          await apiDelete(`/api/templates/${name}`);
+          spinner.succeed(`Reset ${name} to default ${elapsed(start)}`);
+          console.log(chalk.dim(`\n  Run wayfront templates:pull ${name} to update your local copy`));
+        } else {
+          const spinner = ora('Fetching template list…').start();
+          const templates = await apiGet('/api/templates');
+          const custom = templates.filter((t) => t.is_modified);
+
+          if (custom.length === 0) {
+            spinner.succeed('No modified templates to reset');
+            return;
+          }
+
+          spinner.stop();
+          console.log(`Found ${custom.length} modified template(s):\n`);
+          for (const t of custom) {
+            console.log(`  ${formatName(t.name)}`);
+          }
+          console.log();
+
+          const ok = await confirm('Reset all to default?');
+          if (!ok) return;
+
+          const start = Date.now();
+          const resetSpinner = ora(`Resetting ${custom.length} template(s)…`).start();
+          let count = 0;
+          for (const t of custom) {
+            await apiDelete(`/api/templates/${t.name}`);
+            count++;
+            resetSpinner.text = `Resetting templates… (${count}/${custom.length})`;
+          }
+
+          resetSpinner.succeed(`Reset ${count} template(s) to default ${elapsed(start)}`);
+          console.log(chalk.dim('\n  Run wayfront templates:pull to update your local copies'));
+        }
+      } catch (err) {
+        console.error(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/use.js

@@ -0,0 +1,21 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../lib/config.js';
+
+export function registerUse(program) {
+  program
+    .command('use <workspace>')
+    .description('Switch active workspace')
+    .action((workspace) => {
+      const config = loadConfig();
+
+      if (!config.workspaces?.[workspace]) {
+        console.error(`Workspace "${workspace}" not found. Run: wayfront init <workspace>`);
+        process.exit(1);
+      }
+
+      config.default = workspace;
+      saveConfig(config);
+
+      console.log(chalk.green('✓') + ` Active workspace set to "${workspace}"`);
+    });
+}

package/src/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig } from './lib/config.js';
+import { registerInit, runInit } from './commands/init.js';
+import { registerUse } from './commands/use.js';
+import { registerTemplatesPull } from './commands/templates-pull.js';
+import { registerTemplatesPush } from './commands/templates-push.js';
+import { registerTemplatesReset } from './commands/templates-reset.js';
+
+const program = new Command();
+
+program
+  .name('wayfront')
+  .description('CLI for managing Wayfront templates')
+  .version('0.1.0')
+  .action(async () => {
+    const config = loadConfig();
+    const ws = config.default && config.workspaces?.[config.default];
+
+    if (!ws) {
+      console.log(`Welcome to Wayfront! Let's connect your workspace.\n`);
+      await runInit();
+      console.log();
+    } else {
+      const url = ws.url || `https://${config.default}.wayfront.com`;
+      const greetings = ['Ready', 'All set', 'Connected', 'Good to go'];
+      const greeting = greetings[Math.floor(Math.random() * greetings.length)];
+      console.log(`${chalk.green('✓')} ${greeting} — ${chalk.bold(config.default)} ${chalk.dim(`(${url})`)}\n`);
+    }
+
+    program.outputHelp();
+  });
+
+registerInit(program);
+registerUse(program);
+registerTemplatesPull(program);
+registerTemplatesPush(program);
+registerTemplatesReset(program);
+
+program.parse();

package/src/lib/api.js

@@ -0,0 +1,102 @@
+import { hostname, userInfo } from 'node:os';
+import { getCredentials } from './config.js';
+
+function getDeviceName() {
+  try {
+    return `${userInfo().username}@${hostname()}`;
+  } catch {
+    return hostname();
+  }
+}
+
+// Suppress the TLS warning when we intentionally disable cert checks for local dev
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = function (warning, ...args) {
+  if (typeof warning === 'string' && warning.includes('NODE_TLS_REJECT_UNAUTHORIZED')) return;
+  return originalEmitWarning.call(this, warning, ...args);
+};
+
+export function isLocal(url) {
+  const { hostname } = new URL(url);
+  return hostname === 'localhost'
+    || hostname.endsWith('.test')
+    || hostname.endsWith('.local');
+}
+
+async function request(method, path, body) {
+  const { url: baseUrl, token } = getCredentials();
+  const url = `${baseUrl}${path}`;
+
+  // Trust self-signed certs for local dev domains
+  const prevTls = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+  if (isLocal(baseUrl)) {
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+  }
+
+  const options = {
+    method,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Accept': 'application/json',
+      'X-Device-Name': getDeviceName(),
+    },
+  };
+
+  if (body !== undefined) {
+    options.headers['Content-Type'] = 'application/json';
+    options.body = JSON.stringify(body);
+  }
+
+  let res;
+  try {
+    res = await fetch(url, options);
+  } catch (err) {
+    throw new Error(`Could not connect to ${url}`);
+  } finally {
+    if (prevTls === undefined) {
+      delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    } else {
+      process.env.NODE_TLS_REJECT_UNAUTHORIZED = prevTls;
+    }
+  }
+
+  if (!res.ok) {
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error(`API error ${res.status}: ${res.statusText}`);
+    }
+
+    if (res.status === 401) {
+      throw new Error('Authentication failed. Check your API token.');
+    }
+    if (res.status === 403) {
+      throw new Error(data.message || 'Forbidden. Your license may not include API access.');
+    }
+    if (res.status === 422 && data.errors) {
+      const msgs = Object.entries(data.errors)
+        .map(([field, errs]) => `  ${field}: ${errs.join(', ')}`)
+        .join('\n');
+      throw new Error(`Validation failed:\n${msgs}`);
+    }
+
+    throw new Error(data.message || `API error ${res.status}`);
+  }
+
+  if (res.status === 204) return null;
+
+  return res.json();
+}
+
+export function apiGet(path) {
+  return request('GET', path);
+}
+
+export function apiPut(path, body) {
+  return request('PUT', path, body);
+}
+
+export function apiDelete(path) {
+  return request('DELETE', path);
+}

package/src/lib/config.js

@@ -0,0 +1,41 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const configDir = join(homedir(), '.config', 'wayfront');
+const configPath = join(configDir, 'config.json');
+
+export function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return { default: null, workspaces: {} };
+  }
+}
+
+export function saveConfig(config) {
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+export function getCredentials() {
+  const config = loadConfig();
+
+  if (!config.default) {
+    throw new Error('No active workspace. Run: wayfront init <workspace>');
+  }
+
+  const ws = config.workspaces[config.default];
+  if (!ws) {
+    throw new Error(`Workspace "${config.default}" not found. Run: wayfront init <workspace>`);
+  }
+  if (!ws.token) {
+    throw new Error(`No token set for workspace "${config.default}". Run: wayfront init ${config.default}`);
+  }
+
+  return {
+    workspace: config.default,
+    url: ws.url || `https://${config.default}.wayfront.com`,
+    token: ws.token,
+  };
+}

package/src/lib/files.js

@@ -0,0 +1,49 @@
+import { join, relative, sep } from 'node:path';
+import { readdirSync } from 'node:fs';
+import chalk from 'chalk';
+
+export function nameToPath(name, dir = './templates') {
+  const parts = name.split('.');
+  return join(dir, ...parts) + '.twig';
+}
+
+export function pathToName(filePath, dir = './templates') {
+  let rel = relative(dir, filePath);
+  if (rel.endsWith('.twig')) rel = rel.slice(0, -5);
+  return rel.split(sep).join('.');
+}
+
+export function formatName(name) {
+  const lastDot = name.lastIndexOf('.');
+  if (lastDot === -1) return chalk.bold(name);
+  return chalk.dim(name.slice(0, lastDot + 1)) + chalk.bold(name.slice(lastDot + 1));
+}
+
+export function elapsed(start) {
+  const ms = Date.now() - start;
+  return chalk.dim(ms < 1000 ? `(${ms}ms)` : `(${(ms / 1000).toFixed(1)}s)`);
+}
+
+export function findTemplateFiles(dir = './templates') {
+  const results = [];
+
+  function walk(current) {
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.name.endsWith('.twig')) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}

package/src/lib/prompt.js

@@ -0,0 +1,21 @@
+import { createInterface } from 'node:readline';
+
+export function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+export function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}