@mattersimple/theme 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @mattersimple/theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build, preview and publish your firm's website theme from your own code editor.
+
+```bash
+npx @mattersimple/theme login --host https://<platform address> --token rtk_…
+npx @mattersimple/theme init my-theme
+cd my-theme
+npm run dev
+```
+
+Create the token in your firm's admin: **Themes → Developer tools → Developer access**. That dialog shows the exact `login` command.
+
+| Command                                  |                                                                         |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `npx @mattersimple/theme init [folder]`             | Start a theme from the starter kit                                      |
+| `npx @mattersimple/theme dev`                       | Live preview: sync every saved change to your private development theme |
+| `npx @mattersimple/theme push [--theme <id>]`       | Upload as a new theme, or update one                                    |
+| `npx @mattersimple/theme pull --theme <id>`         | Download a theme's files                                                |
+| `npx @mattersimple/theme package`                   | Build a zip to upload by hand                                           |
+| `npx @mattersimple/theme check`                     | Validate without installing                                             |
+| `npx @mattersimple/theme list` / `open` / `publish` | Manage the firm's themes                                              |
+
+Run `npx @mattersimple/theme --help` for every option. The full theme developer guide is in the starter kit's `docs/` folder.
+
+Requires Node.js 20.10 or newer. No dependencies.

package/bin/mattersimple-theme.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,21 @@
 {
-  "name": "@mattersimple/theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@mattersimple/theme",
+    "version": "0.1.0",
+    "description": "Build, preview and publish firm website themes from your own editor.",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "mattersimple-theme": "bin/mattersimple-theme.js"
+    },
+    "files": [
+        "bin",
+        "src",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=20.10"
+    },
+    "scripts": {
+        "test": "node --test"
+    }
+}

package/src/api.js

@@ -0,0 +1,160 @@
+// The platform's theme API (/api/theme/v1), authenticated with a theme
+// access token.
+import { loadCredentials } from './config.js';
+
+export class ApiError extends Error {
+    constructor(message, status, problems = []) {
+        super(message);
+        this.status = status;
+        this.problems = problems;
+    }
+}
+
+export class ThemeApi {
+    constructor({ host, token }) {
+        this.base = host.replace(/\/+$/, '') + '/api/theme/v1/';
+        this.token = token;
+    }
+
+    static fromSavedLogin() {
+        const credentials = loadCredentials();
+
+        if (!credentials) {
+            throw new ApiError(
+                'You are not signed in. Run `mattersimple-theme login --host <url> --token <token>` first (create a token in Admin → Themes → Developer tools).',
+                401,
+            );
+        }
+
+        return new ThemeApi(credentials);
+    }
+
+    async request(method, path, { json, form, raw } = {}) {
+        let response;
+
+        try {
+            response = await fetch(this.base + path, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    Accept: 'application/json',
+                    ...(json !== undefined
+                        ? { 'Content-Type': 'application/json' }
+                        : {}),
+                },
+                body: json !== undefined ? JSON.stringify(json) : form,
+            });
+        } catch (error) {
+            throw new ApiError(
+                `Couldn't reach ${this.base} (${error.cause?.code ?? error.message}).`,
+                0,
+            );
+        }
+
+        if (!response.ok) {
+            let body = {};
+
+            try {
+                body = await response.json();
+            } catch {
+                // Not JSON: fall back to the status text.
+            }
+
+            const validation = body.errors
+                ? Object.values(body.errors).flat()
+                : [];
+
+            throw new ApiError(
+                body.message || `${response.status} ${response.statusText}`,
+                response.status,
+                body.problems ?? validation,
+            );
+        }
+
+        if (raw) {
+            return Buffer.from(await response.arrayBuffer());
+        }
+
+        return response.status === 204 ? null : response.json();
+    }
+
+    me() {
+        return this.request('GET', 'me');
+    }
+
+    starterKit(name) {
+        return this.request(
+            'GET',
+            `starter-kit?name=${encodeURIComponent(name)}`,
+            { raw: true },
+        );
+    }
+
+    themes() {
+        return this.request('GET', 'themes');
+    }
+
+    theme(id) {
+        return this.request('GET', `themes/${id}`);
+    }
+
+    createTheme(zip, { role = 'unpublished', name } = {}) {
+        const form = new FormData();
+        form.append(
+            'theme',
+            new Blob([zip], { type: 'application/zip' }),
+            'theme.zip',
+        );
+        form.append('role', role);
+
+        if (name) {
+            form.append('name', name);
+        }
+
+        return this.request('POST', 'themes', { form });
+    }
+
+    check(zip) {
+        const form = new FormData();
+        form.append(
+            'theme',
+            new Blob([zip], { type: 'application/zip' }),
+            'theme.zip',
+        );
+
+        return this.request('POST', 'themes/check', { form });
+    }
+
+    files(id) {
+        return this.request('GET', `themes/${id}/files`);
+    }
+
+    file(id, path) {
+        return this.request(
+            'GET',
+            `themes/${id}/files/${path.split('/').map(encodeURIComponent).join('/')}`,
+            { raw: true },
+        );
+    }
+
+    pushFiles(id, upsert, deletes, { allowLive = false } = {}) {
+        return this.request('PUT', `themes/${id}/files`, {
+            json: {
+                upsert: upsert.map(([path, content]) => ({
+                    path,
+                    content: content.toString('base64'),
+                })),
+                delete: deletes,
+                allow_live: allowLive,
+            },
+        });
+    }
+
+    preview(id) {
+        return this.request('GET', `themes/${id}/preview`);
+    }
+
+    publish(id) {
+        return this.request('POST', `themes/${id}/publish`);
+    }
+}

