@tanqory/dev-mcp 0.0.0-stage → 0.1.0-alpha.1

package/bundled/theme-kit/types/sdk/schema.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The settings schema DSL — the ONE place a Nova section or block declares its
+ * persisted settings in code. Everything else is derived from it:
+ *
+ *   schema ──► TypeScript prop types        (SettingsOf<typeof schema>)
+ *          ──► the adapter                   (resolveSettings: defaults, legacy, coercion)
+ *          ──► Storybook controls            (stories/argTypes.ts)
+ *          ──► contract drift validation     (validate.ts, against generated/*.json)
+ *
+ * Option IDs here are the PERSISTED IDs (what a store's saved JSON holds), never
+ * display labels. Labels come from the approved contract at display time.
+ */
+/** The editor control vocabulary used by the approved contracts. */
+export type Control = 'select' | 'boolean' | 'text' | 'textarea' | 'richtext' | 'url' | 'range' | 'number' | 'color' | 'image' | 'video' | 'menu' | 'collection' | 'product' | 'page' | 'blog' | 'article';
+/**
+ * How a persisted setting reaches the component:
+ *   prop    — passed through as the typed component prop of the same name
+ *   adapter — resolved by the adapter layer into data (a menu handle becomes a
+ *             Menu object, an image id an Image). The component takes the data.
+ */
+export type Binding = 'prop' | 'adapter';
+interface FieldBase<C extends Control, V, B extends Binding = 'prop'> {
+    readonly control: C;
+    readonly default: V;
+    readonly binding: B;
+    /** LEGACY-HIDDEN: saved values keep rendering; not a control for new stores. */
+    readonly legacyHidden?: boolean;
+    /** The semantic this setting controls — two visible fields must never share one. */
+    readonly semantic?: string;
+    /** Why a field that is not in the approved contract exists. Absent = it must be in the contract. */
+    readonly extension?: string;
+    /** The editor's label for the control (a theme's manifest build reads it; the key, humanised, when absent). */
+    readonly label?: string;
+    /** Helper text under the control. */
+    readonly info?: string;
+    /** Placeholder text in the control. */
+    readonly placeholder?: string;
+    /** The editor panel group the control is filed under. */
+    readonly group?: string;
+}
+export interface SelectField<O extends string = string> extends FieldBase<'select', O> {
+    readonly options: readonly O[];
+    /** The editor's label for each option id (the id itself when absent). */
+    readonly optionLabels?: Readonly<Partial<Record<O, string>>>;
+    /** Saved values that are no longer options → the option they render as. */
+    readonly legacy?: Readonly<Record<string, O>>;
+}
+export interface BooleanField extends FieldBase<'boolean', boolean> {
+}
+export interface TextField<C extends 'text' | 'textarea' | 'richtext' | 'url' | 'color' = 'text'> extends FieldBase<C, string> {
+}
+export interface RangeField extends FieldBase<'range' | 'number', number> {
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    /** Values the design snaps to (e.g. spacer 8·12·16·24…). */
+    readonly snap?: readonly number[];
+    /** The unit the editor shows beside a range ("px", "%"). */
+    readonly unit?: string;
+}
+export type ResourceControl = 'image' | 'video' | 'menu' | 'collection' | 'product' | 'page' | 'blog' | 'article';
+export interface ResourceField<C extends ResourceControl = ResourceControl> extends FieldBase<C, string, 'adapter'> {
+}
+export type Field = SelectField | BooleanField | TextField<'text' | 'textarea' | 'richtext' | 'url' | 'color'> | RangeField | ResourceField;
+type Opts = {
+    legacyHidden?: boolean;
+    semantic?: string;
+    extension?: string;
+    label?: string;
+    info?: string;
+    placeholder?: string;
+    group?: string;
+};
+declare function select<const O extends string>(options: readonly O[], def: NoInfer<O>): SelectField<O>;
+declare function select<const O extends string, const X extends Opts & {
+    legacy?: Record<string, NoInfer<O>>;
+    optionLabels?: Readonly<Partial<Record<NoInfer<O>, string>>>;
+}>(options: readonly O[], def: NoInfer<O>, opts: X): SelectField<O> & X;
+declare function resource<const C extends ResourceControl>(control: C, def?: string): ResourceField<C>;
+declare function resource<const C extends ResourceControl, const X extends Opts>(control: C, def: string, opts: X): ResourceField<C> & X;
+export declare const field: {
+    select: typeof select;
+    boolean: {
+        (def?: boolean | undefined): BooleanField;
+        <const X extends Opts>(def: boolean, opts: X): BooleanField & X;
+    };
+    text: {
+        (def?: string | undefined): TextField<"text">;
+        <const X extends Opts>(def: string, opts: X): TextField<"text"> & X;
+    };
+    textarea: {
+        (def?: string | undefined): TextField<"textarea">;
+        <const X extends Opts>(def: string, opts: X): TextField<"textarea"> & X;
+    };
+    richtext: {
+        (def?: string | undefined): TextField<"richtext">;
+        <const X extends Opts>(def: string, opts: X): TextField<"richtext"> & X;
+    };
+    url: {
+        (def?: string | undefined): TextField<"url">;
+        <const X extends Opts>(def: string, opts: X): TextField<"url"> & X;
+    };
+    color: {
+        (def?: string | undefined): TextField<"color">;
+        <const X extends Opts>(def: string, opts: X): TextField<"color"> & X;
+    };
+    range(def: number, min: number, max: number, step: number, opts?: Opts & {
+        snap?: readonly number[];
+        unit?: string;
+    }): RangeField;
+    /** A number input (contract control "number") — same resolution as range. */
+    number(def: number, min: number, max: number, step: number, opts?: Opts): RangeField;
+    /** A data picker: the persisted value is a handle/id; the adapter resolves it. */
+    resource: typeof resource;
+};
+export type Fields = Readonly<Record<string, Field>>;
+/** Where a schema came from: section or block, and which design family owns it. */
+export interface SchemaMeta {
+    /** global = a theme setting group (Nova 13 popup), not placed on a page. */
+    readonly kind: 'section' | 'block' | 'global';
+    readonly name: string;
+    /** Design family, e.g. '12A'. The validator reads the contract from here. */
+    readonly family: string;
+    /** Blocks a section accepts (sections only). */
+    readonly blocks?: readonly string[];
+    /** Blocks still accepted for saved stores but hidden from the picker. */
+    readonly legacyBlocks?: readonly string[];
+    /** Sections a block may be placed in (blocks only). */
+    readonly parents?: readonly string[];
+    /**
+     * Earlier persisted names of this block (blocks only). Saved content may still
+     * hold a node of that type: the section keeps accepting it (`legacyBlocks`),
+     * the theme renders it as this block, and the contract validator reads this
+     * block's contract under the old name. New content is written with `name`.
+     */
+    readonly legacyNames?: readonly string[];
+    /** How the editor names the block in "Add block" (blocks). */
+    readonly title?: string;
+    /** One line for the editor's picker. */
+    readonly description?: string;
+    readonly icon?: string;
+    /** Route context the block needs (`product`, `collection`, …): it is offered only where the page has it. */
+    readonly requiresContext?: readonly string[];
+}
+export interface Schema<F extends Fields = Fields> extends SchemaMeta {
+    readonly fields: F;
+}
+export declare function defineSchema<const F extends Fields>(meta: SchemaMeta, fields: F): Schema<F>;
+type ValueOf<F> = F extends SelectField<infer O> ? O : F extends BooleanField ? boolean : F extends RangeField ? number : string;
+/**
+ * The resolved settings of a schema: every visible field required (the adapter
+ * fills defaults), every LEGACY-HIDDEN field optional.
+ */
+export type SettingsOf<S extends Schema> = {
+    -readonly [K in keyof S['fields'] as S['fields'][K] extends {
+        binding: 'adapter';
+    } ? never : S['fields'][K] extends {
+        legacyHidden: true;
+    } ? never : K]: ValueOf<S['fields'][K]>;
+} & {
+    -readonly [K in keyof S['fields'] as S['fields'][K] extends {
+        binding: 'adapter';
+    } ? never : S['fields'][K] extends {
+        legacyHidden: true;
+    } ? K : never]?: ValueOf<S['fields'][K]>;
+};
+/** The raw adapter-bound (handle) values of a schema. */
+export type HandlesOf<S extends Schema> = {
+    -readonly [K in keyof S['fields'] as S['fields'][K] extends {
+        binding: 'adapter';
+    } ? K : never]: string;
+};
+export interface SettingIssue {
+    readonly key: string;
+    readonly code: 'unknown-option' | 'legacy-value' | 'coerced' | 'unknown-setting' | 'out-of-range';
+    readonly value: unknown;
+    readonly resolved?: unknown;
+}
+export interface Resolved<S extends Schema> {
+    readonly settings: SettingsOf<S>;
+    readonly handles: HandlesOf<S>;
+    /** Everything the adapter had to correct — surfaced in dev and asserted in tests. */
+    readonly issues: readonly SettingIssue[];
+}
+/**
+ * The adapter core: saved JSON settings → typed, complete settings.
+ *
+ *   - missing → the field default
+ *   - a legacy option → the option it renders as (issue: legacy-value)
+ *   - an unknown option → the default (issue: unknown-option), never a crash
+ *   - "true"/"false"/"32" strings → boolean / number (issue: coerced)
+ *   - LEGACY-HIDDEN fields keep their saved value (that is the point of them)
+ */
+export declare function resolveSettings<S extends Schema>(schema: S, raw: Readonly<Record<string, unknown>> | undefined): Resolved<S>;
+/** Defaults of a schema — what a brand-new section renders with. */
+export declare function defaultsOf<S extends Schema>(schema: S): SettingsOf<S>;
+export {};

package/bundled/versions.json

@@ -0,0 +1,8 @@
+{
+  "@tanqory/theme-abi": "2.0.0-alpha.14",
+  "@tanqory/theme-conformance": "0.1.0-alpha.14",
+  "@tanqory/theme-kit": "2.0.0-alpha.3",
+  "examples": {
+    "blank": "create-tanqory-theme templates/blank"
+  }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@tanqory/dev-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "Local MCP server (stdio) for building Tanqory storefront themes with coding agents: versioned docs and schemas, kit examples, section scaffolding, theme checks, and pages and screenshots of the running dev server.",
+  "keywords": [
+    "tanqory",
+    "theme",
+    "storefront",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex"
+  ],
+  "license": "MIT",
+  "author": "Tanqory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tanqory/tanqory-platform-packages.git",
+    "directory": "packages/tools/dev-mcp"
+  },
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "tanqory-dev-mcp": "./bin/tanqory-dev-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "bundled",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "playwright-core": "^1.56.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "create-tanqory-theme": "0.2.1"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check:public-files": "node scripts/check-public-files.mjs",
+    "sync:bundled": "node scripts/sync-bundled.mjs"
+  }
 }

