@flocon-ai/init 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @flocon-ai/init
 
-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.
+One command to add Flocon AI pages to your website. Change `/blog` (where the pages go, `/` for the whole website) and the domain, then run it:
+
+```
+npx @flocon-ai/init --path /blog --domain https://acme.com
+```
+
+With options, it asks nothing (same for AI agents). Without options (`npx @flocon-ai/init`), it asks step by step.
+
+Supports Next.js (App Router), React Router v7 (framework mode) and Astro.
+
+In a terminal, it asks one question at a time (like `create-next-app`), then shows the plan before changing anything:
+
+1. Where should Flocon pages go? Type a path or pick one (autocomplete): `/`, `/blog`, `/guides` first, then the website's folders. Folders that look private (`admin`, `dashboard`, `(app)`…) come last. Next.js: add a route group to use its layout, e.g. `/(site)/blog`.
+2. Your website's domain? Pre-filled when the project has it (`metadataBase`, `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_APP_URL`, Astro `site`…). `http://` becomes `https://`. Preview URLs (Vercel `-git-` branches, Netlify deploy previews, Cloudflare Pages previews) and dev tunnels are skipped. Empty = `https://example.com`, replace it later.
+3. Add `sitemap.xml` and `llms.txt`?
+4. Plan + "Continue?". Ctrl+C, Esc or "No" at any step: nothing is installed or changed.
+
+Project shapes:
+
+- `src/app` (Next.js) and `src/pages` (Astro): detected.
+- `[locale]` under the Next.js app folder: the route goes under it and the locale is passed to `<FloconPage />`.
+- `src/pages/[locale]` in Astro: the route goes under it and the locale is passed to `getFloconPage`.
+- Browser-only React (Vite, Lovable, Bolt, CRA): not supported (AI bots do not run JavaScript). The CLI stops and installs nothing.
+- Next.js Pages Router: not supported yet. The CLI stops and installs nothing.
+- Next.js 14 or older, or `output: "export"`: the CLI stops and installs nothing.
+- Astro without SSR (`output: "server"` + an adapter): the CLI stops and installs nothing.
+- React Router with `ssr: false` (SPA mode): the CLI stops and installs nothing.
+- React Router with `flatRoutes()`: the route is a splat file named by the path (`$.tsx`, `blog.$.tsx`). Nothing to add in `app/routes.ts`. With `rootDirectory`, the files go in that folder.
+- A `[slug]`, `[lang]`… route already in the target folder (it would catch the URLs before Flocon): the CLI stops and installs nothing. Pick another path.
+- The route file already exists: the CLI stops and installs nothing. If it is Flocon's own file (second run): "already set up here".
+- React Router with a splat for the same URLs (`route("*")`, `$.tsx`, `($locale).$.tsx`): the CLI stops and installs nothing.
+- Next.js with the root layout in `app/[lang]` (no `app/layout`): the route goes under `[lang]`. No root layout above the route at all: the CLI stops.
+- Next.js route groups: never picked on their own. Type the group in the path to use its layout (`/(site)/blog` → URLs `/blog/...`). In a shell, quote it: `--path "/(site)/blog"`.
+- Next.js App Router + Pages Router in one project: a catch-all in `pages/` for the same URLs stops the command (`next build` passes, but `next start` crashes). `pages/index.tsx` counts as a page for `/` (→ `[...slug]`).
+- Git Bash on Windows turns `/blog` into `C:/Program Files/Git/blog`: the CLI says so. Use `--path blog` (no first slash).
+- Paths with capitals: a note (URLs are case-sensitive). Accents (`/actualités`): the error suggests the plain letters.
+- Next.js route = `[[...slug]]` (it also serves the folder's own URL), or `[...slug]` when the website already has a page there (`app/page.tsx`, `app/blog/page.tsx`…): Next.js refuses both for the same URL.
+- Next.js `cacheComponents: true`: the route uses `export const instant = false` instead of `dynamic`.
+- Config files are read without comments.
+
+Options (no prompts, for AI agents and CI). Any of `--path`, `--domain` or `--yes` = no prompts at all (AI agents in Cursor or Windsurf run commands in a real terminal: they hung on the questions). No prompts either when there is no terminal.
+
+Questions need Node.js 20.12+. On older Node, the options still work; without options, the CLI stops and shows the one-line command.
+
+```
+npx @flocon-ai/init --path /blog --domain https://acme.com --yes
+```
+
+- `--path <path>`: where pages live (`/` for the whole website, `/blog`…).
+- `--domain <url>`: your website's domain (`https://acme.com` or `acme.com`). Wins over the one found in the project, and skips the domain question.
+- `--yes`: no prompts (path defaults to `/`).
+- `--skip-install`: do not install the package.
+- `--no-sitemap`: do not add the sitemap and `llms.txt` files.
+
+The sitemap and `llms.txt` files are never overwritten. If the website already has one, the CLI prints what to add and you merge it yourself.
+
+The CLI lists every file that still has `https://example.com`: replace it with your domain. Or run the command again with `--domain`: it replaces `https://example.com` in Flocon's own files.
+
+Project with Prettier or Biome: the CLI prints the command to format the new files (it doesn't run it).
+
+The CLI never asks for or writes `FLOCON_TOKEN`. Copy it from https://flocon-ai.com/app/tokens, add it to your env file and to your host **before you push or deploy**: without it, Flocon's URLs return an error (500). With `--path /`, that is every unknown URL of the website. On Cloudflare: `.dev.vars` locally, and a Secret on the host (`wrangler secret put FLOCON_TOKEN`).
+
+Tests: `npm test` (reads the files the CLI writes). `npm run test:build`: real builds + type checks on what the CLI writes (Next.js latest and 15 with `next start`, Astro, React Router latest and 7.7), with the frameworks and the Flocon libs from npm (~2 min, needs the network). CI runs both, only when this folder changes.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@flocon-ai/init",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "One command to add Flocon AI pages to your website: npx @flocon-ai/init",
+  "homepage": "https://flocon-ai.com/docs",
+  "keywords": [
+    "flocon-ai",
+    "seo",
+    "geo",
+    "mcp",
+    "cli",
+    "nextjs",
+    "astro",
+    "react-router"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "init": "./src/cli.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/init.test.mjs",
+    "test:build": "node --test --test-concurrency=1 test/build.test.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.9.0"
+  }
+}