package/src/cli.js

@@ -0,0 +1,126 @@
+import { parseArgs } from 'node:util';
+
+import { ApiError } from './api.js';
+import { check } from './commands/check.js';
+import { dev } from './commands/dev.js';
+import { init } from './commands/init.js';
+import { list } from './commands/list.js';
+import { login, logout } from './commands/login.js';
+import { open } from './commands/open.js';
+import { packageTheme } from './commands/package.js';
+import { publish } from './commands/publish.js';
+import { pull } from './commands/pull.js';
+import { push } from './commands/push.js';
+import { problem } from './output.js';
+
+const HELP = `mattersimple-theme — build, preview and publish your firm's website theme
+
+Usage: mattersimple-theme <command> [options]
+
+Commands:
+  login --host <url> --token <token>   Sign in with a token from Admin → Themes → Developer tools
+  logout                               Forget the saved token
+  init [folder] [--name <name>]        Start a theme from the starter kit (--no-install to skip npm install)
+  dev                                  Live preview: sync every saved change to your development theme
+  push [--theme <id>]                  Upload as a new unpublished theme, or update theme <id>
+       [--skip-json] [--allow-live]      --skip-json keeps the pages and settings edited in the editor
+  pull --theme <id> [--only-json]      Download a theme's files (e.g. pages and settings edited in the editor)
+  package                              Build dist/<name>-<version>.zip to upload by hand
+  check                                Validate the theme on the platform without installing it
+  list                                 List the firm's themes
+  open --theme <id> [--editor]         Open a theme's preview (or the theme editor)
+  publish --theme <id> [--yes]         Make a theme the live theme
+
+Options:
+  --path <folder>   The theme folder (default: the current folder)
+  --no-build        Don't run the project's CSS build first
+  --no-open         dev: don't open the preview in the browser
+`;
+
+const options = {
+    host: { type: 'string' },
+    token: { type: 'string' },
+    name: { type: 'string' },
+    theme: { type: 'string' },
+    path: { type: 'string' },
+    unpublished: { type: 'boolean' },
+    'skip-json': { type: 'boolean' },
+    'only-json': { type: 'boolean' },
+    'allow-live': { type: 'boolean' },
+    'no-build': { type: 'boolean' },
+    'no-install': { type: 'boolean' },
+    'no-open': { type: 'boolean' },
+    editor: { type: 'boolean' },
+    yes: { type: 'boolean', short: 'y' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'v' },
+};
+
+export async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options,
+        allowPositionals: true,
+    });
+    const [command, ...rest] = positionals;
+    const flags = {
+        host: values.host,
+        token: values.token,
+        name: values.name,
+        theme: values.theme,
+        path: values.path,
+        unpublished: values.unpublished,
+        skipJson: values['skip-json'],
+        onlyJson: values['only-json'],
+        allowLive: values['allow-live'],
+        build: !values['no-build'],
+        install: !values['no-install'],
+        open: !values['no-open'],
+        editor: values.editor,
+        yes: values.yes,
+    };
+
+    if (values.version) {
+        const { default: pkg } = await import('../package.json', {
+            with: { type: 'json' },
+        });
+        console.log(pkg.version);
+
+        return;
+    }
+
+    const commands = {
+        login: () => login(flags),
+        logout: () => logout(),
+        init: () => init({ ...flags, dir: rest[0] }),
+        dev: () => dev(flags),
+        push: () => push(flags),
+        pull: () => pull(flags),
+        package: () => packageTheme(flags),
+        check: () => check(flags),
+        list: () => list(),
+        open: () => open(flags),
+        publish: () => publish(flags),
+    };
+
+    if (!command || values.help || !commands[command]) {
+        console.log(HELP);
+        process.exitCode =
+            command && !values.help && !commands[command] ? 1 : 0;
+
+        return;
+    }
+
+    try {
+        await commands[command]();
+    } catch (error) {
+        if (error instanceof ApiError || error instanceof Error) {
+            problem(error);
+            process.exitCode = 1;
+
+            return;
+        }
+
+        throw error;
+    }
+}