package/src/bm25.mjs

@@ -0,0 +1,69 @@
+/**
+ * Okapi BM25 over a fixed corpus: deterministic, in memory, no network, no embeddings. Same input, same ranking
+ * (ties broken by corpus order).
+ */
+const STOP = new Set(
+  'a an and are as at be by can do does for from how i in into is it its of on or that the this to was what when where which who why will with you your'.split(
+    ' ',
+  ),
+)
+
+/** Lowercased terms; camelCase and compound identifiers (data-tq-node, useCart) also yield their parts. */
+export function tokenize(text) {
+  const out = []
+  for (const raw of String(text).match(/[\p{L}\p{N}][\p{L}\p{N}_.:-]*/gu) ?? []) {
+    const word = raw.replace(/[.:_-]+$/, '')
+    const lower = word.toLowerCase()
+    const parts = word
+      .split(/[._:-]+/)
+      .flatMap((p) => p.split(/(?<=[\p{Ll}\p{N}])(?=\p{Lu})/u))
+      .map((p) => p.toLowerCase())
+      .filter(Boolean)
+    if (parts.length > 1 && !STOP.has(lower)) out.push(lower)
+    for (const p of parts) if (!STOP.has(p) && (p.length > 1 || /\p{N}/u.test(p))) out.push(p)
+  }
+  return out
+}
+
+export class Bm25 {
+  /** @param {{ title: string, text: string }[]} docs */
+  constructor(docs, { k1 = 1.2, b = 0.75, titleWeight = 3 } = {}) {
+    this.k1 = k1
+    this.b = b
+    this.tf = []
+    this.len = []
+    this.df = new Map()
+    for (const d of docs) {
+      const terms = [...tokenize(d.text)]
+      const title = tokenize(d.title)
+      for (let i = 0; i < titleWeight; i++) terms.push(...title)
+      const tf = new Map()
+      for (const t of terms) tf.set(t, (tf.get(t) ?? 0) + 1)
+      for (const t of tf.keys()) this.df.set(t, (this.df.get(t) ?? 0) + 1)
+      this.tf.push(tf)
+      this.len.push(terms.length)
+    }
+    this.n = docs.length
+    this.avg = this.len.reduce((a, b2) => a + b2, 0) / Math.max(1, this.n)
+  }
+
+  /** @returns {{ index: number, score: number }[]} best first */
+  search(query, limit = 10) {
+    const q = [...new Set(tokenize(query))]
+    if (!q.length) return []
+    const scores = []
+    for (let i = 0; i < this.n; i++) {
+      let s = 0
+      for (const t of q) {
+        const f = this.tf[i].get(t)
+        if (!f) continue
+        const df = this.df.get(t)
+        const idf = Math.log(1 + (this.n - df + 0.5) / (df + 0.5))
+        s += (idf * f * (this.k1 + 1)) / (f + this.k1 * (1 - this.b + (this.b * this.len[i]) / this.avg))
+      }
+      if (s > 0) scores.push({ index: i, score: s })
+    }
+    scores.sort((x, y) => y.score - x.score || x.index - y.index)
+    return scores.slice(0, limit)
+  }
+}

