create-jant 0.3.40 → 0.3.43

package/README.md

@@ -1,89 +1,76 @@
-# Create Jant
+# create-jant
 
-Bookstrap a new [Jant](https://github.com/jant-me/jant) project.
+Scaffold a new [Jant](https://github.com/jant-me/jant) site for Cloudflare Workers.
 
 ## Usage
 
 ```bash
-# Using npm
-npm create jant my-blog
+# npm
+npm create jant@latest my-site
 
-# Using pnpm
-pnpm create jant my-blog
+# pnpm
+pnpm create jant@latest my-site
 
-# Using yarn
-yarn create jant my-blog
+# yarn
+yarn create jant my-site
 
-# Interactive mode (prompts for project name)
-npm create jant
+# interactive mode
+npm create jant@latest
 ```
 
-## What's Included
+## What It Does
 
-The scaffolded project includes:
+The scaffold:
 
-- **Hono** - Fast, lightweight web framework
-- **Cloudflare Workers** - Serverless edge runtime
-- **D1** - SQLite database at the edge
-- **R2** - Object storage for media
-- **Drizzle ORM** - Type-safe database access
-- **Tailwind CSS v4** - Utility-first CSS framework
-- **BaseCoat** - UI component library
-- **Lingui** - Internationalization (i18n)
-- **better-auth** - Authentication
-- **Vite** - Fast build tool with HMR
+- creates a Cloudflare Workers project wired for Jant
+- generates a local `.dev.vars` file with a secure `AUTH_SECRET`
+- installs dependencies by default
+- initializes a git repository by default
+- can switch the storage template to S3-compatible storage with `--s3`
 
-## Getting Started
+## Options
 
-After creating your project:
+```bash
+create-jant [project-name] [options]
+
+--s3           Use S3-compatible storage instead of Cloudflare R2
+--no-install   Skip dependency installation
+--no-git       Skip git initialization
+-y, --yes      Skip prompts and use defaults
+```
+
+## After Scaffolding
 
 ```bash
 cd my-site
-pnpm install
-cp .dev.vars.example .dev.vars
-# Edit .dev.vars with your AUTH_SECRET (32+ characters)
-pnpm dev
+npm run dev
 ```
 
-Visit http://localhost:3000 to see your site.
-
-Need another local port? Run `PORT=3030 pnpm dev`.
+Open `http://localhost:3000`.
 
-## Project Structure
+Need another local port?
 
-```
-my-site/
-├── src/
-│   ├── index.ts          # Entry point
-│   ├── app.tsx           # Hono app factory
-│   ├── types.ts          # TypeScript types
-│   ├── db/               # Database schema & migrations
-│   ├── services/         # Business logic
-│   ├── routes/           # Route handlers
-│   ├── theme/            # UI components & layouts
-│   ├── lib/              # Utilities
-│   ├── i18n/             # Internationalization
-│   └── middleware/       # Hono middleware
-├── static/               # Static assets
-├── vite.config.ts        # Vite configuration
-├── wrangler.toml         # Cloudflare Workers config
-└── drizzle.config.ts     # Drizzle ORM config
+```bash
+PORT=3030 npm run dev
 ```
 
-## Scripts
+## What the New Project Includes
 
-```bash
-pnpm dev               # Start dev server (http://localhost:3000)
-pnpm build             # Build for production
-pnpm run deploy        # Apply migrations/backfills and deploy to Cloudflare Workers
-pnpm typecheck         # Run TypeScript checks
-pnpm lint              # Run ESLint
-pnpm format            # Format code with Prettier
-pnpm db:generate       # Generate Drizzle migrations
-pnpm exec jant migrate --local   # Apply schema migrations + data backfills (local)
-pnpm exec jant migrate --remote  # Apply schema migrations + data backfills (production)
-pnpm i18n:build        # Extract + compile translations
-```
+- Cloudflare Workers runtime
+- D1 for the database
+- R2 for media by default
+- Drizzle ORM
+- better-auth
+- Tailwind CSS v4 and BaseCoat
+- Lingui for localization
+- Jant's CLI commands through the local `jant` binary
+
+## Documentation
+
+- [Getting Started](https://github.com/jant-me/jant/blob/main/docs/getting-started.md)
+- [Deploy on Cloudflare](https://github.com/jant-me/jant/blob/main/docs/deployment.md)
+- [Configuration](https://github.com/jant-me/jant/blob/main/docs/configuration.md)
+- [Theming](https://github.com/jant-me/jant/blob/main/docs/theming.md)
 
 ## License
 

package/dist/index.js

@@ -9,7 +9,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = path.dirname(__filename);
-var CORE_VERSION = "0.3.40";
+var CORE_VERSION = "0.3.43";
 var WRANGLER_VERSION = "^4.76.0";
 var TEMPLATE_DIR = fs.existsSync(path.resolve(__dirname, "../template")) ? path.resolve(__dirname, "../template") : path.resolve(__dirname, "../../../sites/demo");
 function isValidProjectName(name) {
@@ -91,9 +91,15 @@ async function copyTemplate(config) {
   await fs.copy(TEMPLATE_DIR, targetDir, {
     filter: (src) => {
       const basename = path.basename(src);
+      const relativePath = path.relative(TEMPLATE_DIR, src);
       if (basename === "node_modules") return false;
       if (basename === ".wrangler") return false;
       if (basename === ".dev.vars") return false;
+      if (basename === ".claude") return false;
+      if (basename === "CLAUDE.md") return false;
+      if (relativePath === path.join("docs", "internal") || relativePath.startsWith(path.join("docs", "internal") + path.sep)) {
+        return false;
+      }
       return true;
     }
   });
@@ -157,6 +163,18 @@ S3_SECRET_ACCESS_KEY=
     devVarsContent,
     "utf-8"
   );
+  const agentsPath = path.join(targetDir, "AGENTS.md");
+  if (await fs.pathExists(agentsPath)) {
+    await fs.writeFile(
+      path.join(targetDir, "CLAUDE.md"),
+      "@AGENTS.md\n",
+      "utf-8"
+    );
+  }
+  const sourceSkillsDir = path.join(targetDir, ".agents", "skills");
+  if (await fs.pathExists(sourceSkillsDir)) {
+    await fs.copy(sourceSkillsDir, path.join(targetDir, ".claude", "skills"));
+  }
 }
 async function main() {
   console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-jant",
-  "version": "0.3.40",
+  "version": "0.3.43",
   "description": "Create a new Jant project",
   "type": "module",
   "bin": {
@@ -19,9 +19,9 @@
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^24.0.0",
+    "@types/node": "^25.5.0",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
+    "typescript": "^6.0.2"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -53,7 +53,7 @@
     "build": "tsup src/index.ts --format esm --clean --outDir dist",
     "dev": "tsup src/index.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
-    "copy-template": "rm -rf template && rsync -a --exclude node_modules --exclude .wrangler --exclude .dev.vars --exclude scripts ../../sites/demo/ template/ && mv template/.gitignore template/_gitignore && mv template/.github template/_github",
+    "copy-template": "rm -rf template && rsync -a --exclude node_modules --exclude .wrangler --exclude .dev.vars --exclude .claude --exclude CLAUDE.md --exclude docs/internal --exclude scripts ../../sites/demo/ template/ && mv template/.gitignore template/_gitignore && mv template/.github template/_github",
     "inject-version": "node -e \"const fs=require('fs');const path=require('path');const coreVersion=require('../core/package.json').version;const workspace=fs.readFileSync(path.resolve(__dirname,'../../pnpm-workspace.yaml'),'utf8');const match=workspace.match(/^[ \\t]*wrangler:[ \\t]*(.+)$/m);if(!match)throw new Error('Unable to resolve wrangler catalog version');const wranglerVersion=match[1].trim();const f='dist/index.js';const source=fs.readFileSync(f,'utf8').replace('__JANT_CORE_VERSION__',coreVersion).replace('__WRANGLER_VERSION__',wranglerVersion);fs.writeFileSync(f,source)\"",
     "test-template": "node scripts/test-template.js"
   }

package/template/.agents/skills/building-jant-site/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: building-jant-site
+description: Customize a standalone Jant site created with create-jant. Use for project structure decisions, local development, theme work, deployment setup, settings-driven customization, and deciding whether a change belongs in the site repo or in Jant core.
+---
+
+# Building a Jant Site
+
+Jant sites created with `create-jant` are intentionally thin. The site repo is mostly configuration and operations glue around `@jant/core`.
+
+## Start Here
+
+Use this skill when you need to:
+
+- change site configuration in `wrangler.toml`
+- customize the look with theme settings or custom CSS
+- decide whether a change belongs in the site repo or the Jant monorepo
+- run local development or deploy to Cloudflare
+- script repeatable site changes without editing core code
+
+## Key Constraint
+
+Do not patch `node_modules/@jant/core`.
+
+If the change is product behavior that should apply to all Jant sites, make it in the Jant monorepo. If the change is site-specific, keep it in:
+
+- dashboard settings
+- custom CSS
+- site docs or helper scripts
+- `wrangler.toml`
+- the thin `index.js` entrypoint
+
+## Files That Matter
+
+```text
+index.js           # Server entrypoint
+wrangler.toml      # Cloudflare config, bindings, vars
+.dev.vars          # Local secrets
+README.md          # Human-facing project instructions
+```
+
+## Common Workflow
+
+### 1. Start local development
+
+```bash
+npm run dev
+```
+
+This already runs local migrations before starting Wrangler dev.
+
+### 2. Pick the right customization layer
+
+- Content or editorial defaults: use the dashboard or the HTTP API
+- Theme and layout changes: use Settings plus custom CSS
+- Deployment and runtime config: edit `wrangler.toml`
+- One-off site behavior at the server edge: wrap `createApp()` in `index.js`
+
+### 3. Deploy the normal way
+
+```bash
+npm run deploy
+```
+
+Prefer this over raw `wrangler deploy`. The Jant deploy command runs remote migrations and prepares assets before handing off to Wrangler.
+
+## Theming Guidance
+
+Start with built-in theme settings. Reach for custom CSS only after the built-in color and font themes are not enough.
+
+Useful variables include:
+
+- `--background`
+- `--foreground`
+- `--primary`
+- `--site-accent`
+- `--site-width`
+- `--card-radius`
+- `--card-padding`
+
+Useful data attributes include:
+
+- `data-page`
+- `data-post`
+- `data-format`
+- `data-post-body`
+- `data-post-media`
+
+Prefer variable overrides over deep selectors. They survive upstream design changes better.
+
+## Gotchas
+
+1. `index.js` should stay small. If you are about to recreate routing, rendering, or DB behavior there, you are probably changing core, not the site.
+2. `SITE_PATH_PREFIX` affects deploy behavior. Use `npm run deploy`, not raw Wrangler, so prefixed asset paths are prepared correctly.
+3. Most editable settings live behind `/api/settings` and are stored as strings.
+4. The fastest way to break a site-specific customization is to fork `@jant/core` locally instead of using settings or CSS.
+
+## Verify Proportionally
+
+- Config-only changes: rerun `npm run dev` or `npm run deploy -- --dry-run` when relevant
+- CSS-only changes: smoke test the affected pages in the browser
+- API-driven changes: exercise the matching endpoint with a real request

package/template/.agents/skills/jant-http-api/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: jant-http-api
+description: Automate a Jant site over HTTP. Use for creating and updating posts, uploading media, managing collections, editing settings, and running public or authenticated queries against the documented Jant API.
+---
+
+# Jant HTTP API
+
+Use this skill when the task is better handled through the site's HTTP API than through the browser UI.
+
+## Auth
+
+Use one of these:
+
+- session cookie from a signed-in browser
+- `Authorization: Bearer jnt_...` API token
+- local `DEV_API_TOKEN` on localhost-style hosts
+
+## Prefer Local CLI First
+
+When you already have shell access to the site directory, prefer the built-in `jant` CLI for common automation:
+
+```bash
+npx jant posts list --limit 20
+npx jant posts create --input ./post.json
+npx jant media upload ./photo.webp --alt "Cover image"
+npx jant media list --mimePrefix image/
+npx jant collections add-post col_... pst_...
+npx jant settings get
+npx jant search "quiet design"
+```
+
+The CLI uses the same site URL and token model as the HTTP API.
+
+## Built-in MCP
+
+Jant also exposes a built-in MCP endpoint at `/api/mcp`.
+
+- auth: session cookie or `Authorization: Bearer jnt_...`
+- tools: posts, media, collections, settings, and search
+- protocol: streamable HTTP request/response shape with `initialize`, `tools/list`, and `tools/call`
+
+Use MCP when the caller already speaks MCP. Use the CLI or plain HTTP when you just need a direct script.
+
+Generated sites also include worked examples in `examples/agent-content-automation/`.
+
+Base URL examples:
+
+- local: `http://localhost:3000`
+- production: `https://your-site.example`
+
+## Post Automation
+
+### Create a note
+
+```bash
+curl -X POST "$JANT_URL/api/posts" \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "format": "note",
+    "title": "Hello World",
+    "bodyMarkdown": "A short note from the API.",
+    "status": "published",
+    "visibility": "public"
+  }'
+```
+
+### Create a quote
+
+```bash
+curl -X POST "$JANT_URL/api/posts" \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "format": "quote",
+    "quoteText": "What stands in the way becomes the way.",
+    "sourceName": "Marcus Aurelius",
+    "bodyMarkdown": "Still worth rereading."
+  }'
+```
+
+### Update a post
+
+```bash
+curl -X PUT "$JANT_URL/api/posts/pst_..." \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "bodyMarkdown": "Updated body copy.",
+    "featured": true
+  }'
+```
+
+## Important Post Rules
+
+- Use `bodyMarkdown` for scripts unless you already have trusted TipTap JSON.
+- Use `body` or `bodyMarkdown`, never both.
+- Use `slug` or `path`, never both. `path` is create-only.
+- Link posts require `title` and `url`.
+- Quote posts require `quoteText` and must use `sourceName` / `sourceUrl`.
+- Replies use `replyToId` and inherit the thread's visibility rules.
+- Sending `attachments` replaces the full attachment list.
+- `GET /api/posts` returns replies as well as roots.
+
+## Uploads
+
+For scripted clients, prefer the local CLI:
+
+```bash
+npx jant media upload ./photo.webp --alt "Cover image"
+```
+
+For raw HTTP clients, use the recommended upload session flow:
+
+1. `POST /api/uploads/init`
+2. upload bytes to the returned transport
+3. `POST /api/uploads/:id/complete`
+
+For simple agent scripts, the legacy one-shot endpoint can be easier:
+
+```bash
+curl -X POST "$JANT_URL/api/upload" \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -F "file=@./photo.jpg"
+```
+
+Use the returned `med_*` ID inside a post attachment:
+
+```json
+{
+  "attachments": [{ "type": "media", "mediaId": "med_..." }]
+}
+```
+
+Read text attachment markdown through:
+
+```bash
+curl "$JANT_URL/api/attachments/med_.../content" \
+  -H "Authorization: Bearer $JANT_API_TOKEN"
+```
+
+## Collections
+
+Create a collection:
+
+```bash
+curl -X POST "$JANT_URL/api/collections" \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slug": "reading",
+    "title": "Reading",
+    "description": "Books and essays",
+    "sortOrder": "newest"
+  }'
+```
+
+Attach posts by sending `collectionIds` on post create or update.
+
+## Settings
+
+Read settings:
+
+```bash
+curl "$JANT_URL/api/settings" \
+  -H "Authorization: Bearer $JANT_API_TOKEN"
+```
+
+Update settings:
+
+```bash
+curl -X PUT "$JANT_URL/api/settings" \
+  -H "Authorization: Bearer $JANT_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "SITE_NAME": "My Site",
+    "TIME_ZONE": "Asia/Shanghai"
+  }'
+```
+
+Settings values must be strings, including booleans and numbers.
+
+## Public Queries
+
+- Public posts: `GET /api/public/posts`
+- Single public post: `GET /api/public/posts/:slug`
+- Search: `GET /api/search?q=...`
+- Collections: `GET /api/collections`
+
+## Gotchas
+
+1. `latest_hidden` posts are still readable by direct URL.
+2. Quote responses use `sourceName` and `sourceUrl` instead of `title` and `url`.
+3. Clearing a post rating on update uses `"rating": 0`.
+4. Search snippets may contain `<mark>` tags. Treat them as trusted rendered snippet HTML, not plain text.

package/template/.agents/skills/jant-site-ops/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: jant-site-ops
+description: Operate a standalone Jant site from the command line. Use for local development, deploys, migrations, password resets, site export/import, snapshot recovery, SQL export, and static asset preparation.
+---
+
+# Jant Site Operations
+
+Use this skill when the task is operational rather than purely editorial.
+
+## Run Commands From the Site Root
+
+All commands below assume the current working directory is the site root created by `create-jant`.
+
+## Day-to-Day Commands
+
+```bash
+npm run dev
+npm run deploy
+npm run export
+npm run reset-password
+```
+
+What they do:
+
+- `npm run dev`: run local migrations, then start Wrangler dev
+- `npm run deploy`: run remote migrations and deploy to Cloudflare
+- `npm run export`: run the Jant export command configured by the site
+- `npm run reset-password`: generate a password reset token for the local site
+
+## CLI Commands
+
+```bash
+npx jant migrate --local
+npx jant migrate --remote --config ./wrangler.toml
+npx jant site export --output ./jant-site-export.zip
+npx jant site import --path ./jant-site-export.zip --dry-run
+npx jant site snapshot export --output ./jant-site-snapshot.zip
+npx jant site snapshot import --path ./jant-site-snapshot.zip --replace
+npx jant db export --output ./jant-export.sql
+```
+
+## Pick the Right Export Format
+
+- `site export`: portable content archive for migration or static inspection
+- `site snapshot export`: recovery archive that preserves Jant IDs and storage keys
+- `db export`: raw SQL dump only
+
+Do not treat those as interchangeable.
+
+## Deployment Guidance
+
+Prefer:
+
+```bash
+npm run deploy
+```
+
+Avoid calling `wrangler deploy` directly for the normal site workflow. Jant's deploy command handles migrations and asset preparation first.
+
+## Media Utilities
+
+Useful commands when working with exported sites or static archives:
+
+```bash
+npx jant site pull-media --help
+npx jant assets prepare
+npx jant uploads cleanup --help
+```
+
+Use `assets prepare` when you need the publishable asset directory assembled locally.
+
+## Remote Operations
+
+Remote site export/import can use an API token:
+
+```bash
+export JANT_API_TOKEN=jnt_your_token
+npx jant site export --url https://your-site.example --output ./jant-site-export.zip
+```
+
+For remote D1-oriented commands, pass `--remote` and your Wrangler config when needed.
+
+## Gotchas
+
+1. `site import` expects an empty target site unless you are explicitly using snapshot restore semantics.
+2. Snapshot import currently requires `--replace`.
+3. A SQL dump is not a complete backup unless you also preserve media objects.
+4. Run operations from the project root. The CLI expects local config and installed `@jant/core`.

package/template/AGENTS.md

@@ -0,0 +1,65 @@
+This is a standalone Jant site created with `create-jant`.
+
+`CLAUDE.md` is a thin compatibility shim that points here. Site skills live in `.agents/skills/`.
+
+## Project Shape
+
+- `index.js` is the server entrypoint. In most projects it should stay a thin `createApp()` wrapper from `@jant/core`.
+- `wrangler.toml` is the main deployment and binding config.
+- `.dev.vars` holds local secrets such as `AUTH_SECRET`.
+- `README.md` documents the normal site workflow for humans.
+
+Most customization happens through:
+
+- site settings in the dashboard
+- custom CSS and theme variables
+- HTTP API calls
+- `jant` CLI commands for posts, collections, settings, search, export, import, migrate, and deploy
+- the built-in MCP endpoint at `/api/mcp` for remote agent tooling
+- examples in `examples/agent-content-automation/`
+
+Do not edit `node_modules/@jant/core`. If you need reusable product changes, make them in the Jant monorepo instead.
+
+## Commands
+
+```bash
+npm run dev
+npm run deploy
+npm run export
+npm run reset-password
+
+npx jant migrate --local
+npx jant posts list --limit 20
+npx jant media list --mimePrefix image/
+npx jant collections list
+npx jant settings get
+npx jant search "quiet design"
+npx jant site export --output ./jant-site-export.zip
+npx jant site import --path ./jant-site-export.zip --dry-run
+npx jant db export --output ./jant-export.sql
+```
+
+Use `npm run deploy` for normal Cloudflare deploys. It applies remote migrations and prepares assets before calling Wrangler.
+
+## Skills
+
+Load the matching skill before making substantive changes:
+
+- `building-jant-site`: project structure, settings, theming, local development, and deployment flow
+- `jant-http-api`: automating posts, uploads, collections, settings, and search over HTTP
+- `jant-site-ops`: export/import, snapshot recovery, deploy, reset-password, and database operations
+
+## Rules
+
+- Keep `index.js` minimal unless the site truly needs custom server behavior.
+- Prefer settings, custom CSS, and documented extension points before changing runtime code.
+- Prefer local `npx jant posts`, `collections`, `settings`, and `search` commands for scripted automation when you are already on the site machine.
+- Use `npx jant media` for file uploads, media listing, text attachment reads, alt updates, and deletes.
+- Use `/api/mcp` when an MCP client is available and you need the site to expose posts, collections, settings, or search as tools.
+- Start from `examples/agent-content-automation/README.md` if the task is content automation rather than app development.
+- Use `bodyMarkdown` in API scripts instead of raw TipTap JSON unless you already have trusted editor output.
+- Quote posts use `quoteText`, `sourceName`, and `sourceUrl`. Do not send `title` or `url` for quote payloads.
+- `PUT /api/settings` accepts strings only, even for booleans and numbers.
+- `GET /api/posts` includes thread replies. Filter them yourself if you only want roots.
+- `latest_hidden` posts stay public by direct URL; they are only excluded from Latest surfaces.
+- Run from the site root where `@jant/core` is installed.