@mattersimple/theme 0.0.0-stage → 0.1.1

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;
+}