package/src/browser.mjs

@@ -0,0 +1,123 @@
+/**
+ * One headless Chromium per server process, started on first use. playwright-core is resolved from the theme
+ * first (its Chromium is usually already downloaded by `npm run check`), else from this package. If no browser
+ * binary exists it is downloaded once with Playwright's own installer, unless TANQORY_MCP_NO_BROWSER_DOWNLOAD=1.
+ * TANQORY_CHROMIUM_PATH uses an existing Chrome/Chromium instead.
+ */
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const VIEWPORTS = {
+  mobile: { width: 390, height: 844, deviceScaleFactor: 2, isMobile: true, hasTouch: true },
+  desktop: { width: 1280, height: 900, deviceScaleFactor: 1, isMobile: false, hasTouch: false },
+}
+
+export class BrowserUnavailable extends Error {
+  constructor(message, hint) {
+    super(message)
+    this.code = 'browser_unavailable'
+    this.hint = hint
+  }
+}
+
+const HINT = 'Run `npx playwright install chromium` (on Linux add `--with-deps`) or set TANQORY_CHROMIUM_PATH to a Chrome/Chromium binary, then call the tool again.'
+
+async function loadPlaywright(root) {
+  const bases = [root && join(root, 'package.json'), import.meta.url].filter(Boolean)
+  for (const base of bases) {
+    try {
+      const req = createRequire(base)
+      const main = req.resolve('playwright-core')
+      const mod = await import(pathToFileURL(main).href)
+      const chromium = mod.chromium ?? mod.default?.chromium
+      if (chromium) return { chromium, dir: dirname(req.resolve('playwright-core/package.json')), from: base === import.meta.url ? 'dev-mcp' : 'theme' }
+    } catch {
+      // next base
+    }
+  }
+  throw new BrowserUnavailable('playwright-core could not be loaded.', 'Reinstall @tanqory/dev-mcp (it depends on playwright-core).')
+}
+
+export class Browser {
+  constructor(root, log = () => {}) {
+    this.root = root
+    this.log = log
+    this.pending = null
+  }
+
+  async launch() {
+    const pw = await loadPlaywright(this.root)
+    const opts = { headless: true, ...(process.env.TANQORY_CHROMIUM_PATH ? { executablePath: process.env.TANQORY_CHROMIUM_PATH } : {}) }
+    try {
+      return await pw.chromium.launch(opts)
+    } catch (e) {
+      const missing = /Executable doesn't exist|browserType\.launch: .*(not found|ENOENT)/i.test(e.message)
+      if (!missing || opts.executablePath || process.env.TANQORY_MCP_NO_BROWSER_DOWNLOAD === '1')
+        throw new BrowserUnavailable(`Headless Chromium could not start: ${e.message.split('\n')[0]}`, HINT)
+      this.log(`Chromium is not installed for playwright-core (${pw.from}); downloading it once…`)
+      const r = spawnSync(process.execPath, [join(pw.dir, 'cli.js'), 'install', 'chromium'], { stdio: ['ignore', 2, 2], timeout: 10 * 60 * 1000 })
+      if (r.status !== 0) throw new BrowserUnavailable('Headless Chromium is not installed and the download failed.', HINT)
+      try {
+        return await pw.chromium.launch(opts)
+      } catch (e2) {
+        throw new BrowserUnavailable(`Headless Chromium could not start after the download: ${e2.message.split('\n')[0]}`, HINT)
+      }
+    }
+  }
+
+  async browser() {
+    if (!this.pending) {
+      this.pending = this.launch()
+      this.pending.catch(() => {
+        this.pending = null
+      })
+    }
+    return this.pending
+  }
+
+  /**
+   * Load `url` and run `fn(page)`; collects console errors, uncaught exceptions and failed same-origin requests.
+   * @template T
+   * @param {string} url
+   * @param {{ viewport?: keyof VIEWPORTS | { width: number, height: number } }} o
+   * @param {(page: any) => Promise<T>} fn
+   */
+  async withPage(url, { viewport = 'desktop' } = {}, fn) {
+    const b = await this.browser()
+    const vp = typeof viewport === 'string' ? VIEWPORTS[viewport] : { width: viewport.width, height: viewport.height, deviceScaleFactor: 1 }
+    const context = await b.newContext({ viewport: { width: vp.width, height: vp.height }, deviceScaleFactor: vp.deviceScaleFactor, isMobile: vp.isMobile ?? false, hasTouch: vp.hasTouch ?? false })
+    const errors = []
+    const origin = new URL(url).origin
+    try {
+      const page = await context.newPage()
+      page.on('console', (m) => {
+        if (m.type() === 'error') errors.push({ kind: 'console', message: m.text().slice(0, 1000), location: m.location()?.url ? `${m.location().url}:${m.location().lineNumber ?? 0}` : undefined })
+      })
+      page.on('pageerror', (e) => errors.push({ kind: 'exception', message: String(e.message ?? e).slice(0, 1000) }))
+      page.on('response', (r) => {
+        if (r.status() >= 400 && r.url().startsWith(origin) && r.request().resourceType() !== 'document') errors.push({ kind: 'request', message: `${r.status()} ${r.request().method()} ${r.url().slice(origin.length)}` })
+      })
+      let status = null
+      try {
+        const res = await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 })
+        status = res?.status() ?? null
+      } catch (e) {
+        if (!/Timeout/i.test(e.message)) throw e
+        errors.push({ kind: 'timeout', message: 'The page did not reach network idle within 30 s; captured as it was.' })
+      }
+      await page.waitForTimeout(250)
+      const result = await fn(page)
+      return { status, errors, viewport: { width: vp.width, height: vp.height }, result }
+    } finally {
+      await context.close().catch(() => {})
+    }
+  }
+
+  async close() {
+    const p = this.pending
+    this.pending = null
+    if (p) await p.then((b) => b.close()).catch(() => {})
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,127 @@
+/**
+ * The Tanqory CLI is the engine; this server only calls it. Contract (CLI v2):
+ *
+ *   tanqory <cmd> --json   → exactly one JSON object on stdout:
+ *                            { ok: boolean, command: string, data?: any, error?: { code, message, hint? } }
+ *                            logs on stderr.
+ *
+ * Which CLI: the one that started this server (`tanqory mcp` passes itself), else TANQORY_CLI, else the theme's
+ * node_modules/.bin/tanqory, else `tanqory` on PATH. Never `npx` at call time: a check must not silently download
+ * a different CLI than the developer installed.
+ */
+import { spawn } from 'node:child_process'
+import { accessSync, constants, existsSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+const JS = /\.(m|c)?js$/
+
+function onPath(name) {
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue
+    for (const ext of process.platform === 'win32' ? ['.cmd', '.exe', ''] : ['']) {
+      const p = join(dir, name + ext)
+      try {
+        accessSync(p, constants.X_OK)
+        return p
+      } catch {
+        // next
+      }
+    }
+  }
+  return null
+}
+
+/** @returns {{ command: string, args: string[], via: string } | null} */
+export function resolveCli({ root, cli } = {}) {
+  if (cli) return { ...cli, args: cli.args ?? [], via: cli.via ?? 'host' }
+  const env = process.env.TANQORY_CLI
+  if (env) {
+    if (env.trim().startsWith('[')) {
+      const [command, ...args] = JSON.parse(env)
+      return { command, args, via: 'TANQORY_CLI' }
+    }
+    return JS.test(env) ? { command: process.execPath, args: [env], via: 'TANQORY_CLI' } : { command: env, args: [], via: 'TANQORY_CLI' }
+  }
+  if (root) {
+    const local = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'tanqory.cmd' : 'tanqory')
+    if (existsSync(local)) return { command: local, args: [], via: 'theme node_modules' }
+  }
+  const global = onPath('tanqory')
+  return global ? { command: global, args: [], via: 'PATH' } : null
+}
+
+export class CliError extends Error {
+  constructor(code, message, hint, extra = {}) {
+    super(message)
+    this.code = code
+    this.hint = hint
+    Object.assign(this, extra)
+  }
+}
+
+const MAX_STDOUT = 16 * 1024 * 1024
+
+/** Pull the contract envelope out of stdout: the whole of it, else the last line that parses as one. */
+export function parseEnvelope(stdout) {
+  const text = stdout.trim()
+  const candidates = [text, ...text.split('\n').reverse()]
+  for (const c of candidates) {
+    try {
+      const v = JSON.parse(c)
+      if (v && typeof v === 'object' && typeof v.ok === 'boolean' && typeof v.command === 'string') return v
+    } catch {
+      // next
+    }
+  }
+  return null
+}
+
+/**
+ * Run `tanqory <args> --json` in the theme root. Resolves the envelope (ok true or false); rejects with CliError
+ * only when there is no usable answer (no CLI, timeout, not the JSON contract).
+ */
+export function runCli(args, { root, cli, timeoutMs = 10 * 60 * 1000, signal } = {}) {
+  const bin = resolveCli({ root, cli })
+  if (!bin)
+    return Promise.reject(
+      new CliError('cli_not_found', 'The Tanqory CLI (`tanqory`) was not found: not in this theme\'s node_modules and not on PATH.', 'Install it in the theme (`npm install --save-dev @tanqory/cli`) or start this server with `npx -y @tanqory/cli mcp`. TANQORY_CLI may point at a CLI binary.'),
+    )
+  const argv = [...bin.args, ...args, '--json']
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin.command, argv, { cwd: root ?? process.cwd(), env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' }, stdio: ['ignore', 'pipe', 'pipe'], signal })
+    let out = ''
+    let err = ''
+    let killed = false
+    const timer = setTimeout(() => {
+      killed = true
+      child.kill('SIGTERM')
+      setTimeout(() => child.kill('SIGKILL'), 5000).unref()
+    }, timeoutMs)
+    child.stdout.on('data', (d) => {
+      if (out.length < MAX_STDOUT) out += d
+    })
+    child.stderr.on('data', (d) => {
+      err = (err + d).slice(-8000)
+    })
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      reject(new CliError('cli_failed_to_start', `Could not start the Tanqory CLI (${bin.command}): ${e.message}`, 'Check the CLI is installed and executable.'))
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      const cmd = `tanqory ${args.join(' ')} --json`
+      if (killed) return reject(new CliError('cli_timeout', `\`${cmd}\` did not finish within ${Math.round(timeoutMs / 1000)} s and was stopped.`, 'Run it in a terminal to see where it hangs.', { stderr: err }))
+      const env = parseEnvelope(out)
+      if (!env)
+        return reject(
+          new CliError(
+            'cli_protocol_error',
+            `\`${cmd}\` exited ${code} without the JSON result this server expects on stdout.`,
+            'This server needs Tanqory CLI v2 (`--json` on every command). Update @tanqory/cli; until then run the command in a terminal.',
+            { stderr: err.trim().split('\n').slice(-20).join('\n'), exitCode: code },
+          ),
+        )
+      resolve({ ...env, exitCode: code, stderrTail: err.trim().split('\n').slice(-20).join('\n'), via: bin.via })
+    })
+  })
+}