package/src/commands/check.js

@@ -0,0 +1,16 @@
+import { ThemeApi } from '../api.js';
+import { success, warn } from '../output.js';
+import { Project } from '../project.js';
+
+/** Have the platform validate the theme, without installing it. */
+export async function check({ path }) {
+    const project = new Project(path).assertTheme();
+    const { unknown } = project.files();
+
+    for (const file of unknown) {
+        warn(`${file}: themes can't contain this file; it's left out.`);
+    }
+
+    await ThemeApi.fromSavedLogin().check(project.zip());
+    success('No problems found.');
+}

package/src/commands/dev.js

@@ -0,0 +1,106 @@
+import { watch } from 'node:fs';
+
+import { ApiError, ThemeApi } from '../api.js';
+import { isThemeFile, toPosix } from '../files.js';
+import { bold, dim, info, problem, success } from '../output.js';
+import { Project } from '../project.js';
+import { openInBrowser, runScript } from '../run.js';
+import { printLinks, pushChanges } from './push.js';
+
+/**
+ * Live development: keeps the CSS build watching, uploads the project to
+ * your private development theme, then pushes every saved change. The
+ * preview reloads itself after each push.
+ */
+export async function dev({ build = true, open: openPreview = true, path }) {
+    const project = new Project(path).assertTheme();
+    const api = ThemeApi.fromSavedLogin();
+    const children = [];
+
+    if (build && project.hasScript('build:css')) {
+        await runScript(project.root, 'build:css');
+    }
+
+    if (build && project.hasScript('watch:css')) {
+        children.push(runScript(project.root, 'watch:css', { wait: false }));
+    }
+
+    const stop = () => {
+        children.forEach((child) => child.kill());
+        process.exit(0);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+
+    info('Uploading your theme to its development theme…');
+    let theme;
+
+    try {
+        theme = await api.createTheme(project.zip(), { role: 'development' });
+    } catch (error) {
+        if (error instanceof ApiError) {
+            problem(error);
+            info(dim('Fix the problems above, then run `npm run dev` again.'));
+            children.forEach((child) => child.kill());
+            process.exitCode = 1;
+
+            return;
+        }
+
+        throw error;
+    }
+
+    success(`Synced to ${bold(theme.name)}.`);
+    const links = await printLinks(api, theme.id);
+
+    if (openPreview) {
+        openInBrowser(links.preview_url);
+    }
+
+    info(dim('\nWatching for changes. Press Ctrl+C to stop.\n'));
+
+    const pending = new Set();
+    let timer = null;
+    let pushing = Promise.resolve();
+
+    const flush = () => {
+        const only = new Set(pending);
+        pending.clear();
+
+        pushing = pushing.then(async () => {
+            try {
+                const changed = await pushChanges(api, project, theme.id, {
+                    only,
+                });
+
+                if (changed > 0) {
+                    success(
+                        `${[...only].join(', ')} ${dim(new Date().toLocaleTimeString())}`,
+                    );
+                }
+            } catch (error) {
+                if (!(error instanceof ApiError)) {
+                    throw error;
+                }
+
+                problem(error);
+            }
+        });
+    };
+
+    watch(project.root, { recursive: true }, (_event, filename) => {
+        if (!filename) {
+            return;
+        }
+
+        const path = toPosix(filename.toString());
+
+        if (!isThemeFile(path)) {
+            return;
+        }
+
+        pending.add(path);
+        clearTimeout(timer);
+        timer = setTimeout(flush, 150);
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+
+import { ThemeApi } from '../api.js';
+import { bold, info, success } from '../output.js';
+import { readZip } from '../zip.js';
+
+export async function init({ dir = 'my-theme', name, install = true }) {
+    const root = resolve(dir);
+
+    if (existsSync(root) && readdirSync(root).length > 0) {
+        throw new Error(`${root} already exists and isn't empty.`);
+    }
+
+    const api = ThemeApi.fromSavedLogin();
+    const files = readZip(await api.starterKit(name || 'My theme'));
+
+    for (const [path, content] of files) {
+        const relative = path.replace(/^[^/]+\//, '');
+        const target = join(root, relative);
+
+        if (!target.startsWith(root + sep)) {
+            continue;
+        }
+
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content);
+    }
+
+    success(`Created ${bold(root)} from the starter kit.`);
+
+    if (install) {
+        info('Installing the build tools (npm install)…');
+        await new Promise((done, fail) => {
+            const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+            spawn(npm, ['install'], { cwd: root, stdio: 'inherit' })
+                .on('exit', (code) =>
+                    code === 0
+                        ? done()
+                        : fail(new Error('npm install failed.')),
+                )
+                .on('error', fail);
+        });
+    }
+
+    info(
+        `\nNext:\n  cd ${dir}\n  npm run dev    # live preview while you edit\n`,
+    );
+}

package/src/commands/list.js

@@ -0,0 +1,20 @@
+import { ThemeApi } from '../api.js';
+import { bold, dim, info } from '../output.js';
+
+export async function list() {
+    const themes = await ThemeApi.fromSavedLogin().themes();
+
+    if (themes.length === 0) {
+        info('No themes yet.');
+
+        return;
+    }
+
+    for (const theme of themes) {
+        const role =
+            theme.role === 'main' ? bold('[live]') : dim(`[${theme.role}]`);
+        info(
+            `${theme.id}  ${role} ${theme.name}${theme.version ? dim(' v' + theme.version) : ''}`,
+        );
+    }
+}

package/src/commands/login.js

@@ -0,0 +1,24 @@
+import { ThemeApi } from '../api.js';
+import { forgetCredentials, saveCredentials } from '../config.js';
+import { bold, success } from '../output.js';
+
+export async function login({ host, token }) {
+    if (!host || !token) {
+        throw new Error(
+            'Usage: mattersimple-theme login --host <platform url> --token <token>. Admin → Themes → Developer tools → Developer access shows the full command.',
+        );
+    }
+
+    const credentials = { host: host.replace(/\/+$/, ''), token };
+    const me = await new ThemeApi(credentials).me();
+    const path = saveCredentials({ ...credentials, firm: me.firm.name });
+
+    success(
+        `Signed in to ${bold(me.firm.name)} as ${me.user.name} (token “${me.token.name}”). Saved to ${path}.`,
+    );
+}
+
+export function logout() {
+    forgetCredentials();
+    success('Signed out.');
+}

package/src/commands/open.js

@@ -0,0 +1,14 @@
+import { ThemeApi } from '../api.js';
+import { openInBrowser } from '../run.js';
+import { printLinks } from './push.js';
+
+export async function open({ theme: id, editor }) {
+    if (!id) {
+        throw new Error(
+            'Which theme? Pass --theme <id> (see `mattersimple-theme list`).',
+        );
+    }
+
+    const links = await printLinks(ThemeApi.fromSavedLogin(), id);
+    openInBrowser(editor ? links.editor_url : links.preview_url);
+}

package/src/commands/package.js

@@ -0,0 +1,41 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { bold, success, warn } from '../output.js';
+import { Project } from '../project.js';
+import { runScript } from '../run.js';
+import { createZip } from '../zip.js';
+
+/** Build a zip to upload by hand in Admin → Themes. */
+export async function packageTheme({ build = true, path }) {
+    const project = new Project(path).assertTheme();
+
+    if (build && project.hasScript('build:css')) {
+        await runScript(project.root, 'build:css');
+    }
+
+    const { files, unknown } = project.files();
+
+    for (const file of unknown) {
+        warn(`Left out ${file}: themes can't contain it.`);
+    }
+
+    const theme = project.themeJson();
+    const slug =
+        String(theme.name || 'theme')
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '') || 'theme';
+    const target = join(
+        project.root,
+        'dist',
+        `${slug}-${theme.version || '0.0.0'}.zip`,
+    );
+
+    mkdirSync(join(project.root, 'dist'), { recursive: true });
+    writeFileSync(target, createZip(files));
+
+    success(`Packaged ${files.size} files into ${bold(target)}.`);
+
+    return target;
+}

package/src/commands/publish.js

@@ -0,0 +1,34 @@
+import { createInterface } from 'node:readline/promises';
+
+import { ThemeApi } from '../api.js';
+import { bold, success } from '../output.js';
+
+/** Make a theme the firm's live theme. */
+export async function publish({ theme: id, yes }) {
+    if (!id) {
+        throw new Error(
+            'Which theme? Pass --theme <id> (see `mattersimple-theme list`).',
+        );
+    }
+
+    const api = ThemeApi.fromSavedLogin();
+    const theme = await api.theme(id);
+
+    if (!yes) {
+        const prompt = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const answer = await prompt.question(
+            `Publish ${bold(theme.name)}? It replaces the live theme for every visitor. [y/N] `,
+        );
+        prompt.close();
+
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            return;
+        }
+    }
+
+    await api.publish(id);
+    success(`${bold(theme.name)} is now live.`);
+}

package/src/commands/pull.js

@@ -0,0 +1,51 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+
+import { ThemeApi } from '../api.js';
+import { checksum, isDocument } from '../files.js';
+import { info, success } from '../output.js';
+import { Project } from '../project.js';
+
+/** Download a theme's files — e.g. the pages and settings changed in the editor. */
+export async function pull({ theme: id, onlyJson, path }) {
+    if (!id) {
+        throw new Error(
+            'Which theme? Pass --theme <id> (see `mattersimple-theme list`).',
+        );
+    }
+
+    const root = resolve(path ?? process.cwd());
+    const api = ThemeApi.fromSavedLogin();
+    mkdirSync(root, { recursive: true });
+    const local = new Project(root).files().files;
+    let written = 0;
+
+    for (const file of (await api.files(id)).files) {
+        if (onlyJson && !isDocument(file.path)) {
+            continue;
+        }
+
+        const current = local.get(file.path);
+
+        if (current && checksum(current, file.path) === file.checksum) {
+            continue;
+        }
+
+        const target = join(root, file.path);
+
+        if (!target.startsWith(root + sep)) {
+            continue;
+        }
+
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, await api.file(id, file.path));
+        info(`  ${file.path}`);
+        written++;
+    }
+
+    success(
+        written === 0
+            ? 'Already up to date.'
+            : `Pulled ${written} file${written === 1 ? '' : 's'}.`,
+    );
+}

package/src/commands/push.js

@@ -0,0 +1,122 @@
+import { ThemeApi } from '../api.js';
+import { batchChanges, checksum, isDocument } from '../files.js';
+import { bold, dim, info, success } from '../output.js';
+import { Project } from '../project.js';
+import { runScript } from '../run.js';
+
+/**
+ * Upload the project: as a new unpublished theme, or onto an existing theme
+ * (only what changed is sent).
+ */
+export async function push({
+    theme: id,
+    unpublished,
+    skipJson,
+    allowLive,
+    name,
+    build = true,
+    path,
+}) {
+    const project = new Project(path).assertTheme();
+    const api = ThemeApi.fromSavedLogin();
+
+    if (build && project.hasScript('build:css')) {
+        await runScript(project.root, 'build:css');
+    }
+
+    if (!id || unpublished) {
+        const created = await api.createTheme(project.zip(), {
+            name: name || project.themeJson().name,
+        });
+        success(
+            `Uploaded as ${bold(created.name)} (${created.id}), unpublished.`,
+        );
+        await printLinks(api, created.id);
+
+        return created;
+    }
+
+    const changed = await pushChanges(api, project, id, {
+        skipJson,
+        allowLive,
+    });
+
+    if (changed === 0) {
+        info('Nothing to push: the theme is up to date.');
+
+        return null;
+    }
+
+    success(`Pushed ${changed} change${changed === 1 ? '' : 's'}.`);
+    await printLinks(api, id);
+
+    return null;
+}
+
+/** @returns {Promise<number>} the number of files sent or deleted */
+export async function pushChanges(
+    api,
+    project,
+    id,
+    { skipJson = false, allowLive = false, only } = {},
+) {
+    const { files } = project.files();
+    // Documents are compared with the version last pushed, so a push only
+    // sends the ones changed here and keeps what was changed in the editor.
+    const remote = new Map(
+        (await api.files(id)).files.map((file) => [
+            file.path,
+            file.pushed_checksum ?? file.checksum,
+        ]),
+    );
+    const upserts = new Map();
+    const deletes = [];
+
+    for (const [path, content] of files) {
+        if ((only && !only.has(path)) || (skipJson && isDocument(path))) {
+            continue;
+        }
+
+        if (remote.get(path) !== checksum(content, path)) {
+            upserts.set(path, content);
+        }
+    }
+
+    for (const path of remote.keys()) {
+        if (
+            (only && !only.has(path)) ||
+            (skipJson && isDocument(path)) ||
+            files.has(path)
+        ) {
+            continue;
+        }
+
+        // The editor's documents stay unless this project ships its own.
+        if (isDocument(path) && !only) {
+            continue;
+        }
+
+        deletes.push(path);
+    }
+
+    if (upserts.size === 0 && deletes.length === 0) {
+        return 0;
+    }
+
+    for (const batch of batchChanges(upserts, deletes)) {
+        if (batch.upsert.length > 0 || batch.delete.length > 0) {
+            await api.pushFiles(id, batch.upsert, batch.delete, { allowLive });
+        }
+    }
+
+    return upserts.size + deletes.length;
+}
+
+export async function printLinks(api, id) {
+    const links = await api.preview(id);
+    info(`  Preview: ${links.preview_url}`);
+    info(`  Editor:  ${links.editor_url}`);
+    info(dim('  The preview link is valid for 12 hours.'));
+
+    return links;
+}

package/src/config.js

@@ -0,0 +1,54 @@
+// Saved sign-in: ~/.config/mattersimple/credentials.json (readable only by you),
+// or MATTERSIMPLE_THEME_HOST + MATTERSIMPLE_THEME_TOKEN in the environment (CI).
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export function credentialsPath() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+
+    return join(base, 'mattersimple', 'credentials.json');
+}
+
+export function loadCredentials() {
+    if (process.env.MATTERSIMPLE_THEME_TOKEN && process.env.MATTERSIMPLE_THEME_HOST) {
+        return {
+            host: process.env.MATTERSIMPLE_THEME_HOST,
+            token: process.env.MATTERSIMPLE_THEME_TOKEN,
+        };
+    }
+
+    const path = credentialsPath();
+
+    if (!existsSync(path)) {
+        return null;
+    }
+
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+export function saveCredentials(credentials) {
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(credentials, null, 4) + '\n', {
+        mode: 0o600,
+    });
+    chmodSync(path, 0o600);
+
+    return path;
+}
+
+export function forgetCredentials() {
+    rmSync(credentialsPath(), { force: true });
+}

