create-tanqory-theme 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanqory
+
+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,56 @@
-# Temporary Holding Version
+# create-tanqory-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.
+```bash
+npm create tanqory-theme@latest my-theme
+```
+
+Creates a Tanqory storefront theme (Theme ABI v2) that builds and passes the platform's checks with nothing but
+the public npm registry: no token, no private registry, no git clone. Everything the project needs ships inside
+this package.
+
+## Templates
+
+| Template          | What you get                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `blank` (default) | Unstyled. Every storefront function wired through `@tanqory/theme-kit/headless` (variants and `?variant=`, cart drawer and cart page, checkout hand-off, sort / filter / pagination, predictive search, markets and languages, forms, consent, SEO and JSON-LD, th/en, live edit, the AI-compat profile) with minimal neutral CSS. Start here for a theme of your own design. |
+| `nova`            | A standalone fork of Nova V3, the Tanqory reference theme: sections, components, styles, starter content, contracts tooling and its test suite. Needs Node ≥ 22.6.                                                                                                                                                                                                            |
+
+```bash
+npm create tanqory-theme@latest my-theme -- --template nova
+pnpm create tanqory-theme my-theme --template blank --yes
+```
+
+Options: `--template <blank|nova>`, `--yes` (defaults: `my-theme`, `blank`), `--no-install`,
+`--package-manager <npm|pnpm|yarn|bun>` (default: the one running the command).
+
+## What is in the project
+
+```
+my-theme/
+├── AGENTS.md, CLAUDE.md        the rules for coding agents (one text, two names)
+├── .mcp.json                   Claude Code   ─┐
+├── .codex/config.toml          Codex          │ the Tanqory MCP server:
+├── .vscode/mcp.json            VS Code        │ npx -y @tanqory/cli mcp
+├── .gemini/settings.json       Gemini CLI    ─┘
+├── .github/workflows/theme-check.yml   build + test + check on every push and PR
+├── tanqory.config.json         the store and output the CLI uses
+├── tests/                      vitest
+└── package.json                dev · build · check · test · typecheck
+```
+
+| Script                           | Does                                                                                                                             |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `npm run build`                  | the theme → `dist/abi` (manifest, browser bundle, single-file server entry, defaults, locales)                                   |
+| `npm run check`                  | `theme-conformance run dist/abi --tier all`: security (the 9 ABI suites), storefront, budgets; reports in `reports/`             |
+| `npm test` / `npm run typecheck` | vitest / tsc                                                                                                                     |
+| `npm run dev`                    | `tanqory theme dev`: localhost:9292 with real store data (after `npx tanqory login`), editor at `/__editor`; `-- --mock` offline |
+
+## Maintainers
+
+- `templates/blank` derives from the kit's Aurora example with its styling removed; `templates/common` is copied
+  into every project; `lib/agents.mjs` is the single source of `AGENTS.md` / `CLAUDE.md`.
+- `templates/nova` is generated, never edited by hand:
+  `node scripts/sync-nova-template.mjs <nova-v3 source dir> <commit>` (see the script header for what it changes).
+- Both templates pin the same exact `@tanqory/*` versions (`test/create.test.mjs`).
+- The package is `"private": true` until the owner's licence decision: remove `private` to let the next
+  changesets release publish it to npmjs (its first publish needs npm 2FA, so the owner publishes it by hand).

package/bin/create-tanqory-theme.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ *     npm create tanqory-theme@latest my-theme
+ *
+ * Scaffolds a Tanqory storefront theme (Theme ABI v2) from a template that ships inside this package.
+ */
+import { main } from '../lib/create.mjs'
+
+if (Number(process.versions.node.split('.')[0]) < 20) {
+  console.error(`\n  create-tanqory-theme needs Node.js 20 or newer (this is ${process.version}).\n`)
+  process.exit(1)
+}
+process.exitCode = await main()

package/lib/agents.mjs

