fix: scaffold .chronicle/ directory for Turbopack compatibility (#21)

* fix: resolve next binary via createRequire instead of hardcoded .bin path

When installed via npx/bunx or as a dependency, next gets hoisted and
node_modules/.bin/next doesn't exist inside the chronicle package dir.
Use createRequire + require.resolve to find next/dist/bin/next via
Node's module resolution which handles hoisting automatically.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve chronicle.yaml from cwd first, then content dir

Allows placing chronicle.yaml in project root when using chronicle
as a library dependency, while still supporting it inside content dir.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* ci: add canary release workflow for PR builds

Publishes canary npm release on every PR commit with version
format 0.1.0-canary.<short-sha> using --tag canary.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: scaffold .chronicle/ directory instead of running Next.js from node_modules

Turbopack refuses to compile .ts/.tsx from node_modules. Instead of
running Next.js with cwd: PACKAGE_ROOT (inside node_modules), the CLI
now scaffolds a .chronicle/ directory in the user's project with copied
source files and a content symlink. Next.js runs from .chronicle/ where
Turbopack compiles normally.

- Add scaffold utility that copies src/, source.config.ts, tsconfig.json
  and generates next.config.mjs
- Update dev/build/start/serve commands to use scaffold cwd
- Update init command to create package.json with deps, content/
  subdirectory, and auto-install via detected package manager
- Default content dir changed from cwd to ./content
- Add .chronicle to .gitignore in init

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: move scaffolding to init, resolve next from cwd, detect package manager via lockfiles

- Move scaffoldDir call from dev/build/start/serve into init command
- Commands now require .chronicle/ to exist (fail with helpful message)
- Remove --content and -d flags from commands and init
- Add resolveNextCli() using createRequire to avoid duplicate Next.js instances
- Detect package manager via npm_config_user_agent then lockfile fallback
- Update Dockerfile to use bun add + chronicle init flow
- Add resolve.ts for PACKAGE_ROOT derivation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use .npmrc file for npm auth in canary workflow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: write .npmrc to home dir for bun publish auth

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: revert canary publish to bun with NPM_CONFIG_TOKEN

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* debug: add npm whoami step to verify token

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: standalone tsconfig, openapi-types dep, content flag, update docs

- Remove extends @raystack/tools-config from tsconfig.json (standalone)
- Move openapi-types from devDependencies to dependencies
- Add -c/--content flag to init for custom content dir name
- Skip sample index.mdx if content dir already has files
- Update CLI, Docker, and Getting Started docs for new scaffold flow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve config from project root and fix .source import path

Pass CHRONICLE_PROJECT_ROOT env var to Next.js child process so runtime
config loader finds chronicle.yaml at the actual project root instead of
.chronicle/ scaffold dir. Use tsconfig path alias for .source/server
import to resolve correctly in scaffold context.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: merge missing scripts and deps into existing package.json on init

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: remove debug npm whoami step from canary workflow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: set type module and add node_modules/.next to gitignore in init

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: render search highlights using dangerouslySetInnerHTML for mark tags

Fumadocs returns search results with <mark> HTML tags for highlighting.
Render them properly instead of showing raw HTML text.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: remove canary release workflow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address CodeRabbit PR review comments

- Use template literal for chalk error message in config.ts
- Resolve Next.js CLI from Chronicle's PACKAGE_ROOT instead of cwd
- Derive chronicle version from own package.json instead of hardcoding 'latest'
- Add try-catch with user-friendly error for resolveNextCli in all commands
- Add comment explaining PACKAGE_ROOT resolution path

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: rsbh

Dockerfile

@@ -13,22 +13,23 @@ WORKDIR /app/packages/chronicle
 COPY --from=deps /app /app
 COPY packages/chronicle ./
 RUN bun build-cli.ts
+RUN chmod +x bin/chronicle.js
+RUN ln -s /app/packages/chronicle/bin/chronicle.js /usr/local/bin/chronicle
+
+# --- init project ---
+WORKDIR /docs
+RUN bun add /app/packages/chronicle
+RUN chronicle init
 
 # --- runner ---
 FROM base AS runner
-WORKDIR /app/packages/chronicle
-
-COPY --from=builder /app /app
+WORKDIR /docs
 
-RUN chmod +x bin/chronicle.js
+COPY --from=builder /docs /docs
+COPY --from=builder /app/packages/chronicle /app/packages/chronicle
 RUN ln -s /app/packages/chronicle/bin/chronicle.js /usr/local/bin/chronicle
 
-RUN mkdir -p /app/content && ln -s /app/content /app/packages/chronicle/content
-
-VOLUME /app/content
-
-ENV CHRONICLE_CONTENT_DIR=./content
-WORKDIR /app/packages/chronicle
+VOLUME /docs/content
 
 EXPOSE 3000
 

docs/cli.mdx

@@ -10,21 +10,28 @@ Chronicle provides a CLI to initialize, develop, build, and serve your documenta
 
 ## init
 
-Scaffold a new Chronicle project.
+Initialize a new Chronicle project. Must be run before other commands.
 
 ```bash
 chronicle init [options]
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-d, --dir <path>` | Target directory | `.` (current directory) |
+| `-c, --content <path>` | Content directory name | `content` |
 
-Creates a `chronicle.yaml` config file and a sample `index.mdx` in the specified directory.
+This creates:
+- `chronicle.yaml` — site configuration
+- `content/` (or custom name) — content directory with a sample `index.mdx`
+- `package.json` — with `@raystack/chronicle` dependency (if not exists)
+- `.chronicle/` — scaffolded build directory
+- `.gitignore` — with `.chronicle` entry
+
+If the content directory already exists and has files, the sample `index.mdx` is skipped.
 
 ## dev
 
-Start the development server with hot reload.
+Start the development server with hot reload. Requires `chronicle init` first.
 
 ```bash
 chronicle dev [options]
@@ -33,20 +40,15 @@ chronicle dev [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --port <port>` | Port number | `3000` |
-| `-c, --content <path>` | Content directory | Current directory |
 
 ## build
 
-Build the site for production.
+Build the site for production. Requires `chronicle init` first.
 
 ```bash
-chronicle build [options]
+chronicle build
 ```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-c, --content <path>` | Content directory | Current directory |
-
 ## start
 
 Start the production server. Requires a prior `chronicle build`.
@@ -58,11 +60,10 @@ chronicle start [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --port <port>` | Port number | `3000` |
-| `-c, --content <path>` | Content directory | Current directory |
 
 ## serve
 
-Build and start the production server in one step.
+Build and start the production server in one step. Requires `chronicle init` first.
 
 ```bash
 chronicle serve [options]
@@ -71,14 +72,10 @@ chronicle serve [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --port <port>` | Port number | `3000` |
-| `-c, --content <path>` | Content directory | Current directory |
-
-## Content Directory Resolution
 
-The content directory is resolved in this order:
+## Config Resolution
 
-1. `--content` CLI flag (highest priority)
-2. `CHRONICLE_CONTENT_DIR` environment variable
-3. Current working directory (default)
+`chronicle.yaml` is resolved in this order:
 
-The content directory must contain a `chronicle.yaml` file.
+1. Current working directory
+2. Content directory

docs/docker.mdx

@@ -19,23 +19,23 @@ docker pull raystack/chronicle
 The default command builds and starts a production server on port 3000.
 
 ```bash
-docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle
+docker run -p 3000:3000 -v ./content:/docs/content raystack/chronicle
 ```
 
-Mount your content directory (containing `chronicle.yaml` and MDX files) to `/app/content`.
+Mount your content directory (containing MDX files) to `/docs/content`. Place `chronicle.yaml` in the content directory or it will use defaults.
 
 ## Development Server
 
 Override the default command with `dev` for hot reload:
 
 ```bash
-docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle dev --port 3000
+docker run -p 3000:3000 -v ./content:/docs/content raystack/chronicle dev --port 3000
 ```
 
 ## Custom Port
 
 ```bash
-docker run -p 8080:8080 -v ./content:/app/content raystack/chronicle serve --port 8080
+docker run -p 8080:8080 -v ./content:/docs/content raystack/chronicle serve --port 8080
 ```
 
 ## Docker Compose
@@ -47,7 +47,7 @@ services:
     ports:
       - "3000:3000"
     volumes:
-      - ./content:/app/content
+      - ./content:/docs/content
 ```
 
 ## Available Commands
@@ -56,11 +56,11 @@ The entrypoint is `chronicle`, so any CLI command can be passed:
 
 ```bash
 # Build only
-docker run -v ./content:/app/content raystack/chronicle build
+docker run -v ./content:/docs/content raystack/chronicle build
 
 # Start pre-built server
-docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle start --port 3000
+docker run -p 3000:3000 -v ./content:/docs/content raystack/chronicle start --port 3000
 
 # Build and start (default)
-docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle serve --port 3000
+docker run -p 3000:3000 -v ./content:/docs/content raystack/chronicle serve --port 3000
 ```

docs/index.mdx

@@ -24,7 +24,15 @@ chronicle init
 
 This creates:
 - `chronicle.yaml` — your site configuration
-- `index.mdx` — a sample documentation page
+- `content/` — content directory with a sample `index.mdx`
+- `package.json` — with `@raystack/chronicle` dependency
+- `.chronicle/` — scaffolded build directory (gitignored)
+
+To use an existing directory as content (e.g. `docs/`):
+
+```bash
+chronicle init -c docs
+```
 
 ### 2. Start the development server
 
@@ -39,13 +47,15 @@ Your docs site is now running at [http://localhost:3000](http://localhost:3000).
 Create `.mdx` files in your content directory. Each file becomes a page. Use folders to create nested navigation.
 
 ```
-content/
+my-docs/
 ├── chronicle.yaml
-├── index.mdx
-├── getting-started.mdx
-└── guides/
-    ├── installation.mdx
-    └── configuration.mdx
+├── content/
+│   ├── index.mdx
+│   ├── getting-started.mdx
+│   └── guides/
+│       ├── installation.mdx
+│       └── configuration.mdx
+└── .chronicle/          # generated, gitignored
 ```
 
 ### 4. Build for production
@@ -68,9 +78,11 @@ A minimal Chronicle project looks like:
 ```
 my-docs/
 ├── chronicle.yaml      # Site configuration
-├── index.mdx           # Home page
-└── guides/
-    └── setup.mdx       # Nested page at /guides/setup
+├── content/
+│   ├── index.mdx       # Home page
+│   └── guides/
+│       └── setup.mdx   # Nested page at /guides/setup
+└── .chronicle/          # Generated by init, gitignored
 ```
 
 All configuration is done through `chronicle.yaml`. No additional config files needed.

packages/chronicle/bin/chronicle.js

@@ -10,7 +10,8 @@
     "src",
     "templates",
     "next.config.mjs",
-    "source.config.ts"
+    "source.config.ts",
+    "tsconfig.json"
   ],
   "bin": {
     "chronicle": "./bin/chronicle.js"
@@ -27,7 +28,6 @@
     "@types/react": "^19.2.10",
     "@types/react-dom": "^19.2.3",
     "@types/semver": "^7.7.1",
-    "openapi-types": "^12.1.3",
     "semver": "^7.7.4",
     "typescript": "5.9.3"
   },
@@ -56,6 +56,7 @@
     "slugify": "^1.6.6",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
+    "openapi-types": "^12.1.3",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"
   }

packages/chronicle/package.json

@@ -1,29 +1,36 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
-import { fileURLToPath } from 'url'
+import fs from 'fs'
 import chalk from 'chalk'
-import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
-
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
-const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
+import { attachLifecycleHandlers, resolveNextCli } from '@/cli/utils'
 
 export const buildCommand = new Command('build')
   .description('Build for production')
-  .option('-c, --content <path>', 'Content directory')
-  .action((options) => {
-    const contentDir = resolveContentDir(options.content)
-    loadCLIConfig(contentDir)
+  .action(() => {
+    const scaffoldPath = path.join(process.cwd(), '.chronicle')
+    if (!fs.existsSync(scaffoldPath)) {
+      console.log(chalk.red('Error: .chronicle/ not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
+
+    let nextCli: string
+    try {
+      nextCli = resolveNextCli()
+    } catch {
+      console.log(chalk.red('Error: Next.js CLI not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
 
     console.log(chalk.cyan('Building for production...'))
-    console.log(chalk.gray(`Content: ${contentDir}`))
 
-    const child = spawn(nextBin, ['build'], {
+    const child = spawn(process.execPath, [nextCli, 'build'], {
       stdio: 'inherit',
-      cwd: PACKAGE_ROOT,
+      cwd: scaffoldPath,
       env: {
         ...process.env,
-        CHRONICLE_CONTENT_DIR: contentDir,
+        CHRONICLE_PROJECT_ROOT: process.cwd(),
+        CHRONICLE_CONTENT_DIR: './content',
       },
     })
 

packages/chronicle/src/cli/commands/build.ts

@@ -1,30 +1,37 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
-import { fileURLToPath } from 'url'
+import fs from 'fs'
 import chalk from 'chalk'
-import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
-
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
-const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
+import { attachLifecycleHandlers, resolveNextCli } from '@/cli/utils'
 
 export const devCommand = new Command('dev')
   .description('Start development server')
   .option('-p, --port <port>', 'Port number', '3000')
-  .option('-c, --content <path>', 'Content directory')
   .action((options) => {
-    const contentDir = resolveContentDir(options.content)
-    loadCLIConfig(contentDir)
+    const scaffoldPath = path.join(process.cwd(), '.chronicle')
+    if (!fs.existsSync(scaffoldPath)) {
+      console.log(chalk.red('Error: .chronicle/ not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
+
+    let nextCli: string
+    try {
+      nextCli = resolveNextCli()
+    } catch {
+      console.log(chalk.red('Error: Next.js CLI not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
 
     console.log(chalk.cyan('Starting dev server...'))
-    console.log(chalk.gray(`Content: ${contentDir}`))
 
-    const child = spawn(nextBin, ['dev', '-p', options.port], {
+    const child = spawn(process.execPath, [nextCli, 'dev', '-p', options.port], {
       stdio: 'inherit',
-      cwd: PACKAGE_ROOT,
+      cwd: scaffoldPath,
       env: {
         ...process.env,
-        CHRONICLE_CONTENT_DIR: contentDir,
+        CHRONICLE_PROJECT_ROOT: process.cwd(),
+        CHRONICLE_CONTENT_DIR: './content',
       },
     })