package/src/files.js

@@ -0,0 +1,138 @@
+// Which files of a theme project belong in the theme — the same rules the
+// platform applies to uploads (src/rules.json, exported by the platform's
+// `php artisan themes:export-rules`).
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import rules from './rules.json' with { type: 'json' };
+
+const allowed = rules.allowed.map((source) => new RegExp(source));
+const ignored = rules.ignored.map((source) => new RegExp(source));
+
+export const limits = rules.limits;
+
+export function isIgnored(path) {
+    return ignored.some((pattern) => pattern.test(path));
+}
+
+export function isThemeFile(path) {
+    return !isIgnored(path) && allowed.some((pattern) => pattern.test(path));
+}
+
+/** Templates, section groups and theme settings — what the theme editor changes. */
+export function isDocument(path) {
+    return (
+        /^templates\/[a-z0-9_./-]+\.json$/.test(path) ||
+        /^sections\/[a-z0-9_-]+\.json$/.test(path) ||
+        path === 'config/settings_data.json'
+    );
+}
+
+export function toPosix(path) {
+    return path.split(sep).join('/');
+}
+
+/**
+ * The theme's files in a project folder, skipping development files.
+ *
+ * @returns {{ files: Map<string, Buffer>, unknown: string[] }} unknown: files the platform wouldn't accept
+ */
+export function readThemeFiles(root) {
+    const files = new Map();
+    const unknown = [];
+
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const absolute = join(dir, entry.name);
+            const path = toPosix(relative(root, absolute));
+
+            if (isIgnored(path) || isIgnored(path + '/')) {
+                continue;
+            }
+
+            if (entry.isDirectory()) {
+                walk(absolute);
+            } else if (entry.isFile()) {
+                if (isThemeFile(path)) {
+                    files.set(path, readFileSync(absolute));
+                } else {
+                    unknown.push(path);
+                }
+            }
+        }
+    }
+
+    walk(root);
+
+    return {
+        files: new Map([...files].sort(([a], [b]) => a.localeCompare(b))),
+        unknown,
+    };
+}
+
+/**
+ * The checksum the platform lists for a file. Documents are compared as
+ * compact JSON, so reformatting one isn't a change.
+ */
+export function checksum(buffer, path = '') {
+    let content = buffer;
+
+    if (isDocument(path)) {
+        try {
+            content = Buffer.from(
+                JSON.stringify(JSON.parse(buffer.toString('utf8'))),
+            );
+        } catch {
+            // Invalid JSON: compare as is; the platform reports the problem.
+        }
+    }
+
+    return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Splits pushes so no request body grows past `maxBytes` of file content.
+ * Assets and screenshots go first, in batches of their own: they can't make
+ * the theme invalid on their own. Everything Liquid and JSON goes in the last
+ * batch, with the deletions, so the theme is validated as a whole once.
+ *
+ * @param {Map<string, Buffer>} upserts
+ * @param {string[]} deletes
+ */
+export function batchChanges(upserts, deletes, maxBytes = 8 * 1024 * 1024) {
+    const binaries = [];
+    const rest = [];
+
+    for (const [path, content] of upserts) {
+        (/^(assets|screenshots)\//.test(path) ? binaries : rest).push([
+            path,
+            content,
+        ]);
+    }
+
+    const batches = [];
+    let current = [];
+    let size = 0;
+
+    for (const entry of binaries) {
+        const bytes = Math.ceil(entry[1].length / 3) * 4;
+
+        if (current.length > 0 && size + bytes > maxBytes) {
+            batches.push({ upsert: current, delete: [] });
+            current = [];
+            size = 0;
+        }
+
+        current.push(entry);
+        size += bytes;
+    }
+
+    if (current.length > 0) {
+        batches.push({ upsert: current, delete: [] });
+    }
+
+    batches.push({ upsert: rest, delete: deletes });
+
+    return batches;
+}