@@ -0,0 +1,118 @@
+/**
+ * The agent instructions every scaffolded theme ships:
+ *   - AGENTS.md (Codex, Copilot, Gemini CLI, Cursor …) and CLAUDE.md (Claude Code), identical bytes;
+ *   - .claude/skills/tanqory-theme/SKILL.md, the same workflow as a Claude Code project skill.
+ * One source, here, so they can never drift; `test/create.test.mjs` asserts it.
+ *
+ * The workflow block is first and short on purpose: coding agents skim long instructions, and Claude Code shows
+ * MCP tools as deferred (behind ToolSearch), so an agent that is not handed the exact tool names rarely loads them.
+ * The rules are the platform's acceptance bar, not style advice: each one is something `tanqory theme check`
+ * fails on.
+ */
+
+/** The Tanqory MCP tools the workflow names, as Claude Code exposes them (server `tanqory`). */
+export const MCP_TOOLS = ['scaffold_section', 'screenshot', 'get_page', 'check_theme', 'dev_server_status', 'search_docs', 'get_kit_example']
+export const claudeName = (tool) => `mcp__tanqory__${tool}`
+
+/**
+ * The workflow, imperative and numbered. Shared by AGENTS.md / CLAUDE.md and the skill.
+ * @param {{ id: string }} template
+ */
+export function workflow(template) {
+  const select = MCP_TOOLS.map(claudeName).join(',')
+  const scaffold =
+    template.id === 'blank'
+      ? `**New section → \`scaffold_section\`** (\`${claudeName('scaffold_section')}\`). Call it with \`name\`, \`purpose\` and \`template: "index"\`; it returns a plan. Call it again with the same arguments plus \`confirm: true\` and the \`planDigest\`. It writes the section, its settings, en + th keys, CSS and a test, wired to the kit. Then restyle it. For any kit API use \`search_docs\` / \`get_kit_example\` instead of reading node_modules.`
+      : `**New section → copy the closest section in \`src/sections/\`** and keep its kit wiring (\`scaffold_section\` writes the Blank layout only). For any kit API use \`search_docs\` / \`get_kit_example\` (\`${claudeName('get_kit_example')}\`) instead of reading node_modules.`
+  return `## Workflow: do this for every change
+
+The **Tanqory MCP server** (\`tanqory\`) is configured in this folder. Use its tools for the steps below; the shell commands are only the fallback. In Claude Code the tools are deferred: load them first with ToolSearch \`select:${select}\`. Other hosts list the same tool names under the \`tanqory\` server.
+
+1. **Start the dev server in the background** and keep it running: \`npm run dev -- --mock\` (offline fixture store; plain \`npm run dev\` once \`npx tanqory login\` is done). It rebuilds on every save. \`dev_server_status\` says when it is up; if the server exits instead, read its output and start it again.
+2. ${scaffold}
+3. **Look at your work → \`screenshot\`** (\`${claudeName('screenshot')}\`) of the page you changed, \`viewport: "desktop"\` and \`"mobile"\`, \`locale: "th"\` and \`"en"\`; **\`get_page\`** (\`${claudeName('get_page')}\`) for the HTML and console errors. Fix what looks wrong and look again.
+4. **Verify → \`check_theme\`** (\`${claudeName('check_theme')}\`), not \`npm run check\`: the same checks as \`tanqory theme check\`, returned as JSON failures with the check id, route, fix hint and file:line when known. Fix **every** failure, including ones you did not cause, and call it again until \`passed: true\`.
+5. **Stop the dev server** with \`npm run dev -- --stop\` (it stops the pid in \`.tanqory/dev-server.json\`). Never \`pkill\`, \`killall\` or a pid found by name (\`pgrep\`, \`ps | grep\`): other servers on this machine are not yours.
+6. Only then say done, and say what the screenshots showed.
+`
+}
+
+/**
+ * @param {{ title: string, template: { id: string, title: string, summary: string, api: string,
+ *   layout: Array<[string, string]>, docs: Array<[string, string]>, extraRules?: string[] },
+ *   versions: Record<string, string>, generator: string }} input
+ */
+export function agentInstructions({ title, template, versions, generator }) {
+  const pins = Object.entries(versions)
+    .map(([name, v]) => `\`${name}@${v}\``)
+    .join(', ')
+  const rows = (pairs) => pairs.map(([a, b]) => `| \`${a}\` | ${b} |`).join('\n')
+  const extra = (template.extraRules ?? []).map((r, i) => `${9 + i}. ${r}`).join('\n')
+
+  return `<!-- Generated by ${generator} (template: ${template.id}) for ${pins}. AGENTS.md and CLAUDE.md are the same file. -->
+# ${title}: instructions for coding agents
+
+This is a **Tanqory storefront theme** (Theme ABI v2), started from the **${template.title}** template. The theme owns its markup and CSS; **every storefront function comes from the kit** (\`${template.api}\`).
+
+${workflow(template)}
+## Commands (shell fallback)
+
+| Command | What it does |
+|---|---|
+| \`npm run dev\` | \`tanqory theme dev\`: the theme on http://localhost:9292 (workerd, the platform's production shim, the signed-in store's real data, cart and checkout), rebuilt on every change. \`-- --mock\`: offline fixture store. \`-- --stop\`: stop the running one |
+| \`http://localhost:9292/__editor\` | the Tanqory Editor on your local theme while the dev server runs; edits are saved to \`.tanqory/dev/content.json\` |
+| \`npm run build\` | builds \`dist/abi\`; fails on any contract problem or hard size limit |
+| \`npm test\` / \`npm run typecheck\` | vitest / \`tsc --noEmit\` (after a build) |
+| \`npm run check\` | \`tanqory theme check\` on \`dist/abi\`: **security** (9 ABI suites), **storefront**, **budgets**. Reports in \`reports/\`. \`-- --tier <name>\` for one tier |
+| \`npx tanqory login\` | sign in once (browser, OAuth); the grant is for one store |
+
+## Rules
+
+${template.summary}
+
+1. **Function from the kit, never re-implemented.** Cart, variant selection and \`?variant=\`, search, collection sort/filter/pagination, markets and languages, forms, consent, SEO and JSON-LD, money, i18n and live edit all come from the kit. Style them; do not rewrite them. If the kit lacks something, say so instead of building a parallel version.
+2. **Never fetch raw APIs.** No \`fetch\`, \`XMLHttpRequest\`, \`WebSocket\`, \`EventSource\` or \`sendBeacon\`, and no third-party script or font origin. Data reaches the theme only through the kit (server: \`ctx.data\`; browser: \`/_tq/data\` and \`/_tq/actions\`, called by the kit).
+3. **\`data-tq-node\` on every section.** \`defineSection\` adds it; never remove it, never render a section outside the kit's section tree, keep it on any wrapper you add.
+4. **i18n every visible string.** No hard-coded text in components: add the key to \`locales/en.json\` **and** \`locales/th.json\` and render it with \`t()\` / \`useTranslate()\`. Text the merchant edits belongs in section settings.
+5. **Accessibility.** Semantic HTML (one \`h1\` per page, landmarks, lists), a label for every control, \`alt\` on informative images, contrast 4.5:1, a visible \`:focus-visible\` outline, every link and button at least **44 × 44 px**, cart and menu reachable by keyboard. Never use \`text-transform\` (use \`font-variant-caps\`).
+6. **Deterministic, self-contained render.** No \`Date.now()\`, \`new Date()\`, \`Math.random()\` or timers while rendering; no Node built-ins; no browser globals at module scope or during the server render.
+7. **Settings and content are validated.** Every setting has a default; \`templates/\`, \`regions/\` and \`config/settings.json\` use only declared section types and setting keys. Keep the kit's \`data:shop\` capability.
+8. **Do not edit generated output**: \`dist/\`, \`reports/\`, \`src/generated/\`, \`lib/abi/generated/\`.
+${extra ? `${extra}\n` : ''}
+## Before you say done
+
+\`check_theme\` (or, without the MCP server, \`npm run build && npm run typecheck && npm test && npm run check\`, i.e. \`tanqory theme check\`) is **green on every tier**, and you have looked at the result with \`screenshot\`. A theme that builds but fails a tier is not done.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+${rows(template.layout)}
+
+## Reference (installed, matches your versions)
+
+| File | What |
+|---|---|
+${rows(template.docs)}
+
+All Tanqory MCP tools: \`search_docs\`, \`get_doc\`, \`get_schema\`, \`list_kit_components\`, \`get_kit_example\`, \`scaffold_section\`, \`validate_manifest\`, \`check_theme\`, \`run_storefront_checks\`, \`dev_server_status\`, \`get_page\`, \`screenshot\`, \`list_dev_stores\`, \`get_store_data_summary\`. The server (\`npx -y @tanqory/cli mcp\`) is pre-configured for Claude Code (\`.mcp.json\`), Codex (\`.codex/config.toml\`), VS Code (\`.vscode/mcp.json\`) and Gemini CLI (\`.gemini/settings.json\`). It never publishes anything.
+`
+}
+
+/**
+ * The Claude Code project skill (`.claude/skills/tanqory-theme/SKILL.md`): Claude Code lists project skills to the
+ * model by name + description, so theme work pulls the workflow in even when CLAUDE.md was skimmed.
+ * @param {{ title: string, template: { id: string }, generator: string }} input
+ */
+export function skillFile({ title, template, generator }) {
+  return `---
+name: tanqory-theme
+description: Use for ANY change to this Tanqory storefront theme (${title}) - new or changed sections, styles, locales, templates, or making \`tanqory theme check\` green. Gives the required workflow with the Tanqory MCP tools (scaffold_section, screenshot, get_page, check_theme) and how to stop the dev server safely.
+---
+<!-- Generated by ${generator} (template: ${template.id}). Same workflow as AGENTS.md / CLAUDE.md. -->
+# Tanqory theme workflow
+
+${workflow(template)}
+The rules (kit for every storefront function, no raw fetch, \`data-tq-node\`, en + th for every string, 44 px targets) are in \`CLAUDE.md\`.
+`
+}

