@shop-on/theme-dev-host 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @shop-on/theme-dev-host
 
-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.
+A local theme-editor dev server. It serves the **editor contract** (editor-loader,
+draft read/write, template/settings) over a theme's local `src/`, and
+reverse-proxies everything else to the theme's own dev server — behind **one
+origin** a real admin theme-editor can bind to. So a theme runs and previews
+locally while the platform spends ~zero compute (it never boots a storefront,
+allocates a port, or stores an in-progress theme).
+
+Self-contained: no Redis, no orchestrator dependency. This is the nucleus of the
+future `theme` CLI (`theme dev`).
+
+See **[docs/theme-dev-host.md](../../docs/theme-dev-host.md)** for the architecture.
+
+## Quick start
+
+```bash
+# One command — starts the theme's dev server AND the gateway, wired together:
+pnpm -C themes/care theme:editor
+
+#   gateway     http://localhost:4101   (open this; ?preview=<sid> shows drafts)
+#   theme dev   http://localhost:3002
+```
+
+The gateway port is the single origin for both the editor API and the storefront
+render. `Ctrl-C` stops both.
+
+Each theme depends on `@shop-on/theme-dev-host` (`workspace:*`) and exposes
+`theme:editor` → the `theme-dev-host` bin, which infers the theme from the directory
+it runs in — so the command is identical for every theme.
+
+## Modes
+
+| Command                                              | What it runs                                                  |
+| ---------------------------------------------------- | ------------------------------------------------------------- |
+| `pnpm -C themes/<name> theme:editor`                 | theme dev server **+** gateway (the normal flow)              |
+| `pnpm -C packages/theme-dev-host dev --theme <name>` | gateway only (when the theme's `pnpm dev` is already running) |
+
+## Flags (`theme:editor`)
+
+| Flag                   | Default                                    | Purpose                                                                                                                                                                                                                           |
+| ---------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<name>` (positional)  | inferred from the invoking theme dir       | override the theme dir under `themes/`                                                                                                                                                                                            |
+| `--port`               | `4101`                                     | gateway port (the preview origin)                                                                                                                                                                                                 |
+| `--theme-port`         | auto (read from the theme's `vite.config`) | the theme's own dev port                                                                                                                                                                                                          |
+| `--slug` / `--install` | `<name>` / `devinstall`                    | the `(shop-handle, install-id)` the gateway store-pins to — **must match the connected install** (install id is in the admin editor URL `/themes/<install-id>/editor`); defaults won't match a real store and 404 `unknown store` |
+| `--preset <handle>`    | the theme's `current.preset`               | load that preset's settings into the editor and make it the target **Save** writes back to (load-state / save-state); a missing handle opens empty and Save creates it                                                            |
+| `--tunnel [provider]`  | off                                        | expose the gateway publicly — `cloudflared` (default, no signup), `ngrok`, `zrok`                                                                                                                                                 |
+| `--public-url <url>`   | —                                          | with `--tunnel manual`: front the gateway with any tunnel you run yourself                                                                                                                                                        |
+| `--env`                | `dev`                                      | platform whose public key verifies editor tokens (`dev`/`staging`/`prod`)                                                                                                                                                         |
+
+Editor write routes require a signature-verified RS256 JWT; pair a hosted-prod
+admin with `--env prod` so the right key verifies it.
+
+## Saving back to source
+
+The editor's draft is in-memory — "publish" clears it, it doesn't persist. To
+commit your work, use the editor's **Save** (writes the current templates +
+section groups + settings into the theme's `src/`) or **Save as preset** (writes
+the current settings under a new named preset). Git is the checkpoint: Save →
+`src/` → commit. `--preset <handle>` picks which slot Save targets, so you can
+load one state, tweak, and Save back to it — or branch to a fresh name with Save
+as preset. Settings are **merged** into the preset map, so sibling presets are
+never clobbered.
+
+Without `--tunnel` the gateway is localhost-only. With `--tunnel`, paste the
+printed public URL into the **hosted** admin theme-editor (actions menu → "Local
+dev preview") to preview your local theme there — no backend or local admin
+needed. HMR there dials `ws://localhost:<theme-port>`, so it only works in a
+browser on the same machine as the dev server. See
+[docs/theme-dev-host.md](../../docs/theme-dev-host.md).
+
+## Test
+
+```bash
+pnpm -C packages/theme-dev-host test
+```

package/certs/jwtRS256.dev.pub

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxvrVRevpM9Q4DE8mWony
+MYK2AKBKEXA9sxkerBSAJutggePuPn65xwOC4V90+0SUeXUeobe8Ux0QT3QKy244
+oqE3Ykkonwin3+Ws81ZmI4zzo7d1MXXHkuRko64JJT1LHtOYNsxI209177qxxf6J
+tmprUic5tyq8U2TgcbK4qd38mSLI4QFOieDU0r3uqc8U7S4A9NnHzrba9/lUIouJ
+RvU1j0k4wonnk0idAkRuTWLmQRAcNZQnAVQvQ9t9ShLCC0FSnD2quvV3V1r0YnWY
++sYRy67zVvJ8DgyhIuJdX8cpWPWTh0DUTspHSPMufmeeq058IIkixJz2poDIdtLl
+/wIDAQAB
+-----END PUBLIC KEY-----

package/certs/jwtRS256.prod.pub

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqC3UMe4gql3jXPDATrc3
+PeuwutddgDE1sXhuaX/3yjU0Nket0Rbaho82zSU4FgnXXSwtUWCXt+35+b35zLdO
+WzS24TaE/ZlP1LORm91nSKAvQdzPBIP5paA3/JljByLrWxv6fY6U2+ppGiSpO8fM
+n3ZLlIzk99F+hgNg/8cQy8QhaM7Wz6qiFJ93z3Gfbub3XwKmtdGQlCC86Kvh6GB2
+I5IyKZCfPmEAm15JJzh1zEXZZ+n/PgNcTh6xrJiuQM7/hyFpyKaSwn9NAO6Y1oUC
+tmhMLxuqsJGKQ9ci/83x/OU89cqV8Vt3GAN4M4r/B89cekjxvOuX9V/IzGxTtJti
+ZQIDAQAB
+-----END PUBLIC KEY-----

package/certs/jwtRS256.staging.pub

@@ -0,0 +1,9 @@
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu13KN25kdHurKIzWWOf4
+7nA2zqvEeARCqwOhbBzMjbxCB8wgN0a6LocM0Yqxveq1Hevc3cTnpSSFWhZabv8Q
+08gxgwkq8Ed1SC2KkjWIGxLJFsoUy0w0lHnWVJisHCcs9r9OLIjwWLVs9mDwRFZV
+DWNn75JZOc5B6fffP1KAvfU9S51I+Yy0GZyoegdcRDelJgeQEFL7U3aoNPpzFsaP
+2jeK0eGD37cSxI5XcoDZGoQno7YxFM6vA8wkMZSS7tF8Xo89UHgjpKThC+nhriQe
+OVLHiGYXryQojmNc9/3NpQMhlBIEmI+Joe0siSiiH7VWojwV4Mn0J4BeFOIRxTZ/
+ZQIDAQAB
+-----END PUBLIC KEY-----

package/dist/LICENSE.md

@@ -0,0 +1,39 @@
+# Cody Theme Development License
+
+Copyright (c) 2026 Cody LLC. All rights reserved except as granted below.
+
+"The Software" is this package, its source, and its documentation. "The
+Platform" is Cody, the commerce platform operated by Cody LLC.
+
+## 1. Grant
+
+You may use, copy and modify the Software, and distribute modified copies, solely
+to develop, test, and distribute themes, apps and other extensions that run on
+the Platform.
+
+## 2. Restrictions
+
+You may not:
+
+1. use the Software, or anything derived from it, with any commerce platform,
+   storefront or hosting service other than the Platform;
+2. use the Software to build a product that competes with the Platform;
+3. sublicense the Software, or distribute it other than as part of a theme,
+   app or extension for the Platform;
+4. remove or alter this license or any copyright notice in the Software.
+
+## 3. Your work
+
+Themes, apps and extensions you build with the Software are yours. The parts of
+the Software they include stay under this license.
+
+## 4. Termination
+
+This license ends automatically if you break any of its terms. You must then
+stop using the Software and delete your copies of it.
+
+## 5. No warranty
+
+The Software is provided "as is", without warranty of any kind. Cody LLC is not
+liable for any claim, damages or other liability arising from the Software or
+its use.

package/dist/auth.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { EditorAuthError } from "./verify.mjs";
+//#region src/auth.ts
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function reject(c, reason) {
+	console.warn(`theme-dev-host: 401 ${c.req.method} ${c.req.path} — ${reason}`);
+	return c.json({ error: reason }, 401);
+}
+async function applyJwt(c, header, verify) {
+	const claims = await verify(header.slice(7));
+	const storeSlug = c.req.param("storeSlug") ?? "";
+	const installId = c.req.param("installId") ?? "";
+	if (claims.shop_handle !== storeSlug) return reject(c, `shop mismatch (token shop_handle=${claims.shop_handle}, path=${storeSlug})`);
+	if (claims.install_id !== installId) return reject(c, `install mismatch (token install_id=${claims.install_id}, path=${installId})`);
+	c.set("sid", claims.sid);
+	c.set("shopHandle", storeSlug);
+	c.set("installId", installId);
+	return null;
+}
+function createEditorAuth(verify) {
+	const editorAuth = async (c, next) => {
+		const header = c.req.header("Authorization");
+		if (!header?.startsWith("Bearer ")) return reject(c, "missing bearer token");
+		try {
+			const fail = await applyJwt(c, header, verify);
+			if (fail) return fail;
+		} catch (err) {
+			if (err instanceof EditorAuthError) return reject(c, err.reason);
+			throw err;
+		}
+		await next();
+	};
+	const editorAuthOrPreview = async (c, next) => {
+		const header = c.req.header("Authorization");
+		if (header?.startsWith("Bearer ")) {
+			try {
+				const fail = await applyJwt(c, header, verify);
+				if (fail) return fail;
+			} catch (err) {
+				if (err instanceof EditorAuthError) return reject(c, err.reason);
+				throw err;
+			}
+			await next();
+			return;
+		}
+		if (c.req.method !== "GET") return reject(c, "missing bearer token");
+		const sid = c.req.query("sid") ?? c.req.header("X-Editor-Sid") ?? void 0;
+		if (!sid || !UUID_RE.test(sid)) return reject(c, "missing or invalid sid");
+		c.set("sid", sid);
+		c.set("shopHandle", c.req.param("storeSlug") ?? "");
+		c.set("installId", c.req.param("installId") ?? "");
+		await next();
+	};
+	return {
+		editorAuth,
+		editorAuthOrPreview
+	};
+}
+//#endregion
+export { createEditorAuth };

package/dist/drafts.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+//#region src/drafts.ts
+const sessions = /* @__PURE__ */ new Map();
+const MAX_SESSIONS = 100;
+function sessionFor(sid) {
+	let s = sessions.get(sid);
+	if (!s) {
+		if (sessions.size >= MAX_SESSIONS) {
+			const oldest = sessions.keys().next().value;
+			if (oldest !== void 0) sessions.delete(oldest);
+		}
+		s = {
+			templates: {},
+			groups: {}
+		};
+		sessions.set(sid, s);
+	}
+	return s;
+}
+const drafts = {
+	getSettings(sid) {
+		return sessions.get(sid)?.settings;
+	},
+	setSettings(sid, settings) {
+		sessionFor(sid).settings = settings;
+	},
+	getTemplate(sid, templateId) {
+		return sessions.get(sid)?.templates[templateId];
+	},
+	setTemplate(sid, templateId, template) {
+		sessionFor(sid).templates[templateId] = template;
+	},
+	getGroups(sid) {
+		return { ...sessions.get(sid)?.groups };
+	},
+	setGroup(sid, groupType, group) {
+		sessionFor(sid).groups[groupType] = group;
+	},
+	clear(sid) {
+		sessions.delete(sid);
+	}
+};
+//#endregion
+export { drafts };

package/dist/editor-app.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { LANG_RE, loadLocale, loadStorefrontLocale, parseLang, readJsonDir, resolveDisplayName, resolveTranslations, unwrapSettings } from "./locale.mjs";
+import { drafts } from "./drafts.mjs";
+import { isValidPresetHandle, writeSettingsPreset, writeThemeSourceFiles } from "./save.mjs";
+import "./auth.mjs";
+import path from "node:path";
+import "hono";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { currentPresetHandle } from "@shop-on/theme-contract/preset-listing";
+import { bodyLimit } from "hono/body-limit";
+//#region src/editor-app.ts
+const TEMPLATE_ID_RE = /^[A-Za-z0-9_.-]+$/;
+const invalidTemplateId = (id) => !id || !TEMPLATE_ID_RE.test(id) || /[/\\]|\.\./.test(id);
+const PREFIX = "/api/stores/:storeSlug/:installId";
+function registerEditorRoutes(app, configDir, auth, store, opts) {
+	const { editorAuth, editorAuthOrPreview } = auth;
+	const themeSrcDir = opts?.themeSrcDir;
+	const presetOverride = opts?.preset;
+	if (store) app.use(`${PREFIX}/*`, async (c, next) => {
+		const slug = c.req.param("storeSlug");
+		const install = c.req.param("installId");
+		if (slug !== store.slug || install !== store.install) {
+			console.warn(`theme-dev-host: rejected /api/stores/${slug}/${install}/* — gateway is pinned to ${store.slug}/${store.install}. Restart with --slug ${slug} --install ${install} (the install id is in the admin editor URL).`);
+			return c.json({ error: "unknown store" }, 404);
+		}
+		await next();
+	});
+	const writeBodyLimit = bodyLimit({
+		maxSize: 8388608,
+		onError: (c) => c.json({ error: "draft too large" }, 413)
+	});
+	async function loadSettingsData() {
+		try {
+			return JSON.parse(await readFile(path.join(configDir, "settings-data.json"), "utf-8"));
+		} catch {
+			return {};
+		}
+	}
+	async function liveSettings() {
+		return unwrapSettings(await loadSettingsData(), presetOverride);
+	}
+	async function diskTemplate(id) {
+		try {
+			return JSON.parse(await readFile(path.join(configDir, "templates", `${id}.json`), "utf-8"));
+		} catch {
+			return null;
+		}
+	}
+	async function sectionGroupsFor(sid) {
+		const groups = drafts.getGroups(sid);
+		try {
+			for (const file of await readdir(path.join(configDir, "section-groups"))) {
+				if (!file.endsWith(".json")) continue;
+				const data = JSON.parse(await readFile(path.join(configDir, "section-groups", file), "utf-8"));
+				if (data.type && !groups[data.type]) groups[data.type] = {
+					sections: data.sections ?? {},
+					order: data.order ?? []
+				};
+			}
+		} catch {}
+		return groups;
+	}
+	app.get(`${PREFIX}/editor-loader`, editorAuthOrPreview, async (c) => {
+		const sid = c.get("sid");
+		const locale = await loadLocale(configDir, parseLang(c));
+		const [schemaRaw, sections, blocks, templates, sectionGroups] = await Promise.all([
+			readFile(path.join(configDir, "settings-schema.json"), "utf-8").catch(() => null),
+			readJsonDir(path.join(configDir, "sections")),
+			readJsonDir(path.join(configDir, "blocks")),
+			readJsonDir(path.join(configDir, "templates")),
+			readJsonDir(path.join(configDir, "section-groups"))
+		]);
+		const themeSchema = (schemaRaw ? JSON.parse(schemaRaw) : []).map((s) => resolveTranslations(s, locale));
+		const settingsData = await loadSettingsData();
+		const settings = drafts.getSettings(sid) ?? unwrapSettings(settingsData, presetOverride);
+		const activePreset = presetOverride ?? settingsData.current?.preset ?? "default";
+		const initialTemplateData = {
+			sections: {},
+			order: [],
+			...drafts.getTemplate(sid, "index") ?? await diskTemplate("index")
+		};
+		initialTemplateData.section_groups = await sectionGroupsFor(sid);
+		let layoutSchema = {};
+		try {
+			layoutSchema = resolveTranslations(JSON.parse(await readFile(path.join(configDir, "layouts", "main.json"), "utf-8")), locale);
+		} catch {}
+		return c.json({
+			themeSchema,
+			sectionSchemas: sections.map(({ id, data }) => ({
+				type: id,
+				...resolveTranslations(data, locale)
+			})),
+			blockSchemas: blocks.map(({ id, data }) => ({
+				type: id,
+				...resolveTranslations(data, locale)
+			})),
+			templates: templates.map(({ id, data }) => ({
+				id,
+				name: resolveDisplayName(data, id, locale)
+			})),
+			sectionGroupDefaults: sectionGroups.map(({ data }) => resolveTranslations(data, locale)),
+			initialTemplateData,
+			layoutSchema,
+			settings,
+			activePreset
+		});
+	});
+	app.put(`${PREFIX}/draft`, editorAuth, writeBodyLimit, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body?.settings || typeof body.settings !== "object") return c.json({ error: "settings required" }, 400);
+		drafts.setSettings(c.get("sid"), body.settings);
+		return c.json({ ok: true });
+	});
+	app.put(`${PREFIX}/draft/template`, editorAuth, writeBodyLimit, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (invalidTemplateId(body?.templateId) || !body?.template) return c.json({ error: "templateId and template required" }, 400);
+		drafts.setTemplate(c.get("sid"), body.templateId, body.template);
+		return c.json({ ok: true });
+	});
+	app.put(`${PREFIX}/draft/section-group`, editorAuth, writeBodyLimit, async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body?.groupType || !body?.group) return c.json({ error: "groupType and group required" }, 400);
+		drafts.setGroup(c.get("sid"), body.groupType, body.group);
+		return c.json({ ok: true });
+	});
+	app.post(`${PREFIX}/publish`, editorAuth, async (c) => {
+		drafts.clear(c.get("sid"));
+		return c.json({
+			ok: true,
+			published: true
+		});
+	});
+	async function saveListingPreset() {
+		if (!themeSrcDir) return void 0;
+		try {
+			if (!(await stat(path.join(themeSrcDir, "listings"))).isDirectory()) return void 0;
+		} catch {
+			return;
+		}
+		const settingsData = await loadSettingsData();
+		return currentPresetHandle(settingsData, presetOverride) ?? "default";
+	}
+	app.post(`${PREFIX}/save`, editorAuth, writeBodyLimit, async (c) => {
+		if (!themeSrcDir) return c.json({ error: "save unavailable (no theme src)" }, 500);
+		const body = await c.req.json().catch(() => null);
+		if (!body?.files || typeof body.files !== "object") return c.json({ error: "files required" }, 400);
+		if (body.settings && !isValidPresetHandle(body.presetHandle)) return c.json({ error: "valid presetHandle required with settings" }, 400);
+		try {
+			const { written } = await writeThemeSourceFiles(themeSrcDir, body.files, { listingPreset: await saveListingPreset() });
+			if (body.settings && isValidPresetHandle(body.presetHandle)) {
+				await writeSettingsPreset(themeSrcDir, body.presetHandle, body.settings);
+				written.push("config/settings-data.json");
+			}
+			return c.json({
+				ok: true,
+				written
+			});
+		} catch (err) {
+			return c.json({ error: err.message }, 400);
+		}
+	});
+	app.post(`${PREFIX}/save-preset`, editorAuth, writeBodyLimit, async (c) => {
+		if (!themeSrcDir) return c.json({ error: "save unavailable (no theme src)" }, 500);
+		const body = await c.req.json().catch(() => null);
+		if (!isValidPresetHandle(body?.handle) || !body?.settings || typeof body.settings !== "object") return c.json({ error: "handle and settings required" }, 400);
+		await writeSettingsPreset(themeSrcDir, body.handle, body.settings, { makeCurrent: body.makeCurrent === true });
+		return c.json({ ok: true });
+	});
+	app.get(`${PREFIX}/settings`, editorAuthOrPreview, async (c) => {
+		return c.json(drafts.getSettings(c.get("sid")) ?? await liveSettings());
+	});
+	app.get(`${PREFIX}/template`, editorAuthOrPreview, async (c) => {
+		const id = c.req.query("templateId");
+		if (invalidTemplateId(id)) return c.json({ error: "invalid or missing templateId" }, 400);
+		const draft = drafts.getTemplate(c.get("sid"), id);
+		const template = draft ? { ...draft } : await diskTemplate(id);
+		if (!template) return c.json({ error: "Template not found" }, 404);
+		template.section_groups = await sectionGroupsFor(c.get("sid"));
+		return c.json(template);
+	});
+	app.get(`${PREFIX}/templates`, editorAuthOrPreview, async (c) => {
+		const locale = await loadLocale(configDir, parseLang(c));
+		const items = await readJsonDir(path.join(configDir, "templates"));
+		return c.json(items.map(({ id, data }) => ({
+			id,
+			name: resolveDisplayName(data, id, locale)
+		})));
+	});
+	app.get(`${PREFIX}/sections`, editorAuthOrPreview, async (c) => {
+		const locale = await loadLocale(configDir, parseLang(c));
+		const items = await readJsonDir(path.join(configDir, "sections"));
+		return c.json(items.map(({ id, data }) => ({
+			type: id,
+			...resolveTranslations(data, locale)
+		})));
+	});
+	app.get(`${PREFIX}/blocks`, editorAuthOrPreview, async (c) => {
+		const locale = await loadLocale(configDir, parseLang(c));
+		const items = await readJsonDir(path.join(configDir, "blocks"));
+		return c.json(items.map(({ id, data }) => ({
+			type: id,
+			...resolveTranslations(data, locale)
+		})));
+	});
+	app.get(`${PREFIX}/section-groups`, editorAuthOrPreview, async (c) => {
+		const locale = await loadLocale(configDir, parseLang(c));
+		const items = await readJsonDir(path.join(configDir, "section-groups"));
+		return c.json(items.map(({ data }) => resolveTranslations(data, locale)));
+	});
+	app.get(`${PREFIX}/storefront-strings`, editorAuthOrPreview, async (c) => {
+		const lang = c.req.query("lang");
+		if (!lang || !LANG_RE.test(lang)) return c.json({ error: "Invalid lang" }, 400);
+		return c.json(await loadStorefrontLocale(configDir, lang));
+	});
+	app.get(`${PREFIX}/layout-schema`, editorAuthOrPreview, async (c) => {
+		const layout = c.req.query("layout") ?? "main";
+		if (invalidTemplateId(layout)) return c.json({ error: "invalid layout" }, 400);
+		const locale = await loadLocale(configDir, parseLang(c));
+		try {
+			const raw = await readFile(path.join(configDir, "layouts", `${layout}.json`), "utf-8");
+			return c.json(resolveTranslations(JSON.parse(raw), locale));
+		} catch {
+			return c.json({ error: "Layout not found" }, 404);
+		}
+	});
+}
+//#endregion
+export { registerEditorRoutes };