package/src/output.js

@@ -0,0 +1,31 @@
+const color = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (text) =>
+    color ? `\u001b[${code}m${text}\u001b[0m` : String(text);
+
+export const bold = paint(1);
+export const dim = paint(2);
+export const red = paint(31);
+export const green = paint(32);
+export const yellow = paint(33);
+export const cyan = paint(36);
+
+export function info(message) {
+    console.log(message);
+}
+
+export function success(message) {
+    console.log(green('✔ ') + message);
+}
+
+export function warn(message) {
+    console.warn(yellow('! ') + message);
+}
+
+/** Prints an API error, with the theme's problems when the platform listed them. */
+export function problem(error) {
+    console.error(red('✖ ') + error.message);
+
+    for (const item of error.problems ?? []) {
+        console.error(red('  • ') + item);
+    }
+}

package/src/project.js

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { createZip } from './zip.js';
+import { readThemeFiles } from './files.js';
+
+/** A theme project folder: the theme files plus its build setup. */
+export class Project {
+    constructor(root = process.cwd()) {
+        this.root = resolve(root);
+    }
+
+    assertTheme() {
+        if (!existsSync(join(this.root, 'layout', 'theme.liquid'))) {
+            throw new Error(
+                `${this.root} isn't a theme folder (no layout/theme.liquid). Run this in your theme's folder, or create one with \`mattersimple-theme init\`.`,
+            );
+        }
+
+        return this;
+    }
+
+    themeJson() {
+        try {
+            return JSON.parse(
+                readFileSync(join(this.root, 'theme.json'), 'utf8'),
+            );
+        } catch {
+            return {};
+        }
+    }
+
+    packageJson() {
+        try {
+            return JSON.parse(
+                readFileSync(join(this.root, 'package.json'), 'utf8'),
+            );
+        } catch {
+            return {};
+        }
+    }
+
+    hasScript(name) {
+        return Boolean(this.packageJson().scripts?.[name]);
+    }
+
+    files() {
+        return readThemeFiles(this.root);
+    }
+
+    zip() {
+        return createZip(this.files().files);
+    }
+}