package/lib/create.mjs

@@ -0,0 +1,245 @@
+/**
+ * create-tanqory-theme: copy a starter theme, name it, install it.
+ *
+ * Everything the project needs ships inside this package (templates/), so creating a theme needs the npm
+ * registry and nothing else: no git clone, no GitHub, no token.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { cp, mkdir, readFile, readdir, rename, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import { agentInstructions, skillFile } from './agents.mjs'
+
+export const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+export const TEMPLATES_DIR = join(ROOT, 'templates')
+export const TEMPLATE_IDS = ['blank', 'nova']
+const SELF = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+
+/** npm's own package-name rule (validate-npm-package-name, new packages): lowercase, URL-safe, ≤ 214. */
+const NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/
+const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun']
+/** Files whose bytes are copied untouched (no placeholder substitution). */
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|woff2?|ttf|otf|wav|mp3|mp4|webm|wasm|gz|tgz)$/i
+
+export class CreateError extends Error {}
+
+export function usage() {
+  return `
+  npm create tanqory-theme@latest [directory] [-- options]
+
+  Creates a Tanqory storefront theme (Theme ABI v2) ready for Claude Code, Codex and other coding agents.
+
+  Templates
+    blank   Unstyled. Every storefront function wired through @tanqory/theme-kit/headless,
+            minimal neutral CSS. Start here for a theme of your own design.
+    nova    A standalone fork of Nova, the Tanqory reference theme, with its full build
+            tooling, tests and contracts.
+
+  Options
+    --template, -t <blank|nova>   skip the template question
+    --yes, -y                     accept the defaults (directory my-theme, template blank)
+    --no-install                  do not install dependencies
+    --package-manager <npm|pnpm|yarn|bun>
+                                  install with this one (default: the one running this command)
+    --help, -h
+
+  Examples
+    npm create tanqory-theme@latest my-theme
+    npm create tanqory-theme@latest my-theme -- --template nova
+    pnpm create tanqory-theme my-theme --template blank --yes
+`
+}
+
+/** @returns {{ dir?: string, template?: string, yes: boolean, install: boolean, pm?: string, help: boolean }} */
+export function parseArgs(argv) {
+  const out = { yes: false, install: true, help: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const value = () => {
+      const v = a.includes('=') ? a.slice(a.indexOf('=') + 1) : argv[++i]
+      if (!v || v.startsWith('-')) throw new CreateError(`${a.split('=')[0]} needs a value`)
+      return v
+    }
+    if (a === '--help' || a === '-h') out.help = true
+    else if (a === '--yes' || a === '-y') out.yes = true
+    else if (a === '--no-install') out.install = false
+    else if (a === '--template' || a === '-t' || a.startsWith('--template=')) out.template = value()
+    else if (a === '--package-manager' || a.startsWith('--package-manager=')) out.pm = value()
+    else if (a.startsWith('-')) throw new CreateError(`unknown option ${a} (see --help)`)
+    else if (out.dir === undefined) out.dir = a
+    else throw new CreateError(`unexpected argument ${a}: give one directory`)
+  }
+  if (out.template !== undefined && !TEMPLATE_IDS.includes(out.template))
+    throw new CreateError(`--template must be one of ${TEMPLATE_IDS.join(', ')} (got "${out.template}")`)
+  if (out.pm !== undefined && !PACKAGE_MANAGERS.includes(out.pm))
+    throw new CreateError(`--package-manager must be one of ${PACKAGE_MANAGERS.join(', ')} (got "${out.pm}")`)
+  return out
+}
+
+/** The package manager that is running `create` (npm/pnpm/yarn/bun set npm_config_user_agent). */
+export function detectPackageManager(userAgent = process.env.npm_config_user_agent ?? '') {
+  const name = userAgent.split('/')[0]
+  return PACKAGE_MANAGERS.includes(name) ? name : 'npm'
+}
+
+export function titleCase(name) {
+  return basename(name)
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ')
+}
+
+export function validatePackageName(name) {
+  if (!name) return 'the directory name is empty'
+  if (name.length > 214) return 'it is longer than 214 characters'
+  if (!NAME.test(name)) return 'npm package names use lowercase letters, digits, "-", "." and "_" (e.g. my-theme)'
+  if (/^[._]/.test(name)) return 'it must not start with "." or "_"'
+  return null
+}
+
+export function readTemplate(id) {
+  const dir = join(TEMPLATES_DIR, id)
+  const meta = JSON.parse(readFileSync(join(dir, 'template.json'), 'utf8'))
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  const versions = Object.fromEntries(
+    Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([n]) => n.startsWith('@tanqory/')).sort(),
+  )
+  return { dir, meta, versions }
+}
+
+async function ask({ dir, template }) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    if (dir === undefined) dir = (await rl.question('  Project directory (my-theme): ')).trim() || 'my-theme'
+    if (template === undefined) {
+      process.stdout.write(`
+  Which template?
+    1) Blank   unstyled, every storefront function wired through the kit
+    2) Nova    a standalone fork of the Nova reference theme
+`)
+      for (;;) {
+        const a = (await rl.question('  Template (1): ')).trim().toLowerCase() || '1'
+        if (a === '1' || a === 'blank') { template = 'blank'; break }
+        if (a === '2' || a === 'nova') { template = 'nova'; break }
+        process.stdout.write('  Type 1 or 2.\n')
+      }
+    }
+  } finally {
+    rl.close()
+  }
+  return { dir, template }
+}
+
+async function substitute(dir, replacements) {
+  for (const entry of await readdir(dir)) {
+    const path = join(dir, entry)
+    if ((await stat(path)).isDirectory()) {
+      await substitute(path, replacements)
+      continue
+    }
+    if (BINARY.test(entry)) continue
+    const text = await readFile(path, 'utf8')
+    let next = text
+    for (const [token, value] of Object.entries(replacements)) next = next.split(token).join(value)
+    if (next !== text) await writeFile(path, next)
+  }
+}
+
+/** npm drops `.gitignore` from a published tarball, so templates ship it as `_gitignore`. */
+async function restoreDotfiles(dir) {
+  for (const entry of await readdir(dir)) {
+    const path = join(dir, entry)
+    if ((await stat(path)).isDirectory()) {
+      if (entry !== 'node_modules') await restoreDotfiles(path)
+    } else if (entry === '_gitignore') await rename(path, join(dir, '.gitignore'))
+  }
+}
+
+/**
+ * Write the project. Pure file work (no prompt, no install), so tests drive it directly.
+ * @returns {Promise<{ target: string, name: string, template: string }>}
+ */
+export async function scaffold({ dir, template, cwd = process.cwd() }) {
+  const target = resolve(cwd, dir)
+  const name = basename(target)
+  const problem = validatePackageName(name)
+  if (problem) throw new CreateError(`"${name}" cannot be the theme's package name: ${problem}.`)
+  if (existsSync(target) && readdirSync(target).length > 0)
+    throw new CreateError(`${relative(cwd, target) || '.'}/ already exists and is not empty. Choose another directory.`)
+
+  const { dir: from, meta, versions } = readTemplate(template)
+  const title = titleCase(name)
+  await mkdir(target, { recursive: true })
+  await cp(join(TEMPLATES_DIR, 'common'), target, { recursive: true })
+  await cp(from, target, { recursive: true, filter: (src) => src !== join(from, 'template.json') })
+  await restoreDotfiles(target)
+  await substitute(target, { __PACKAGE_NAME__: name, __THEME_TITLE__: title })
+
+  const instructions = agentInstructions({ title, template: meta, versions, generator: `${SELF.name}@${SELF.version}` })
+  await writeFile(join(target, 'AGENTS.md'), instructions)
+  await writeFile(join(target, 'CLAUDE.md'), instructions)
+  await mkdir(join(target, '.claude', 'skills', 'tanqory-theme'), { recursive: true })
+  await writeFile(join(target, '.claude', 'skills', 'tanqory-theme', 'SKILL.md'), skillFile({ title, template: meta, generator: `${SELF.name}@${SELF.version}` }))
+  return { target, name, template }
+}
+
+export function install(target, pm) {
+  const r = spawnSync(pm, ['install'], { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' })
+  return r.status === 0
+}
+
+export async function main(argv = process.argv.slice(2), { interactive = process.stdin.isTTY && process.stdout.isTTY } = {}) {
+  let opts
+  try {
+    opts = parseArgs(argv)
+  } catch (e) {
+    if (e instanceof CreateError) {
+      console.error(`\n  ${e.message}\n`)
+      return 1
+    }
+    throw e
+  }
+  if (opts.help) {
+    console.log(usage())
+    return 0
+  }
+  let { dir, template } = opts
+  if ((dir === undefined || template === undefined) && interactive && !opts.yes) ({ dir, template } = await ask({ dir, template }))
+  dir ??= 'my-theme'
+  template ??= 'blank'
+
+  let result
+  try {
+    result = await scaffold({ dir, template })
+  } catch (e) {
+    if (e instanceof CreateError) {
+      console.error(`\n  ${e.message}\n`)
+      return 1
+    }
+    throw e
+  }
+  const pm = opts.pm ?? detectPackageManager()
+  const rel = relative(process.cwd(), result.target) || '.'
+  console.log(`\n  Created ${rel}/ from the ${template === 'nova' ? 'Nova fork' : 'Blank'} template.\n`)
+
+  let installed = false
+  if (opts.install) {
+    console.log(`  Installing dependencies with ${pm} …\n`)
+    installed = install(result.target, pm)
+    if (!installed) console.error(`\n  ${pm} install failed (see above). Run it again inside ${rel}/.\n`)
+  }
+  const runCmd = pm === 'npm' ? 'npm run' : pm
+  console.log(`  Next:
+
+    cd ${rel}${installed ? '' : `\n    ${pm} install`}
+    ${runCmd} build      build the theme into dist/abi
+    ${runCmd} check      the platform's checks: security, storefront, budgets
+
+  Open the folder in VS Code with Claude Code or Codex: AGENTS.md / CLAUDE.md tell the agent the rules,
+  and the Tanqory MCP server is pre-configured (.mcp.json, .codex/config.toml, .vscode/mcp.json).
+`)
+  return opts.install && !installed ? 1 : 0
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "create-tanqory-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "description": "Create a Tanqory storefront theme (Theme ABI v2): Blank or a Nova fork, ready for Claude Code, Codex and other coding agents.",
+  "keywords": [
+    "tanqory",
+    "theme",
+    "storefront",
+    "ecommerce",
+    "scaffold",
+    "create"
+  ],
+  "license": "MIT",
+  "author": "Tanqory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tanqory/tanqory-platform-packages.git",
+    "directory": "packages/tools/create-tanqory-theme"
+  },
+  "type": "module",
+  "bin": {
+    "create-tanqory-theme": "./bin/create-tanqory-theme.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/templates/blank/README.md

@@ -0,0 +1,13 @@
+# __THEME_TITLE__
+
+A Tanqory storefront theme (Theme ABI v2) on `@tanqory/theme-kit/headless`, started from the **Blank** template:
+every storefront function is wired, the markup is minimal and the CSS is neutral. Make it yours.
+
+```bash
+npm install
+npm run build        # dist/abi: manifest, browser bundle, single-file server entry, defaults, locales
+npm test             # vitest
+npm run check        # the platform's checks: security, storefront, budgets (reports/)
+```
+
+Node ≥ 20. Coding agents: read `AGENTS.md` (the same text as `CLAUDE.md`).

package/templates/blank/config/settings.json

@@ -0,0 +1,3 @@
+{
+  "width": "normal"
+}

package/templates/blank/locales/en.json

@@ -0,0 +1,22 @@
+{
+  "theme.nav.main": "Main menu",
+  "theme.footer.menu": "More",
+  "theme.footer.rights": "© {name}. All rights reserved.",
+  "theme.price.from": "From {price}",
+  "theme.shelf.viewAll": "View all",
+  "theme.shelf.empty": "No products in this collection yet.",
+  "theme.product.missing": "This product is not available.",
+  "theme.collection.kicker": "Collection",
+  "theme.collection.none": "This collection is empty for now.",
+  "theme.cart.continue": "Continue shopping",
+  "theme.cart.view": "View cart",
+  "theme.cart.taxes": "Taxes and shipping are calculated at checkout.",
+  "theme.drawer.qty": "Qty {count}",
+  "theme.journal.read": "Read more",
+  "theme.journal.back": "Back to {blog}",
+  "theme.journal.by": "By {author}",
+  "theme.notFound.title": "Page not found",
+  "theme.notFound.body": "The link may be old, or the page has moved.",
+  "theme.notFound.home": "Back to the home page",
+  "seo.homeDescription": "{name}: shop online."
+}

package/templates/blank/locales/th.json

@@ -0,0 +1,22 @@
+{
+  "theme.nav.main": "เมนูหลัก",
+  "theme.footer.menu": "เพิ่มเติม",
+  "theme.footer.rights": "© {name} สงวนลิขสิทธิ์",
+  "theme.price.from": "เริ่มต้น {price}",
+  "theme.shelf.viewAll": "ดูทั้งหมด",
+  "theme.shelf.empty": "ยังไม่มีสินค้าในคอลเลกชันนี้",
+  "theme.product.missing": "สินค้านี้ไม่มีจำหน่าย",
+  "theme.collection.kicker": "คอลเลกชัน",
+  "theme.collection.none": "คอลเลกชันนี้ยังไม่มีสินค้า",
+  "theme.cart.continue": "เลือกซื้อสินค้าต่อ",
+  "theme.cart.view": "ดูตะกร้า",
+  "theme.cart.taxes": "ภาษีและค่าจัดส่งคำนวณตอนชำระเงิน",
+  "theme.drawer.qty": "จำนวน {count}",
+  "theme.journal.read": "อ่านต่อ",
+  "theme.journal.back": "กลับไปที่ {blog}",
+  "theme.journal.by": "โดย {author}",
+  "theme.notFound.title": "ไม่พบหน้าที่คุณกำลังหา",
+  "theme.notFound.body": "ลิงก์อาจเก่าแล้ว หรือหน้านี้ถูกย้ายไป",
+  "theme.notFound.home": "กลับหน้าแรก",
+  "seo.homeDescription": "{name}: ช้อปออนไลน์"
+}

package/templates/blank/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Tanqory storefront theme (Theme ABI v2) on @tanqory/theme-kit.",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "build": "node scripts/build.mjs",
+    "check": "node scripts/check.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanqory/theme-kit": "2.0.0-alpha.3",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@tanqory/cli": "2.0.0-alpha.3",
+    "@tanqory/theme-abi": "2.0.0-alpha.14",
+    "@tanqory/theme-conformance": "0.1.0-alpha.15",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "~5.9.3",
+    "vite": "^5.4.10",
+    "vitest": "^3.2.4"
+  }
+}

package/templates/blank/regions/footer.json

@@ -0,0 +1,35 @@
+{
+  "contentVersion": 1,
+  "region": "footer",
+  "sections": [
+    {
+      "id": "footer",
+      "type": "footer",
+      "blocks": [
+        {
+          "id": "footer-brand",
+          "type": "footer-brand",
+          "settings": {
+            "tagline": "Made in small batches."
+          }
+        },
+        {
+          "id": "footer-menu",
+          "type": "footer-menu",
+          "settings": {
+            "heading": "Explore",
+            "menu": "main-menu"
+          }
+        },
+        {
+          "id": "footer-menu-2",
+          "type": "footer-menu",
+          "settings": {
+            "heading": "Help",
+            "menu": "footer"
+          }
+        }
+      ]
+    }
+  ]
+}

package/templates/blank/regions/header.json

@@ -0,0 +1,13 @@
+{
+  "contentVersion": 1,
+  "region": "header",
+  "sections": [
+    {
+      "id": "header",
+      "type": "header",
+      "settings": {
+        "menu": "main-menu"
+      }
+    }
+  ]
+}