@barkajs/barka 0.1.0

package/CLAUDE.md

@@ -0,0 +1,64 @@
+# Barka — AI-Native Progressive CMS — Agent Rules
+
+## Mission — context for all decisions
+
+Barka is the #1 CMS for marketing-driven companies that need rich, multi-language websites across multiple domains and publish a lot of content fast. It was born from frustration with Payload, Astro, Drupal, WordPress, and Strapi — where AI agents struggled with multi-language, multi-site, custom landing pages, and high-volume publishing. Every decision should optimize for: AI agents creating content and features easily, multi-language/multi-domain as first-class, rapid landing page and blog post creation, and zero friction from idea to published page.
+
+## INVARIANTS — NEVER violate
+
+- NEVER delete or overwrite content/, config/, themes/ — USER-OWNED directories
+- NEVER modify starters/ without syncing changes to ALL starters (lokatech + kadoservices + blank)
+- NEVER hardcode language prefixes (/pl/, /de/) in theme components — use _url() and _t()
+- NEVER commit apps/smoke-crm/ — temporary test fixture
+- ALWAYS run `npm test && npm run typecheck` before push
+- ALWAYS verify with Playwright before reporting a fix as done
+- ALWAYS check INVARIANTS.json before modifying protected paths
+
+## Architecture decisions (settled — do not re-litigate)
+
+- Theme resolution order: active theme → base theme → starter → built-in fallback
+- ALL section components use _url() for href links, _t() for UI text (hero, cta, features, blog-listing, text-with-image, etc.)
+- init --force cleans content/, config/, themes/ before copying
+- barka build must mirror app.ts rendering pipeline exactly
+- Zero JS on frontend — public pages ship 0 bytes of JavaScript
+- UI translations via config/translations/`<lang>`.yaml — never hardcode per-language text in JSX
+- Multi-site: config/sites.yaml defines domains, content filtered by siteId + langcode
+- Starters are self-contained distributions — after init, user owns everything
+
+## Content structure
+
+- Markdown files with YAML frontmatter in content/
+- Landing pages use YAML sections (content/landing-pages/*.yaml)
+- PL content: file suffix (.pl.md, .pl.yaml) — URLs get /pl/ prefix from framework, NOT from content
+
+## Theme components (SDC)
+
+- Each component: directory with template.tsx + schema.yaml
+- Components receive: { data, settings, themeSettings }
+- Use `themeSettings._url?.(path)` for localized links
+- Use `themeSettings._t?.(key)` for translated UI strings
+- Component CSS in colocated .css files, served via /static/components.css
+
+## npm package model
+
+- Package name: `@barkajs/barka`
+- content/, config/, themes/ are gitignored — generated by `barka init`, user-owned
+- starters/ and src/built-in-theme/ ship with the npm package
+- CLI resolves starters from cwd first, then from package root (getPackageRoot())
+
+## Commands
+
+```
+barka dev                 # Dev server with hot reload
+barka build               # Static HTML to dist/
+barka init -s X           # Init from starter
+barka db:init             # SQLite + admin user
+barka create <name>       # Scaffold new project
+barka starters            # List available starters
+npm test                  # Vitest (must pass before push)
+npm run typecheck         # TypeScript (must pass before push)
+```
+
+## Commit format
+
+`type(scope): description` — e.g. `feat(sections): add gallery section type`

package/INVARIANTS.json

@@ -0,0 +1,43 @@
+{
+  "version": 1,
+  "description": "Machine-readable project invariants. AI agents: read this before modifying code. Hooks and tests validate against these rules.",
+  "protected_paths": {
+    "user_owned": ["content/", "config/", "themes/"],
+    "never_commit": ["apps/smoke-crm/", ".env", "data/barka.db"],
+    "never_delete": ["starters/", "src/built-in-theme/"]
+  },
+  "required_before_push": ["npm test", "npm run typecheck"],
+  "i18n": {
+    "components_must_use": ["_url()", "_t()"],
+    "never_hardcode_lang_prefix": true,
+    "lang_prefix_added_by": "framework routing, not content files",
+    "translation_files": "config/translations/<lang>.yaml"
+  },
+  "theme": {
+    "resolution_chain": ["active", "base", "starter", "built-in"],
+    "starter_sync_rule": "changes to any starter must be checked against all starters",
+    "component_props": ["data", "settings", "themeSettings"],
+    "url_helper": "themeSettings._url(path)",
+    "translation_helper": "themeSettings._t(key)"
+  },
+  "build": {
+    "must_mirror": "app.ts rendering pipeline",
+    "static_assets_path": "/static/",
+    "zero_frontend_js": true,
+    "translations_required": true,
+    "languages_required": true,
+    "langcode_filter_on_listings": true
+  },
+  "starters": {
+    "available": ["lokatech", "kadoservices", "blank"],
+    "init_force_cleans_dirs": true,
+    "after_init_user_owns": ["content/", "config/", "themes/"]
+  },
+  "npm_package": {
+    "name": "@barkajs/barka",
+    "content_config_themes_gitignored": true,
+    "starters_shipped_with_package": true,
+    "builtin_theme_shipped_as_source": true,
+    "path_resolution": "getPackageRoot() from src/lib/paths.ts"
+  }
+}

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present Grzegorz Bartman
+
+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.