package/dist/gateway.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { materializeThemeConfig, watchThemeConfig } from "./materialize.mjs";
+import { createEditorVerifier } from "./verify.mjs";
+import { createEditorAuth } from "./auth.mjs";
+import { registerEditorRoutes } from "./editor-app.mjs";
+import { createProxy } from "./proxy.mjs";
+import { mkdtempSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+//#region src/gateway.ts
+async function startGateway(opts) {
+	const themeSrcDir = path.join(opts.themeDir, "src");
+	const storesDir = mkdtempSync(path.join(os.tmpdir(), "theme-dev-host-"));
+	const configDir = path.join(storesDir, opts.slug, opts.install, "config");
+	await materializeThemeConfig(themeSrcDir, configDir, opts.preset);
+	const auth = createEditorAuth(createEditorVerifier(opts.jwtPublicKey));
+	const app = new Hono();
+	registerEditorRoutes(app, configDir, auth, {
+		slug: opts.slug,
+		install: opts.install
+	}, {
+		themeSrcDir,
+		preset: opts.preset
+	});
+	app.all("*", createProxy(`http://localhost:${opts.themePort}`));
+	const server = serve({
+		fetch: app.fetch,
+		port: opts.port
+	});
+	const watcher = opts.watch === false ? void 0 : watchThemeConfig(themeSrcDir, configDir, { preset: opts.preset });
+	return {
+		configDir,
+		themeSrcDir,
+		server,
+		close: () => {
+			watcher?.close();
+			server.close();
+		}
+	};
+}
+//#endregion
+export { startGateway };

package/dist/keys.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/keys.ts
+const PLATFORM_ENVS = [
+	"dev",
+	"staging",
+	"prod"
+];
+function isPlatformEnv(v) {
+	return PLATFORM_ENVS.includes(v);
+}
+function resolveJwtPublicKey(env) {
+	const fromEnv = process.env.JWT_PUBLIC_KEY;
+	if (fromEnv) return fromEnv.replaceAll("\\n", "\n");
+	const certPath = path.resolve(import.meta.dirname, "../certs", `jwtRS256.${env}.pub`);
+	return readFileSync(certPath, "utf-8");
+}
+//#endregion
+export { PLATFORM_ENVS, isPlatformEnv, resolveJwtPublicKey };

package/dist/launch.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { startGateway } from "./gateway.mjs";
+import { startTunnel } from "./tunnel.mjs";
+import { isPlatformEnv, resolveJwtPublicKey } from "./keys.mjs";
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/launch.ts
+function flagValue(name) {
+	const i = process.argv.indexOf(`--${name}`);
+	if (i < 0) return void 0;
+	const v = process.argv[i + 1];
+	return v && !v.startsWith("--") ? v : void 0;
+}
+const hasFlag = (name) => process.argv.includes(`--${name}`);
+function detectThemePort(themeDir) {
+	try {
+		const m = readFileSync(path.join(themeDir, "vite.config.ts"), "utf-8").match(/port:\s*(\d+)/);
+		if (m) return Number(m[1]);
+	} catch {}
+	return 3002;
+}
+const themeDir = path.resolve(flagValue("dir") ?? process.cwd());
+const theme = path.basename(themeDir);
+const port = Number(flagValue("port") ?? "4101");
+const themePort = Number(flagValue("theme-port") ?? detectThemePort(themeDir));
+const slug = flagValue("slug") ?? theme;
+const install = flagValue("install") ?? "devinstall";
+const preset = flagValue("preset");
+const env = flagValue("env") ?? "dev";
+if (!isPlatformEnv(env)) {
+	console.error(`--env must be one of dev|staging|prod (got "${env}")`);
+	process.exit(1);
+}
+const jwtPublicKey = resolveJwtPublicKey(env);
+const tunnelProvider = hasFlag("tunnel") ? flagValue("tunnel") ?? "cloudflared" : "none";
+const publicUrl = flagValue("public-url");
+const pm = process.env.npm_execpath;
+const [cmd, args] = !pm ? ["npm", ["run", "dev"]] : /\.[cm]?js$/.test(pm) ? [process.execPath, [
+	pm,
+	"run",
+	"dev"
+]] : [pm, ["run", "dev"]];
+const child = spawn(cmd, args, {
+	cwd: themeDir,
+	stdio: "inherit",
+	env: {
+		...process.env,
+		ORCHESTRATOR_URL: `http://localhost:${port}`,
+		STORE_SLUG: slug,
+		INSTALL_ID: install,
+		...preset ? { THEME_PRESET: preset } : {},
+		...tunnelProvider !== "none" ? { THEME_HMR_HOST: "localhost" } : {}
+	}
+});
+const gw = await startGateway({
+	themeDir,
+	port,
+	themePort,
+	slug,
+	install,
+	jwtPublicKey,
+	preset
+});
+let tunnel = null;
+try {
+	tunnel = await startTunnel(tunnelProvider, port, publicUrl);
+} catch (err) {
+	console.error(`tunnel: ${err.message}`);
+}
+const origin = tunnel?.url ?? `http://localhost:${port}`;
+console.log("");
+console.log(`theme:editor — ${theme} (slug=${slug}, install=${install})`);
+console.log(`  gateway     http://localhost:${port}   (editor API + storefront proxy)`);
+console.log(`  theme dev   http://localhost:${themePort}   (starting — first load compiles)`);
+console.log(`  editor auth verifying editor tokens against the ${env} platform key`);
+if (preset) console.log(`  preset      editing '${preset}' — Save writes back to this preset`);
+if (tunnel) console.log(`  public      ${tunnel.url}`);
+console.log("");
+console.log(`  preview origin → ${origin}`);
+console.log(tunnel ? "  ^ paste into the hosted admin theme-editor: actions menu → \"Local dev preview\"." : "  ^ localhost-only; add --tunnel to drive a hosted admin.");
+console.log("  Ctrl-C to stop both.");
+let shuttingDown = false;
+async function shutdown(code) {
+	if (shuttingDown) return;
+	shuttingDown = true;
+	child.kill("SIGINT");
+	await tunnel?.stop();
+	gw.close();
+	process.exit(code);
+}
+process.on("SIGINT", () => void shutdown(0));
+process.on("SIGTERM", () => void shutdown(0));
+child.on("exit", (code) => {
+	console.log(`\ntheme dev server exited — shutting down gateway.`);
+	shutdown(code ?? 0);
+});
+//#endregion
+export {};

package/dist/locale.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+//#region src/locale.ts
+async function readJsonDir(dir) {
+	let files;
+	try {
+		files = await readdir(dir);
+	} catch {
+		return [];
+	}
+	const results = [];
+	for (const file of files) {
+		if (!file.endsWith(".json")) continue;
+		try {
+			const raw = await readFile(path.join(dir, file), "utf-8");
+			results.push({
+				id: file.replace(".json", ""),
+				data: JSON.parse(raw)
+			});
+		} catch {}
+	}
+	return results;
+}
+function resolveTranslations(obj, locale) {
+	if (typeof obj === "string" && obj.startsWith("t:")) {
+		const key = obj.slice(2);
+		let cur = locale;
+		for (const p of key.split(".")) cur = cur?.[p];
+		return typeof cur === "string" ? cur : obj;
+	}
+	if (Array.isArray(obj)) return obj.map((v) => resolveTranslations(v, locale));
+	if (obj && typeof obj === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(obj)) out[k] = resolveTranslations(v, locale);
+		return out;
+	}
+	return obj;
+}
+/**
+* Resolve a human-readable display name for a config item. Tries `data.name`
+* through the locale, falls back to the id when the name is missing or its
+* `t:*` key isn't in the locale — never leaks a raw `t:*` token to clients.
+*/
+function resolveDisplayName(data, id, locale) {
+	const name = data?.name;
+	if (typeof name === "string" && name !== "") {
+		const resolved = resolveTranslations(name, locale);
+		if (typeof resolved === "string" && !resolved.startsWith("t:")) return resolved;
+	}
+	return id;
+}
+async function loadLocale(baseDir, lang) {
+	const localeDir = path.join(baseDir, "locales");
+	const read = async (file) => JSON.parse(await readFile(path.join(localeDir, file), "utf-8"));
+	try {
+		return await read(`${lang}.default.schema.json`);
+	} catch {
+		try {
+			const files = (await readdir(localeDir)).filter((f) => f.endsWith(".default.schema.json")).sort();
+			if (files[0]) return await read(files[0]);
+		} catch {}
+		return {};
+	}
+}
+/**
+* Buyer-facing catalog (`<lang>.default.json` — NOT the `.schema.json` editor
+* strings). Returns the catalog PLUS which shipped locale actually served it:
+* the admin Translations page labels its "default value" column with that
+* language, so the fallback must be visible, not silent.
+*/
+async function loadStorefrontLocale(baseDir, lang) {
+	const localeDir = path.join(baseDir, "locales");
+	const read = async (file) => JSON.parse(await readFile(path.join(localeDir, file), "utf-8"));
+	try {
+		return {
+			lang,
+			messages: await read(`${lang}.default.json`)
+		};
+	} catch {
+		try {
+			const files = (await readdir(localeDir)).filter((f) => f.endsWith(".default.json")).sort();
+			if (files[0]) return {
+				lang: files[0].replace(".default.json", ""),
+				messages: await read(files[0])
+			};
+		} catch {}
+		return {
+			lang,
+			messages: {}
+		};
+	}
+}
+const LANG_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+function parseLang(c) {
+	const raw = c.req.header("Accept-Language")?.split(",")[0]?.trim();
+	return raw && LANG_RE.test(raw) ? raw : "mn";
+}
+function unwrapSettings(data, preset) {
+	return data.presets ? data.presets[preset ?? data.current?.preset]?.settings ?? {} : data;
+}
+//#endregion
+export { LANG_RE, loadLocale, loadStorefrontLocale, parseLang, readJsonDir, resolveDisplayName, resolveTranslations, unwrapSettings };