package/src/rules.json

@@ -0,0 +1,28 @@
+{
+    "allowed": [
+        "^layout/[a-z0-9_-]+\\.liquid$",
+        "^templates/(customers/)?[a-z0-9_-]+(\\.[a-z0-9_-]+)?\\.(json|liquid)$",
+        "^sections/[a-z0-9_-]+\\.(liquid|json)$",
+        "^snippets/[a-z0-9_-]+\\.liquid$",
+        "^assets/[A-Za-z0-9_.@-]+\\.(css|js|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf)$",
+        "^config/(settings_schema|settings_data)\\.json$",
+        "^locales/[a-z]{2}(-[A-Z]{2})?(\\.default)?(\\.schema)?\\.json$",
+        "^screenshots/(desktop|mobile)\\.(png|jpe?g|webp)$",
+        "^theme\\.json$",
+        "^(README|CHANGELOG|LICENSE)(\\.(md|txt))?$"
+    ],
+    "ignored": [
+        "(^|/)(__MACOSX|\\.DS_Store|Thumbs\\.db|\\.git)(/|$)",
+        "(^|/)(\\.[^/]+|node_modules|src|dist|docs|package(-lock)?\\.json|pnpm-lock\\.yaml|yarn\\.lock|bun\\.lockb?|tailwind\\.config\\.[a-z]+|[^/]+\\.map)(/|$)"
+    ],
+    "limits": {
+        "max_zip_bytes": 20971520,
+        "max_uncompressed_bytes": 41943040,
+        "max_files": 500,
+        "max_file_bytes": 5242880,
+        "max_compression_ratio": 100,
+        "screenshot_min_width": 1600,
+        "screenshot_min_height": 1000,
+        "screenshot_max_bytes": 5242880
+    }
+}