package/src/devserver.mjs

@@ -0,0 +1,82 @@
+/**
+ * The running `tanqory theme dev` server. Contract (CLI v2):
+ *
+ *   .tanqory/dev-server.json   { pid, url, port, store: { id, handle }, mode: "store" | "mock", startedAt }
+ *   GET /__tq/status           { ok, theme: { name, manifestDigest }, lastBuild: { ok, at, errors: [{ file, line, message }] } }
+ *   GET /__tq/page?path=&locale=&market=   { status, html, consoleErrors: [], serverLogs: [] }
+ *   GET /__tq/store-summary    what the store has to design against
+ *
+ * Only loopback URLs are used: the server never fetches a remote host because a file said so.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const DEV_SERVER_FILE = join('.tanqory', 'dev-server.json')
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+export class DevServerError extends Error {
+  constructor(code, message, hint) {
+    super(message)
+    this.code = code
+    this.hint = hint
+  }
+}
+
+const alive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return null
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return e.code === 'EPERM'
+  }
+}
+
+const NOT_RUNNING_HINT = 'Start it yourself in the background from the theme folder: `npm run dev -- --mock` (offline fixture store; `npm run dev` when signed in with `npx tanqory login`), wait until dev_server_status says it is running, then call this tool again. Stop it later with `npm run dev -- --stop`, never pkill.'
+
+/** The dev-server record, or a reason it cannot be used. Never throws. */
+export function readDevServer(root) {
+  if (!root) return { running: false, reason: 'no_theme', hint: 'Open the server in a theme folder (one with tanqory.config.json).' }
+  let rec
+  try {
+    rec = JSON.parse(readFileSync(join(root, DEV_SERVER_FILE), 'utf8'))
+  } catch (e) {
+    return { running: false, reason: e.code === 'ENOENT' ? 'not_started' : 'unreadable_record', hint: NOT_RUNNING_HINT }
+  }
+  let url
+  try {
+    url = new URL(rec.url)
+  } catch {
+    return { running: false, reason: 'invalid_record', hint: `${DEV_SERVER_FILE} has no valid url. ${NOT_RUNNING_HINT}` }
+  }
+  if (!LOOPBACK.has(url.hostname) || !/^https?:$/.test(url.protocol))
+    return { running: false, reason: 'not_loopback', hint: `${DEV_SERVER_FILE} points at ${url.host}; only a localhost dev server is used.` }
+  const pidAlive = alive(rec.pid)
+  if (pidAlive === false) return { running: false, reason: 'stale_record', record: rec, hint: `The dev server (pid ${rec.pid}) is no longer running. ${NOT_RUNNING_HINT}` }
+  return { running: true, record: { ...rec, url: url.origin } }
+}
+
+export async function devGet(origin, path, { timeoutMs = 60000 } = {}) {
+  let res
+  try {
+    res = await fetch(`${origin}${path}`, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } })
+  } catch (e) {
+    throw new DevServerError('dev_server_unreachable', `The dev server at ${origin} did not answer ${path.split('?')[0]}: ${e.cause?.code ?? e.name}.`, NOT_RUNNING_HINT)
+  }
+  const text = await res.text()
+  let body
+  try {
+    body = JSON.parse(text)
+  } catch {
+    throw new DevServerError('dev_server_protocol_error', `${path.split('?')[0]} answered ${res.status} without JSON.`, 'The dev server needs Tanqory CLI v2; restart `tanqory theme dev` after updating.')
+  }
+  if (!res.ok && res.status !== 404) throw new DevServerError('dev_server_error', `${path.split('?')[0]} answered ${res.status}: ${body?.error?.message ?? text.slice(0, 200)}`, body?.error?.hint ?? 'See the `tanqory theme dev` terminal.')
+  return { status: res.status, body }
+}
+
+/** Require a running dev server; throws DevServerError otherwise. */
+export function requireDevServer(root) {
+  const s = readDevServer(root)
+  if (!s.running) throw new DevServerError('dev_server_not_running', `No running dev server (${s.reason}).`, s.hint)
+  return s.record
+}