package/dist/materialize.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { watch } from "node:fs";
+import path from "node:path";
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { LISTING_DIRS, currentPresetHandle, mergePresetJson } from "@shop-on/theme-contract/preset-listing";
+//#region src/materialize.ts
+const JSON_DIRS = [
+	"sections",
+	"blocks",
+	"templates",
+	"section-groups",
+	"layouts",
+	"locales"
+];
+async function copyJsonDir(srcDir, destDir) {
+	let files;
+	try {
+		files = await readdir(srcDir);
+	} catch {
+		return;
+	}
+	await mkdir(destDir, { recursive: true });
+	const wanted = new Set(files.filter((f) => f.endsWith(".json") && !f.startsWith("._")));
+	try {
+		for (const existing of await readdir(destDir)) if (existing.endsWith(".json") && !wanted.has(existing)) await rm(path.join(destDir, existing), { force: true });
+	} catch {}
+	for (const file of wanted) await copyFile(path.join(srcDir, file), path.join(destDir, file));
+}
+async function dirExists(dir) {
+	try {
+		return (await stat(dir)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+async function resolveActivePreset(themeSrcDir, presetOverride) {
+	let data = null;
+	try {
+		data = JSON.parse(await readFile(path.join(themeSrcDir, "config", "settings-data.json"), "utf-8"));
+	} catch {}
+	return currentPresetHandle(data, presetOverride);
+}
+async function overlayListingDir(listingDir, targetDir) {
+	let files;
+	try {
+		files = await readdir(listingDir);
+	} catch {
+		return;
+	}
+	await mkdir(targetDir, { recursive: true });
+	for (const file of files) {
+		if (!file.endsWith(".json") || file.startsWith("._")) continue;
+		const override = JSON.parse(await readFile(path.join(listingDir, file), "utf-8"));
+		const targetPath = path.join(targetDir, file);
+		let base = null;
+		try {
+			base = JSON.parse(await readFile(targetPath, "utf-8"));
+		} catch {}
+		const output = base === null ? override : mergePresetJson(base, override);
+		await writeFile(targetPath, `${JSON.stringify(output, null, 2)}\n`, "utf-8");
+	}
+}
+async function materializeThemeConfig(themeSrcDir, configDir, presetOverride) {
+	await mkdir(configDir, { recursive: true });
+	for (const dir of JSON_DIRS) await copyJsonDir(path.join(themeSrcDir, dir), path.join(configDir, dir));
+	try {
+		await copyFile(path.join(themeSrcDir, "config", "settings-schema.json"), path.join(configDir, "settings-schema.json"));
+	} catch {}
+	const settingsDataPath = path.join(configDir, "settings-data.json");
+	try {
+		await copyFile(path.join(themeSrcDir, "config", "settings-data.json"), settingsDataPath);
+	} catch {
+		await writeFile(settingsDataPath, "{}\n", "utf-8");
+	}
+	const activePreset = await resolveActivePreset(themeSrcDir, presetOverride);
+	if (activePreset) {
+		const listingDir = path.join(themeSrcDir, "listings", activePreset);
+		if (await dirExists(listingDir)) for (const dir of LISTING_DIRS) await overlayListingDir(path.join(listingDir, dir), path.join(configDir, dir));
+	}
+}
+function watchThemeConfig(themeSrcDir, configDir, opts = {}) {
+	const onError = opts.onError ?? ((err) => console.warn("[theme-dev-host] re-materialize failed:", err));
+	let timer;
+	return watch(themeSrcDir, { recursive: true }, (_event, filename) => {
+		if (!filename || !filename.toString().endsWith(".json")) return;
+		clearTimeout(timer);
+		timer = setTimeout(() => {
+			materializeThemeConfig(themeSrcDir, configDir, opts.preset).catch(onError);
+		}, 150);
+	});
+}
+//#endregion
+export { materializeThemeConfig, watchThemeConfig };

package/dist/proxy.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+//#region src/proxy.ts
+function createProxy(target) {
+	const targetOrigin = new URL(target).origin;
+	return async (c) => {
+		const incoming = new URL(c.req.url);
+		if (incoming.pathname.startsWith("//")) return c.text("bad request", 400);
+		const url = new URL(incoming.pathname + incoming.search, target);
+		if (url.origin !== targetOrigin) return c.text("bad request", 400);
+		const headers = new Headers(c.req.raw.headers);
+		headers.delete("host");
+		headers.delete("authorization");
+		const method = c.req.method;
+		const hasBody = method !== "GET" && method !== "HEAD";
+		let res;
+		try {
+			res = await fetch(url, {
+				method,
+				headers,
+				body: hasBody ? c.req.raw.body : void 0,
+				redirect: "manual",
+				...hasBody ? { duplex: "half" } : {}
+			});
+		} catch {
+			return c.text(`theme-dev-host: theme dev server not reachable at ${target} — is \`pnpm dev\` running for the theme?`, 502);
+		}
+		return new Response(res.body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res.headers
+		});
+	};
+}
+//#endregion
+export { createProxy };

package/dist/save.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { PRESET_HANDLE_RE } from "@shop-on/theme-contract/preset-listing";
+//#region src/save.ts
+function serialize(data) {
+	return `${JSON.stringify(data, null, 2)}\n`;
+}
+const WRITABLE_DIRS = /* @__PURE__ */ new Set(["templates", "section-groups"]);
+const FILE_RE = /^[A-Za-z0-9_.-]+\.json$/;
+function isWritableThemePath(rel) {
+	if (typeof rel !== "string" || rel.includes("\\")) return false;
+	const parts = rel.split("/");
+	if (parts.length !== 2) return false;
+	const [dir, file] = parts;
+	if (!dir || !file) return false;
+	return WRITABLE_DIRS.has(dir) && FILE_RE.test(file);
+}
+function isValidPresetHandle(handle) {
+	return typeof handle === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(handle);
+}
+async function writeThemeSourceFiles(themeSrcDir, files, opts = {}) {
+	const root = path.resolve(themeSrcDir);
+	const listingPreset = opts.listingPreset;
+	if (listingPreset !== void 0 && !PRESET_HANDLE_RE.test(listingPreset)) throw new Error(`invalid listing preset handle: ${listingPreset}`);
+	const written = [];
+	for (const [rel, data] of Object.entries(files)) {
+		if (!isWritableThemePath(rel)) throw new Error(`refusing to write disallowed path: ${rel}`);
+		const destRel = listingPreset ? `listings/${listingPreset}/${rel}` : rel;
+		const dest = path.resolve(root, destRel);
+		if (dest !== root && !dest.startsWith(root + path.sep)) throw new Error(`refusing to write outside theme src: ${rel}`);
+		await mkdir(path.dirname(dest), { recursive: true });
+		await writeFile(dest, serialize(data), "utf-8");
+		written.push(destRel);
+	}
+	return { written };
+}
+async function writeSettingsPreset(themeSrcDir, handle, settings, opts = {}) {
+	const file = path.join(themeSrcDir, "config", "settings-data.json");
+	let data = {};
+	try {
+		data = JSON.parse(await readFile(file, "utf-8"));
+	} catch {}
+	const presets = { ...data.presets };
+	presets[handle] = { settings };
+	const next = {
+		current: { preset: opts.makeCurrent || !data.current ? handle : data.current.preset },
+		presets
+	};
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(file, serialize(next), "utf-8");
+}
+//#endregion
+export { isValidPresetHandle, isWritableThemePath, writeSettingsPreset, writeThemeSourceFiles };

package/dist/tunnel.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+//#region src/tunnel.ts
+const PROVIDERS = {
+	cloudflared: {
+		argv: (port) => [
+			"cloudflared",
+			"tunnel",
+			"--url",
+			`http://localhost:${port}`
+		],
+		urlRe: /https:\/\/[a-z0-9-]+\.trycloudflare\.com/,
+		signup: false
+	},
+	ngrok: {
+		argv: (port) => [
+			"ngrok",
+			"http",
+			String(port),
+			"--log",
+			"stdout"
+		],
+		urlRe: /https:\/\/[a-z0-9-]+\.ngrok[-a-z0-9.]*\.(app|dev|io)/,
+		signup: true
+	},
+	zrok: {
+		argv: (port) => [
+			"zrok",
+			"share",
+			"public",
+			`http://localhost:${port}`
+		],
+		urlRe: /https:\/\/[a-z0-9-]+\.share\.zrok\.io/,
+		signup: true
+	}
+};
+function spawnTunnel(name, argv, urlRe) {
+	return new Promise((resolve, reject) => {
+		const proc = spawn(argv[0], argv.slice(1), { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let settled = false;
+		const scan = (buf) => {
+			const m = buf.toString().match(urlRe);
+			if (m && !settled) {
+				settled = true;
+				clearTimeout(timer);
+				resolve({
+					url: m[0],
+					stop: async () => {
+						proc.kill();
+					}
+				});
+			}
+		};
+		proc.stdout.on("data", scan);
+		proc.stderr.on("data", scan);
+		proc.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`${name} not found on PATH — install it, or use \`--tunnel manual --public-url <url>\`. (${err.message})`));
+		});
+		proc.on("exit", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`${name} exited (code ${code}) before printing a public URL`));
+		});
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			proc.kill();
+			reject(/* @__PURE__ */ new Error(`${name} timed out before printing a public URL`));
+		}, 3e4);
+	});
+}
+async function startTunnel(provider, port, publicUrl) {
+	if (provider === "none") return null;
+	if (provider === "manual") {
+		if (!publicUrl) throw new Error("`--tunnel manual` requires `--public-url <url>`");
+		return {
+			url: publicUrl,
+			stop: async () => {}
+		};
+	}
+	const p = PROVIDERS[provider];
+	return spawnTunnel(provider, p.argv(port), p.urlRe);
+}
+//#endregion
+export { startTunnel };

