@mattersimple/theme 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MatterSimple
+
+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

@@ -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,22 @@
 {
-  "name": "@mattersimple/theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@mattersimple/theme",
+    "version": "0.1.1",
+    "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",
+        "LICENSE",
+        "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.`);
+}