package/src/run.js

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+
+/** Runs a package.json script in the project, inheriting the terminal. */
+export function runScript(root, script, { wait = true } = {}) {
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(npm, ['run', '--silent', script], {
+        cwd: root,
+        stdio: 'inherit',
+    });
+
+    if (!wait) {
+        return child;
+    }
+
+    return new Promise((resolve, reject) => {
+        child.on('exit', (code) =>
+            code === 0
+                ? resolve()
+                : reject(new Error(`npm run ${script} failed.`)),
+        );
+        child.on('error', reject);
+    });
+}
+
+export function openInBrowser(url) {
+    const command =
+        process.platform === 'darwin'
+            ? 'open'
+            : process.platform === 'win32'
+              ? 'cmd'
+              : 'xdg-open';
+    const args =
+        process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    spawn(command, args, { stdio: 'ignore', detached: true })
+        .on('error', () => {})
+        .unref();
+}

package/src/zip.js

@@ -0,0 +1,156 @@
+// A minimal zip reader and writer on node:zlib — enough for theme packages
+// (no zip64, no encryption), so the CLI needs no dependencies.
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+
+const CRC_TABLE = new Uint32Array(256).map((_, n) => {
+    let c = n;
+
+    for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+
+    return c >>> 0;
+});
+
+export function crc32(buffer) {
+    let crc = 0xffffffff;
+
+    for (const byte of buffer) {
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+
+    return (crc ^ 0xffffffff) >>> 0;
+}
+
+function dosDateTime(date) {
+    const time =
+        (date.getHours() << 11) |
+        (date.getMinutes() << 5) |
+        Math.floor(date.getSeconds() / 2);
+    const day =
+        ((date.getFullYear() - 1980) << 9) |
+        ((date.getMonth() + 1) << 5) |
+        date.getDate();
+
+    return { time, day };
+}
+
+/**
+ * @param {Map<string, Buffer>|Record<string, Buffer|string>} files contents keyed by path
+ * @returns {Buffer}
+ */
+export function createZip(files) {
+    const entries = files instanceof Map ? [...files] : Object.entries(files);
+    const { time, day } = dosDateTime(new Date());
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+
+    for (const [path, value] of entries) {
+        const data = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        const name = Buffer.from(path, 'utf8');
+        const deflated = deflateRawSync(data);
+        const stored = deflated.length >= data.length;
+        const body = stored ? data : deflated;
+        const crc = crc32(data);
+
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(stored ? 0 : 8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(day, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(stored ? 0 : 8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(day, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+
+        locals.push(local, name, body);
+        centrals.push(central, name);
+        offset += local.length + name.length + body.length;
+    }
+
+    const directory = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+
+    return Buffer.concat([...locals, directory, end]);
+}
+
+/**
+ * @param {Buffer} zip
+ * @returns {Map<string, Buffer>} file contents keyed by path (folders skipped)
+ */
+export function readZip(zip) {
+    let end = -1;
+
+    for (let i = zip.length - 22; i >= Math.max(0, zip.length - 65557); i--) {
+        if (zip.readUInt32LE(i) === 0x06054b50) {
+            end = i;
+            break;
+        }
+    }
+
+    if (end === -1) {
+        throw new Error('Not a zip file.');
+    }
+
+    const count = zip.readUInt16LE(end + 10);
+    let cursor = zip.readUInt32LE(end + 16);
+    const files = new Map();
+
+    for (let i = 0; i < count; i++) {
+        if (zip.readUInt32LE(cursor) !== 0x02014b50) {
+            throw new Error('Corrupt zip directory.');
+        }
+
+        const method = zip.readUInt16LE(cursor + 10);
+        const compressedSize = zip.readUInt32LE(cursor + 20);
+        const nameLength = zip.readUInt16LE(cursor + 28);
+        const extraLength = zip.readUInt16LE(cursor + 30);
+        const commentLength = zip.readUInt16LE(cursor + 32);
+        const localOffset = zip.readUInt32LE(cursor + 42);
+        const name = zip.toString(
+            'utf8',
+            cursor + 46,
+            cursor + 46 + nameLength,
+        );
+        cursor += 46 + nameLength + extraLength + commentLength;
+
+        if (name.endsWith('/')) {
+            continue;
+        }
+
+        const dataStart =
+            localOffset +
+            30 +
+            zip.readUInt16LE(localOffset + 26) +
+            zip.readUInt16LE(localOffset + 28);
+        const data = zip.subarray(dataStart, dataStart + compressedSize);
+        files.set(
+            name,
+            method === 8 ? inflateRawSync(data) : Buffer.from(data),
+        );
+    }
+
+    return files;
+}