package/dist/verify.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { importSPKI, jwtVerify } from "jose";
+//#region src/verify.ts
+var EditorAuthError = class extends Error {
+	reason;
+	constructor(reason) {
+		super(reason);
+		this.reason = reason;
+		this.name = "EditorAuthError";
+	}
+};
+function createEditorVerifier(pem) {
+	let keyPromise;
+	return async (token) => {
+		if (!pem) throw new EditorAuthError("JWT public key not configured");
+		let key;
+		try {
+			key = await (keyPromise ??= importSPKI(pem, "RS256"));
+		} catch (err) {
+			throw new EditorAuthError(err.message);
+		}
+		try {
+			const { payload } = await jwtVerify(token, key, {
+				algorithms: ["RS256"],
+				issuer: "SPN"
+			});
+			const claims = payload;
+			if (!Array.isArray(claims.scp) || !claims.scp.includes("editor")) throw new EditorAuthError("wrong scope");
+			if (!claims.sid || !claims.shop_handle || !claims.install_id) throw new EditorAuthError("missing claims");
+			return claims;
+		} catch (err) {
+			if (err instanceof EditorAuthError) throw err;
+			throw new EditorAuthError(err.message);
+		}
+	};
+}
+//#endregion
+export { EditorAuthError, createEditorVerifier };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@shop-on/theme-dev-host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Local theme-editor dev server: serves the editor contract + proxies a theme's dev server behind one origin, so a theme runs locally and previews in a real admin theme-editor. Nucleus of the future theme CLI.",
+  "license": "SEE LICENSE IN dist/LICENSE.md",
+  "bin": {
+    "theme-dev-host": "./dist/launch.mjs"
+  },
+  "files": [
+    "dist",
+    "certs"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@hono/node-server": "^2.1.3",
+    "hono": "^4.13.12",
+    "jose": "^6.2.12",
+    "@shop-on/theme-contract": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.3",
+    "tsx": "^4.23.15",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "launch": "tsx src/launch.ts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }