Docs on Lesstructhttps://lesstruct.dev/docs/Recent content in Docs on LesstructHugoenReleased under the [MIT License](https://github.com/aristorinjuang/lesstruct/blob/main/LICENSE).Tue, 16 Jun 2026 19:07:39 +0700<link>https://lesstruct.dev/docs/project-context/</link><pubDate>Tue, 16 Jun 2026 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/project-context/</guid><description><h1 id="project-context-for-ai-agents">Project Context for AI Agents<a class="anchor" href="#project-context-for-ai-agents">#</a></h1> <p><em>This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss.</em></p> <hr> <h2 id="technology-stack--versions">Technology Stack &amp; Versions<a class="anchor" href="#technology-stack--versions">#</a></h2> <h3 id="backend-go">Backend (Go)<a class="anchor" href="#backend-go">#</a></h3> <ul> <li><strong>Go</strong> 1.26 — module: <code>github.com/aristorinjuang/lesstruct</code></li> <li><strong>Chi</strong> 5.2.5 — HTTP router; <strong>httprate</strong> 0.15.0 — per-route rate limiting</li> <li><strong>Databases</strong> (driver selected via <code>DB_DRIVER</code> env: <code>sqlite</code> | <code>postgres</code> | <code>mysql</code>): <ul> <li><strong>SQLite</strong> (modernc.org/sqlite v1.50.0) — default, embedded</li> <li><strong>PostgreSQL</strong> (jackc/pgx/v5 v5.10.0)</li> <li><strong>MySQL</strong> (go-sql-driver/mysql v1.9.2) — DSN MUST contain <code>parseTime=true</code> AND <code>multiStatements=true</code></li> </ul> </li> <li><strong>golang-migrate</strong> 4.19.1 — DB migrations via <code>iofs</code> embedded filesystem, per-driver subdirs under <code>internal/database/migrations/{sqlite,postgresql,mysql}/</code></li> <li><strong>BurntSushi/toml</strong> 1.6.0 — <code>config.toml</code> parsing</li> <li><strong>joho/godotenv</strong> 1.5.1 — <code>.env</code> loader (called from <code>config.Load()</code>)</li> <li><strong>fsnotify</strong> 1.10.0 — config file hot-reload</li> <li><strong>golang-jwt</strong> 5.3.1 — JWT auth (browser admin realm)</li> <li><strong>bluemonday</strong> 1.0.27 — HTML sanitization</li> <li><strong>goldmark</strong> 1.8.2 — Markdown parser (Markdown → TipTap JSON converter in <code>internal/content/markdown/</code>)</li> <li><strong>wazero</strong> 1.11.0 — WebAssembly runtime (plugin system)</li> <li><strong>google.golang.org/genai</strong> 1.59.0 — Google Imagen image generation</li> <li><strong>openai/openai-go</strong> 1.12.0 — text generation (OpenAI-compatible APIs via <code>AI_TEXT_GENERATION_BASE_URL</code>)</li> <li><strong>deepteams/webp</strong> 1.2.1 + <strong>golang.org/x/image</strong> 0.39.0 — image transcoding for media uploads</li> <li><strong>spf13/cobra</strong> 1.10.2 — CLI framework (<code>cmd/lesstruct-cli</code>)</li> <li><strong>golang.org/x/crypto</strong> 0.51.0, <strong>golang.org/x/net</strong> 0.55.0</li> <li><strong>stretchr/testify</strong> 1.11.1 — test assertions</li> <li><strong>mockery</strong> — mock generation (<code>make mock</code>)</li> <li><strong>govulncheck</strong> — vulnerability scanning (<code>make vulncheck</code>)</li> <li><strong>golangci-lint</strong> v2.11.4 — linter (<code>make lint</code>); config in <code>.golangci.yml</code></li> </ul> <h3 id="cli-cmdlesstruct-cli">CLI (<code>cmd/lesstruct-cli</code>)<a class="anchor" href="#cli-cmdlesstruct-cli">#</a></h3> <ul> <li>Thin Cobra-based client over <code>/api/v1</code>; imports <strong>no server internals</strong></li> <li>Subcommands: <code>content</code> (create/get/list/update/delete/publish/unpublish), <code>media</code> (upload/get/list), <code>config</code></li> <li>Auth via <code>--api-key</code> flag, <code>LESSTRUCT_API_KEY</code> env, or config file (precedence in that order)</li> <li>Output mode: <code>--output text|json</code> (default <code>text</code>)</li> <li>Built via <code>make build-cli</code> → <code>bin/lesstruct-cli</code>; integration tests via <code>make test-cli</code> (tag <code>integration</code>)</li> </ul> <h3 id="admin-panel-frontend--webadmin">Admin Panel (Frontend) — <code>web/admin/</code><a class="anchor" href="#admin-panel-frontend--webadmin">#</a></h3> <ul> <li><strong>Vue 3</strong> 3.5.31 — Composition API + <code>&lt;script setup&gt;</code> only</li> <li><strong>TypeScript</strong> 6.0 — strict mode</li> <li><strong>Vite</strong> 8 — build tool; base: <code>/admin/</code>, output to <code>internal/api/static/admin/</code></li> <li><strong>Pinia</strong> 3.0.4 — state management</li> <li><strong>Vue Router</strong> 5.0.4</li> <li><strong>TipTap</strong> 3.22+ (Vue 3) — rich text editor (starter-kit + code-block-lowlight, emoji, image, link, mathematics, placeholder, table, table-cell, table-header, table-row, text-align, underline)</li> <li><strong>Headless UI</strong> 1.7.23 — accessible primitives</li> <li><strong>KaTeX</strong> 0.16.47 — math rendering</li> <li><strong>lowlight</strong> 3.3.0 — syntax highlighting</li> <li><strong>Vitest</strong> 4.1.2 + jsdom 29 — unit tests</li> <li><strong>Prettier</strong> 3.8.1 + ESLint 10 + Oxlint ~1.57 — linting/formatting</li> <li>Node engine: <code>^20.19.0 || &gt;=22.12.0</code></li> </ul> <h3 id="content-theme">Content Theme<a class="anchor" href="#content-theme">#</a></h3> <ul> <li>Go <code>html/template</code> — server-rendered content site via <code>internal/api/template/</code> (layouts/pages) and <code>internal/api/contentpage/</code> (data assembly)</li> <li>Theme overrides via <code>THEME_DIR</code> env var or theme plugin architecture</li> <li>Default theme CSS minified via <code>make css</code> (tdewolff/minify)</li> </ul> <h3 id="architecture">Architecture<a class="anchor" href="#architecture">#</a></h3> <ul> <li><strong>Domain-Driven Design</strong>: <code>internal/domain/&lt;name&gt;/</code> holds business logic, types, sentinel errors, interfaces. Current domains: <code>apikey</code>, <code>auth</code>, <code>content</code>, <code>customfield</code>, <code>dashboard</code>, <code>media</code>, <code>plugin</code>, <code>posttype</code>, <code>profilepicture</code>, <code>sanitize</code>, <code>seo</code>, <code>textgen</code>, <code>thumbnail</code>, <code>user</code></li> <li><strong>Repository pattern</strong>: interfaces in domain, per-driver implementations in <code>internal/repository/{sqlite,mysql,postgresql}/</code>. Shared cross-driver helpers (e.g., <code>soft_delete.go</code>, <code>user.go</code>) live directly in <code>internal/repository/</code></li> <li><strong>HTTP handlers</strong>: <code>internal/api/handlers/</code> (browser admin realm) and <code>internal/api/handlers/agent/</code> (Bearer API-key realm, <code>/api/v1</code>); routes registered in <code>internal/api/routes/routes.go</code></li> <li><strong>Auth realms</strong>: two co-exist on shared paths and are dispatched by <code>dispatchByAuth()</code> based on the <code>Authorization</code> header prefix (<code>Bearer lesstruct_…</code> = agent realm, JWT cookie or other Bearer = browser realm). Each chain carries its own auth middleware</li> <li><strong>Middleware</strong> (<code>internal/api/middleware/</code>): <code>auth</code> (JWT), <code>apikey</code> (Bearer API key), <code>admin</code>, <code>commentator</code>, <code>cors</code>, <code>csrf</code>, <code>nocookie</code>, <code>ratelimit</code> (via httprate)</li> <li><strong>Response envelope</strong> (<code>internal/api/response/</code>): <code>{&quot;data&quot;: ..., &quot;error&quot;: {...}, &quot;meta&quot;: {...}}</code>. Lists use <code>SuccessList()</code> which uses a dedicated <code>listResponse</code> type WITHOUT <code>omitempty</code> on <code>data</code> so empty lists serialize as <code>&quot;data&quot;:[]</code></li> <li><strong>Plugin system</strong>: wazero WASM runtime in <code>internal/plugin/</code> with hook execution (<code>before_save</code>, <code>after_save</code>, etc.). Subpackages: <code>bootstrap</code>, <code>capability</code>, <code>devmode</code>, <code>hostfunctions</code>, <code>loader</code>, <code>registry</code>, <code>runtime</code></li> <li><strong>Content pipeline</strong>: <code>internal/content/</code> holds format converters — <code>tiptap/</code> (canonical), <code>markdown/</code> (Markdown→TipTap via goldmark), <code>wordpress/</code> (WordPress importer)</li> <li><strong>Config</strong>: <code>.env</code> + env vars loaded via <code>internal/config/config.go</code> (<code>Config</code> struct, <code>Load()</code>); user-facing <code>config.toml</code> in project root loaded at startup with hot-reload via fsnotify; post types/languages/thumbnails schemas in <code>internal/config/</code></li> <li><strong>Migrations</strong>: numbered <code>.up.sql</code>/<code>.down.sql</code> pairs in <code>internal/database/migrations/{driver}/</code>, embedded via <code>embed.go</code></li> </ul> <hr> <h2 id="critical-implementation-rules">Critical Implementation Rules<a class="anchor" href="#critical-implementation-rules">#</a></h2> <h3 id="language-specific-rules">Language-Specific Rules<a class="anchor" href="#language-specific-rules">#</a></h3> <h4 id="go">Go<a class="anchor" href="#go">#</a></h4> <ul> <li>Use <code>any</code>, never <code>interface{}</code></li> <li>Never use <code>panic()</code> — use <code>log.Fatalf()</code>/<code>log.Panicf()</code> only in <code>main.go</code> (and only in <code>cmd/lesstruct-cli/main.go</code> for the CLI)</li> <li>Private structs/functions before public ones in every file</li> <li>Constructors (<code>New*</code>) go AFTER all methods on the struct</li> <li>Multi-line function arguments when ≥3 params (one arg per line)</li> <li>Always use constants for HTTP methods: <code>http.MethodDelete</code>, not <code>&quot;DELETE&quot;</code></li> <li><code>internal/config/</code> holds env-based config; <code>config.toml</code> holds user-facing config</li> <li>Domain errors are sentinel errors (<code>var ErrSomething = errors.New(...)</code>) in the domain package</li> <li>Handlers map domain errors to HTTP responses via <code>handleContentError()</code> pattern (browser realm) or the agent error mapper in <code>internal/api/handlers/agent/errors.go</code> (agent realm)</li> <li>JSON responses use the envelope from <code>internal/api/response/</code> — call <code>Success</code>, <code>Error</code>, or <code>SuccessList</code>; never hand-roll the envelope</li> <li>Cross-driver repository code must work for SQLite, PostgreSQL, AND MySQL — beware driver-specific SQL (placeholders, <code>RETURNING</code>, time handling). Use the per-driver subpackage when behavior must diverge</li> </ul> <h4 id="typescriptvue">TypeScript/Vue<a class="anchor" href="#typescriptvue">#</a></h4> <ul> <li>Use <code>&lt;script setup lang=&quot;ts&quot;&gt;</code> exclusively</li> <li>Use <code>defineProps&lt;T&gt;()</code>, <code>defineEmits&lt;T&gt;()</code> typed interfaces</li> <li><code>composables/</code> for reusable stateful logic (e.g., <code>useAuth</code>)</li> <li><code>stores/</code> for Pinia stores, organized by domain under <code>stores/domain/</code> and UI under <code>stores/ui/</code></li> <li><code>types/</code> for shared TypeScript interfaces</li> <li>TipTap content is always a JSON string (<code>&quot;{\&quot;type\&quot;:\&quot;doc\&quot;,\&quot;content\&quot;:[...]}&quot;</code>)</li> </ul> <h3 id="framework-specific-rules">Framework-Specific Rules<a class="anchor" href="#framework-specific-rules">#</a></h3> <h4 id="backend-chi--domain-driven-design">Backend (Chi + Domain-Driven Design)<a class="anchor" href="#backend-chi--domain-driven-design">#</a></h4> <ul> <li><strong>No framework</strong>: Chi is a lightweight router, not a framework — handlers receive <code>http.ResponseWriter, *http.Request</code></li> <li>Routes registered in <code>internal/api/routes/routes.go</code>, grouped by resource and by auth realm</li> <li>Two auth realms co-own some <code>/api/v1/media</code> paths — when adding routes that may collide, register via <code>dispatchByAuth(agentChain, browserChain)</code> rather than duplicating the path</li> <li>Agent realm (<code>/api/v1/*</code>) requires Bearer <code>lesstruct_&lt;keyID&gt;_&lt;secret&gt;</code> tokens verified by <code>APIKeyAuthMiddleware</code>; identity is injected into context using the SAME context keys (<code>UserIDKey</code>, <code>UsernameKey</code>, <code>RoleKey</code>) as the JWT middleware so downstream code is auth-agnostic</li> <li>Content services require a <code>HookExecutor</code> — always pass plugin hooks through, don&rsquo;t bypass</li> <li>Custom field validation flows through <code>content.Service.validateCustomFields()</code> — never call <code>validateFieldValue()</code> directly from handlers</li> <li>Post types loaded from <code>config.toml</code> at startup via <code>internal/config/posttypes.go</code>; reloaded on file change via fsnotify</li> <li>SEO auto-extraction: <code>ExtractPlainText()</code> and <code>ExtractImageURL()</code> consume TipTap JSON from content</li> <li>Markdown bodies on the agent create surface are converted to canonical TipTap JSON via <code>internal/content/markdown</code> — raw Markdown is NEVER persisted</li> <li>Rate limits configurable per realm via <code>RATE_LIMIT_{AUTH,API,PUBLIC}_PER_MINUTE</code>; toggle via <code>RATE_LIMIT_ENABLED</code></li> </ul> <h4 id="frontend-vue-3--pinia">Frontend (Vue 3 + Pinia)<a class="anchor" href="#frontend-vue-3--pinia">#</a></h4> <ul> <li><strong>Atomic design</strong>: <code>atoms/</code> → <code>molecules/</code> → <code>organisms/</code> → <code>views/</code> under <code>web/admin/src/components/</code> and <code>web/admin/src/views/</code></li> <li>Content editor: <code>ContentEditor.vue</code> is the single organism for create + edit (shared component, not separate views)</li> <li>Custom field rendering: <code>CustomFieldRenderer.vue</code> in molecules handles all field types</li> <li>Media upload: <code>MediaPanel.vue</code> organism, opened as a slideover from <code>ContentEditor</code></li> <li>SEO settings are collapsible within <code>ContentEditor</code> (<code>isSEOSettingsOpen</code>)</li> <li>Store actions (e.g., <code>contentStore.create()</code>) make API calls; components only call store actions</li> <li>Toast notifications via <code>Toast.vue</code> molecule with <code>displayToast(message, type)</code> pattern</li> </ul></description></item><item><title/><link>https://lesstruct.dev/docs/api-reference/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/api-reference/</guid><description><h1 id="lesstruct-api-reference-apiv1">Lesstruct API Reference (<code>/api/v1</code>)<a class="anchor" href="#lesstruct-api-reference-apiv1">#</a></h1> <p>Lesstruct exposes a versioned, API-key-authenticated REST API at <code>/api/v1</code> for creating, reading, updating, and deleting <strong>Content</strong> and <strong>Media</strong>. It is designed for programmatic consumers — the <code>lesstruct-cli</code>, MCP servers, AI agents (Claude Code, OpenCode, Hermes, …), and human integrators — and accepts Markdown as a first-class authoring format.</p> <p>This reference documents the <strong>implemented</strong> surface. For the design intent, see <code>_bmad-output/planning-artifacts/architecture-ai-cli.md</code>.</p> <h2 id="overview">Overview<a class="anchor" href="#overview">#</a></h2> <ul> <li><strong>Base URL.</strong> The API is served from the same origin as your Lesstruct server, under the <code>/api/v1</code> prefix. Example: <code>https://your-lesstruct.example/api/v1/content</code>.</li> <li><strong>Transport.</strong> HTTPS in production. All request and response bodies are <code>application/json</code>, except media upload which is <code>multipart/form-data</code>.</li> <li><strong>Authentication.</strong> Every <code>/api/v1</code> request carries an API key as a Bearer token (see <a href="#authentication">Authentication</a>). <code>/api/v1</code> is <strong>Bearer-only</strong> — there is no cookie/JWT fallback.</li> <li><strong>Versioning.</strong> The <code>v1</code> URL segment pins the contract. Breaking changes ship under a new version segment.</li> <li><strong>JSON conventions.</strong> Keys are <code>camelCase</code>. Strings are UTF-8. Timestamps are ISO 8601 strings.</li> </ul> <h2 id="authentication">Authentication<a class="anchor" href="#authentication">#</a></h2> <p>Requests authenticate with a personal API key in the <code>Authorization</code> header:</p></description></item><item><title/><link>https://lesstruct.dev/docs/configuration/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/configuration/</guid><description><h1 id="configuration">Configuration<a class="anchor" href="#configuration">#</a></h1> <p>Lesstruct has two layers of configuration, each for a different concern:</p> <ul> <li><strong><code>config.toml</code></strong> — your site&rsquo;s <em>content schema</em>: languages, custom post types, user profile fields, thumbnail variants. Edited by hand, version-controlled.</li> <li><strong>Environment variables</strong> (in <code>.env</code> or the process env) — your <em>deployment configuration</em>: host, port, database, secrets, SMTP, AI integrations. Treated as deployment state, not committed.</li> </ul> <p>This document covers both.</p> <h2 id="table-of-contents">Table of Contents<a class="anchor" href="#table-of-contents">#</a></h2> <ul> <li><a href="#where-the-files-live">Where the Files Live</a></li> <li><a href="#environment-variables">Environment Variables</a></li> <li><a href="#configtoml-reference">config.toml Reference</a></li> <li><a href="#validation-rules">Validation Rules</a></li> <li><a href="#worked-examples">Worked Examples</a></li> <li><a href="#what-is-not-configurable-from-configtoml">What is NOT Configurable from config.toml</a></li> <li><a href="#upgrading-lesstruct">Upgrading Lesstruct</a></li> <li><a href="#troubleshooting">Troubleshooting</a></li> <li><a href="#quick-reference">Quick Reference</a></li> </ul> <h2 id="where-the-files-live">Where the Files Live<a class="anchor" href="#where-the-files-live">#</a></h2> <table> <thead> <tr> <th>Concern</th> <th>Default location</th> <th>Override via env</th> </tr> </thead> <tbody> <tr> <td>Content schema</td> <td><code>./config.toml</code> in the working directory</td> <td><code>CONFIG_DIR</code> (directory), <code>CONFIG_FILE</code> (filename)</td> </tr> <tr> <td>Deployment config</td> <td><code>.env</code> in the working directory</td> <td>process env wins over <code>.env</code></td> </tr> <tr> <td>Custom theme</td> <td>empty (uses embedded theme)</td> <td><code>THEME_DIR=themes/&lt;name&gt;</code></td> </tr> <tr> <td>Plugins</td> <td><code>plugins/</code> in the working directory</td> <td>not configurable (hard-coded)</td> </tr> <tr> <td>Database</td> <td><code>data/lesstruct.db</code> (SQLite)</td> <td><code>DB_DRIVER</code>, <code>DB_PATH</code>, <code>DB_DSN</code></td> </tr> </tbody> </table> <p><code>config.toml</code> is loaded once at startup from <code>CONFIG_DIR/CONFIG_FILE</code>. The runtime does <strong>not</strong> auto-merge or auto-generate anything; the file is read as-is. If the file is missing, the runtime falls back to defaults (one language: English, default <code>post</code> and <code>page</code> post types, default thumbnail at 370 px). Validation errors at startup are reported with a clear message; the server does not start with an invalid <code>config.toml</code>.</p></description></item><item><title/><link>https://lesstruct.dev/docs/plugin-capabilities/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/plugin-capabilities/</guid><description><h1 id="plugin-capabilities">Plugin Capabilities<a class="anchor" href="#plugin-capabilities">#</a></h1> <blockquote class='book-hint '> <p><strong>Audience.</strong> This is the <strong>developer-facing</strong> reference for the Lesstruct plugin capability manifest and host functions. It references source-tree paths (e.g. <code>internal/plugin/</code>).</p> <p>If you are a Lesstruct user who has installed the binary and wants to add host function calls to a plugin, use the <strong>user-facing</strong> snapshot bundled with the <code>lesstruct-plugin-development</code> skill at <code>skills/lesstruct-plugin-development/references/plugin-capabilities.md</code>. It covers the same contract (manifest schema, host functions, security model) but with no source-tree references.</p></description></item><item><title/><link>https://lesstruct.dev/docs/plugin-development/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/plugin-development/</guid><description><h1 id="plugin-development-guide">Plugin Development Guide<a class="anchor" href="#plugin-development-guide">#</a></h1> <blockquote class='book-hint '> <p><strong>Audience.</strong> This is the <strong>developer-facing</strong> reference for Lesstruct plugin development. It references source-tree paths (e.g. <code>internal/plugin/</code>, <code>pkg/sdk/</code>).</p> <p>If you are a Lesstruct user who has installed the binary and wants to write a plugin against your installation, use the <strong>user-facing</strong> snapshot bundled with the <code>lesstruct-plugin-development</code> skill at <code>skills/lesstruct-plugin-development/references/plugin-development.md</code>. It covers the same contract (hooks, memory protocol, host functions, build instructions) but with no source-tree references.</p> </blockquote><p>Lesstruct supports WebAssembly (WASM) plugins that extend functionality through hooks. Plugins are compiled from Go, Rust, C/C++, or any language that targets WASI.</p></description></item><item><title/><link>https://lesstruct.dev/docs/theme-development/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://lesstruct.dev/docs/theme-development/</guid><description><h1 id="theme-development-guide">Theme Development Guide<a class="anchor" href="#theme-development-guide">#</a></h1> <blockquote class='book-hint '> <p><strong>Audience.</strong> This is the <strong>developer-facing</strong> reference for Lesstruct theme development. It references source-tree paths (e.g. <code>internal/api/template/</code>).</p> <p>If you are an end user of Lesstruct — i.e. you have installed the binary and want to customise the public site via <code>themes/&lt;name&gt;/</code> — use the <strong>user-facing</strong> snapshot bundled with the <code>lesstruct-theme-development</code> skill at <code>skills/lesstruct-theme-development/references/theme-development.md</code>. It covers the same contract (CSS variables, template blocks, JS DOM contract, CDN assets) but with no source-tree references.</p></description></item></channel></rss>