@flocon-ai/init 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,34 @@
-# 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:
+
+```
+npx @flocon-ai/init
+```
+
+Supports Next.js (App Router), React Router v7 (framework mode) and Astro.
+
+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.
+
+Options (no prompts, for AI agents):
+
+```
+npx @flocon-ai/init --path /blog --yes
+```
+
+- `--path <path>`: where pages live (`/` for the whole website, `/blog`…).
+- `--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 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, then deploy.
+
+Tests: `npm test`.

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@flocon-ai/init",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "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"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+import readline from "node:readline/promises"
+import { addSitemapAndLlms } from "./sitemap.mjs"
+import { TEMPLATES } from "./templates.mjs"
+
+const DOCS = "https://flocon-ai.com/docs"
+const TOKENS_URL = "https://flocon-ai.com/app/tokens"
+
+const FRAMEWORKS = {
+  nextjs: { label: "Next.js (App Router)", pkg: "@flocon-ai/next" },
+  react: { label: "React Router v7 (framework mode)", pkg: "@flocon-ai/react" },
+  astro: { label: "Astro", pkg: "@flocon-ai/astro" }
+}
+
+const log = (line = "") => console.log(line)
+
+function fail(lines) {
+  for (const line of lines) console.error(line)
+  process.exit(1)
+}
+
+function parseArgs(argv) {
+  const args = { yes: false, skipInstall: false, sitemap: true, path: undefined }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--yes") args.yes = true
+    else if (a === "--skip-install") args.skipInstall = true
+    else if (a === "--no-sitemap") args.sitemap = false
+    else if (a === "--path") args.path = argv[++i] ?? ""
+    else if (a.startsWith("--path=")) args.path = a.slice("--path=".length)
+    else fail([`Unknown option: ${a}`, "Options: --path <path> --yes --skip-install --no-sitemap"])
+  }
+  return args
+}
+
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"))
+  } catch {
+    return undefined
+  }
+}
+
+// "app" or "src/app" (Next.js uses src/app only when app/ is absent).
+function nextAppDir(cwd) {
+  if (fs.existsSync(path.join(cwd, "app"))) return "app"
+  if (fs.existsSync(path.join(cwd, "src/app"))) return "src/app"
+  return undefined
+}
+
+function detectFramework(cwd) {
+  const pkg = readPackageJson(cwd)
+  if (!pkg) return undefined
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  if (deps.next && nextAppDir(cwd)) return "nextjs"
+  if (deps.astro && fs.existsSync(path.join(cwd, "src/pages"))) return "astro"
+  if (deps["@react-router/dev"] && fs.existsSync(path.join(cwd, "app/routes.ts"))) return "react"
+  return undefined
+}
+
+function detectPackageManager(cwd) {
+  const has = (f) => fs.existsSync(path.join(cwd, f))
+  if (has("pnpm-lock.yaml")) return "pnpm"
+  if (has("yarn.lock")) return "yarn"
+  if (has("bun.lock") || has("bun.lockb")) return "bun"
+  return "npm"
+}
+
+const INSTALL_ARGS = { npm: ["install"], pnpm: ["add"], yarn: ["add"], bun: ["add"] }
+
+// "blog" -> "/blog", "/blog/" -> "/blog". Returns { error } when the path is not valid.
+function normalizePath(input) {
+  let p = String(input ?? "").trim()
+  if (/\s/.test(p)) return { error: "The path must not contain spaces." }
+  if (p === "") p = "/"
+  if (!p.startsWith("/")) p = "/" + p
+  if (p.length > 1) p = p.replace(/\/+$/, "") || "/"
+  if (!/^(\/[A-Za-z0-9_-]+)*\/?$/.test(p)) {
+    return { error: "Use only letters, numbers, - and _ in the path (e.g. /blog or /guides/seo)." }
+  }
+  return { path: p }
+}
+
+// Next.js (app/[locale]) or Astro (src/pages/[locale]) with a `[locale]` segment: the route goes under it.
+function hasLocaleSegment(cwd, framework) {
+  if (framework === "nextjs") return fs.existsSync(path.join(cwd, nextAppDir(cwd), "[locale]"))
+  if (framework === "astro") return fs.existsSync(path.join(cwd, "src/pages/[locale]"))
+  return false
+}
+
+// Projects we know and do not support: stop with the reason, install nothing.
+function unsupportedReason(cwd) {
+  const pkg = readPackageJson(cwd)
+  if (!pkg) return undefined
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+  if (deps.next && !nextAppDir(cwd) && (fs.existsSync(path.join(cwd, "pages")) || fs.existsSync(path.join(cwd, "src/pages")))) {
+    return [
+      "Flocon AI: this is a Next.js Pages Router project. It is not supported yet (@flocon-ai/next needs the App Router).",
+      "Nothing was installed or changed."
+    ]
+  }
+  const ssrOnVite = deps.next || deps.astro || deps["@react-router/dev"] || deps["@tanstack/react-start"] || deps["@remix-run/dev"]
+  if ((deps.vite || deps["react-scripts"]) && deps.react && !ssrOnVite) {
+    return [
+      "Flocon AI: this is a browser-only React app (Vite: Lovable, Bolt, CRA…). It is not supported.",
+      "Why: AI bots and search crawlers do not run JavaScript. They would see an empty page.",
+      "Options: move to a server-rendered framework, like Next.js or React Router v7 (framework mode).",
+      "Nothing was installed or changed. Docs: " + DOCS
+    ]
+  }
+  return undefined
+}
+
+function routeFile(cwd, framework, urlPath, hasLocale) {
+  const prefix = urlPath === "/" ? "" : urlPath
+  if (framework === "nextjs") {
+    const locale = hasLocale ? "/[locale]" : ""
+    return `${nextAppDir(cwd)}${locale}${prefix}/[...slug]/page.tsx`
+  }
+  if (framework === "astro") return `src/pages${hasLocale ? "/[locale]" : ""}${prefix}/[...slug].astro`
+  return "app/routes/flocon.tsx"
+}
+
+function fileIsTaken(cwd, framework, file) {
+  if (fs.existsSync(path.join(cwd, file))) return true
+  if (framework === "nextjs") {
+    const stem = file.replace(/\.tsx$/, "")
+    return ["js", "jsx", "ts", "tsx"].some((ext) => fs.existsSync(path.join(cwd, `${stem}.${ext}`)))
+  }
+  return false
+}
+
+function tokenAlreadySet(cwd) {
+  if (process.env.FLOCON_TOKEN) return true
+  const re = /^\s*(export\s+)?FLOCON_TOKEN\s*=\s*\S/m
+  for (const f of [".env.local", ".env", ".env.development.local", ".env.development"]) {
+    try {
+      if (re.test(fs.readFileSync(path.join(cwd, f), "utf8"))) return true
+    } catch {}
+  }
+  return false
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const cwd = process.cwd()
+
+  // 1. Framework
+  const framework = detectFramework(cwd)
+  if (!framework) {
+    const reason = unsupportedReason(cwd)
+    if (reason) fail(reason)
+    fail([
+      "Flocon AI: no supported framework found in this folder.",
+      "Supported: Next.js (App Router), React Router v7 (framework mode), Astro.",
+      "Run this command at the root of your website. Docs: " + DOCS
+    ])
+  }
+  const { label, pkg } = FRAMEWORKS[framework]
+  log(`Found: ${label}`)
+
+  // 2. Path (asked before anything is changed)
+  let answer = args.path
+  if (answer === undefined) {
+    if (args.yes || !process.stdin.isTTY) {
+      answer = "/"
+    } else {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+      answer = await rl.question("Where should Flocon pages go? (e.g. / for the whole website, /blog, /guides) ")
+      rl.close()
+    }
+  }
+  const normalized = normalizePath(answer)
+  if (normalized.error) fail([`Invalid path "${answer}": ${normalized.error}`])
+  const urlPath = normalized.path
+
+  // 3. Install
+  const pm = detectPackageManager(cwd)
+  const installCmd = [pm, ...INSTALL_ARGS[pm], pkg]
+  if (args.skipInstall) {
+    log(`Skipped install. Package: ${pkg} (package manager: ${pm}).`)
+  } else {
+    log(`Installing ${pkg} with ${pm}...`)
+    const res = spawnSync(installCmd[0], installCmd.slice(1), { cwd, stdio: "inherit", shell: process.platform === "win32" })
+    if (res.status !== 0) fail([`Install failed. Run it yourself: ${installCmd.join(" ")}`])
+  }
+
+  // 4. Route file (never overwrite)
+  const hasLocale = hasLocaleSegment(cwd, framework)
+  const file = routeFile(cwd, framework, urlPath, hasLocale)
+  const template = hasLocale ? TEMPLATES[framework + "Locale"] : TEMPLATES[framework]
+  let exitCode = 0
+  if (fileIsTaken(cwd, framework, file)) {
+    exitCode = 1
+    log(`\n${file} already exists. I did not touch it. Add this file yourself (e.g. as ${file}):\n`)
+    log(template)
+  } else {
+    const full = path.join(cwd, file)
+    fs.mkdirSync(path.dirname(full), { recursive: true })
+    fs.writeFileSync(full, template, { flag: "wx" })
+    log(`Created ${file}`)
+  }
+  if (framework === "react") {
+    const routePath = urlPath === "/" ? "*" : `${urlPath.slice(1)}/*`
+    log(`\nRegister the route last in app/routes.ts:\n  route("${routePath}", "routes/flocon.tsx")`)
+  }
+
+  // 4b. Sitemap + llms.txt (never overwrite)
+  if (args.sitemap) {
+    const appDir = framework === "nextjs" ? nextAppDir(cwd) : undefined
+    if (addSitemapAndLlms({ cwd, framework, appDir, urlPath, log })) exitCode = 1
+  }
+
+  // 5. Token (no prompt, no file write)
+  log()
+  if (tokenAlreadySet(cwd)) {
+    log("FLOCON_TOKEN is already set. Good.")
+  } else {
+    log(
+      `Flocon needs FLOCON_TOKEN to work. Copy your website token from ${TOKENS_URL}, then add FLOCON_TOKEN=... to your env file (.env.local / .env) and to your host. Never commit it.`
+    )
+  }
+
+  // 6. Last step
+  log("\nNext step: add FLOCON_TOKEN to your host, then deploy.")
+  process.exit(exitCode)
+}
+
+await main()

package/src/sitemap.mjs

@@ -0,0 +1,149 @@
+// Sitemap + llms.txt files written by the CLI (`--no-sitemap` skips them).
+// Copy of the `get_setup` snippets in back/functions/mcp/setup.ts (a package never imports from back/).
+// test/init.test.mjs fails if they drift.
+import fs from "node:fs"
+import path from "node:path"
+
+const nextSitemap = `import type { MetadataRoute } from "next"
+import { floconSitemap } from "@flocon-ai/next"
+
+// Built on getAllPages(): published pages only, never drafts.
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  return floconSitemap({ url: ({ locale, path }) => \`https://example.com/\${locale}\${path}\` })
+}
+`
+
+const nextLlms = `import { floconLlmsTxt } from "@flocon-ai/next"
+
+export async function GET() {
+  return new Response(await floconLlmsTxt({ url: ({ locale, path }) => \`https://example.com/\${locale}\${path}\` }), {
+    headers: { "content-type": "text/plain; charset=utf-8" }
+  })
+}
+`
+
+const astroSitemap = `import { getAllPages } from "@flocon-ai/astro"
+
+// Published pages only, never drafts.
+export async function GET() {
+  const pages = await getAllPages()
+  const urls = pages
+    .map((p) => \`<url><loc>https://example.com/\${p.locale}\${p.path}</loc><lastmod>\${p.updatedAt}</lastmod></url>\`)
+    .join("")
+  return new Response(
+    \`<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\${urls}</urlset>\`,
+    { headers: { "content-type": "application/xml" } }
+  )
+}
+`
+
+const astroLlms = `import { floconLlmsTxt } from "@flocon-ai/astro"
+
+export async function GET() {
+  const text = await floconLlmsTxt({ url: ({ locale, path }) => \`https://example.com/\${locale}\${path}\` })
+  return new Response(text, { headers: { "content-type": "text/plain; charset=utf-8" } })
+}
+`
+
+const reactSitemap = `import { floconSitemap } from "@flocon-ai/react"
+
+export async function loader() {
+  const xml = await floconSitemap({ url: ({ locale, path }) => \`https://example.com\${path}\` })
+  return new Response(xml, { headers: { "content-type": "application/xml; charset=utf-8" } })
+}
+`
+
+const reactLlms = `import { floconLlmsTxt } from "@flocon-ai/react"
+
+export async function loader() {
+  const text = await floconLlmsTxt({ url: ({ locale, path }) => \`https://example.com\${path}\` })
+  return new Response(text, { headers: { "content-type": "text/plain; charset=utf-8" } })
+}
+`
+
+const exts = (base, list) => list.map((e) => base + e)
+
+// `existing` = files that mean the website already has one.
+function spec(framework, appDir) {
+  if (framework === "nextjs") {
+    return {
+      sitemap: {
+        file: `${appDir}/sitemap.ts`,
+        code: nextSitemap,
+        existing: [...exts(`${appDir}/sitemap`, [".js", ".ts", ".xml"]), ...exts(`${appDir}/sitemap.xml/route`, [".js", ".ts"]), "public/sitemap.xml"]
+      },
+      llms: {
+        file: `${appDir}/llms.txt/route.ts`,
+        code: nextLlms,
+        existing: [...exts(`${appDir}/llms.txt/route`, [".js", ".ts"]), `${appDir}/llms.txt`, "public/llms.txt"]
+      }
+    }
+  }
+  if (framework === "astro") {
+    return {
+      sitemap: {
+        file: "src/pages/sitemap.xml.ts",
+        code: astroSitemap,
+        existing: [...exts("src/pages/sitemap.xml", [".ts", ".js", ".astro"]), "src/pages/sitemap-index.xml.ts", "public/sitemap.xml", "public/sitemap-index.xml"]
+      },
+      llms: {
+        file: "src/pages/llms.txt.ts",
+        code: astroLlms,
+        existing: [...exts("src/pages/llms.txt", [".ts", ".js", ".astro"]), "public/llms.txt"]
+      }
+    }
+  }
+  return {
+    sitemap: {
+      file: "app/routes/sitemap[.]xml.ts",
+      code: reactSitemap,
+      existing: [...exts("app/routes/sitemap[.]xml", [".ts", ".tsx"]), ...exts("app/routes/sitemap.xml", [".ts", ".tsx"]), "public/sitemap.xml"]
+    },
+    llms: {
+      file: "app/routes/llms[.]txt.ts",
+      code: reactLlms,
+      existing: [...exts("app/routes/llms[.]txt", [".ts", ".tsx"]), ...exts("app/routes/llms.txt", [".ts", ".tsx"]), "public/llms.txt"]
+    }
+  }
+}
+
+// Astro: @astrojs/sitemap builds the sitemap from the config, there is no file to detect.
+function astroConfigHasSitemap(cwd) {
+  for (const f of ["astro.config.mjs", "astro.config.ts", "astro.config.js", "astro.config.mts"]) {
+    try {
+      if (/@astrojs\/sitemap/.test(fs.readFileSync(path.join(cwd, f), "utf8"))) return true
+    } catch {}
+  }
+  return false
+}
+
+// Never overwrites. Returns true when something has to be done by hand.
+export function addSitemapAndLlms({ cwd, framework, appDir, urlPath, log }) {
+  const files = spec(framework, appDir)
+  const exists = (f) => fs.existsSync(path.join(cwd, f))
+  let manual = false
+  log()
+  for (const [kind, name] of [
+    ["sitemap", "sitemap"],
+    ["llms", "llms.txt"]
+  ]) {
+    const { file, code, existing } = files[kind]
+    const taken = existing.some(exists) || (kind === "sitemap" && framework === "astro" && astroConfigHasSitemap(cwd))
+    if (taken) {
+      manual = true
+      log(`The website already has a ${name}. I did not touch it. Add this yourself: merge the Flocon URLs (published pages, under ${urlPath}) into it.`)
+      log(`Example (${file}):\n`)
+      log(code)
+    } else {
+      const full = path.join(cwd, file)
+      fs.mkdirSync(path.dirname(full), { recursive: true })
+      fs.writeFileSync(full, code, { flag: "wx" })
+      log(`Created ${file}`)
+    }
+  }
+  log(`In the sitemap and llms.txt files, replace https://example.com with your website URL (Flocon pages live under ${urlPath}).`)
+  if (framework === "react") {
+    log('Register both routes before the catch-all in app/routes.ts:\n  route("sitemap.xml", "routes/sitemap[.]xml.ts")\n  route("llms.txt", "routes/llms[.]txt.ts")')
+  }
+  return manual
+}

package/src/templates.mjs

@@ -0,0 +1,113 @@
+// Route files written by the CLI.
+// Copy of the `get_setup` snippets in back/functions/mcp/setup.ts (a package never imports from back/).
+// test/init.test.mjs fails if they drift.
+
+const nextjs = `import { FloconPage } from "@flocon-ai/next"
+
+// One catch-all route serves every Flocon page. Rendered on each request.
+export default async function Page({ params }: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await params
+  return <FloconPage path={"/" + slug.join("/")} />
+}
+`
+
+// Same as `nextjs`, for a route under `[locale]`: the locale goes to the lib.
+const nextjsLocale = `import { FloconPage } from "@flocon-ai/next"
+
+// One catch-all route serves every Flocon page, under the [locale] segment. Rendered on each request.
+export default async function Page({ params }: { params: Promise<{ locale: string; slug: string[] }> }) {
+  const { locale, slug } = await params
+  return <FloconPage locale={locale} path={"/" + slug.join("/")} />
+}
+`
+
+const astro = `---
+import FloconPage from "@flocon-ai/astro/FloconPage.astro"
+import { getFloconPage, getFloconMetadata } from "@flocon-ai/astro"
+
+// Your URL rule. Flocon AI adds no prefix of its own.
+const url = ({ locale, path }: { locale: string; path: string }) => \`https://example.com/\${locale}\${path}\`
+
+const data = await getFloconPage({ path: "/" + (Astro.params.slug ?? "") })
+if (!data) return new Response(null, { status: 404 })
+const meta = getFloconMetadata({ data, url })
+---
+
+<html lang={data.page.locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{meta.title}</title>
+    {meta.meta.map((m) => <meta {...m} />)}
+    {meta.links.map((l) => <link {...l} />)}
+  </head>
+  <body>
+    <FloconPage data={data} url={url} />
+  </body>
+</html>
+`
+
+// Same as `astro`, for a route under `src/pages/[locale]`.
+const astroLocale = `---
+import FloconPage from "@flocon-ai/astro/FloconPage.astro"
+import { getFloconPage, getFloconMetadata } from "@flocon-ai/astro"
+
+// Your URL rule. Flocon AI adds no prefix of its own.
+const url = ({ locale, path }: { locale: string; path: string }) => \`https://example.com/\${locale}\${path}\`
+
+const data = await getFloconPage({ path: "/" + (Astro.params.slug ?? ""), locale: Astro.params.locale })
+if (!data) return new Response(null, { status: 404 })
+const meta = getFloconMetadata({ data, url })
+---
+
+<html lang={data.page.locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <title>{meta.title}</title>
+    {meta.meta.map((m) => <meta {...m} />)}
+    {meta.links.map((l) => <link {...l} />)}
+  </head>
+  <body>
+    <FloconPage data={data} url={url} />
+  </body>
+</html>
+`
+
+const react = `// Register it as a splat route in app/routes.ts: route("*", "routes/flocon.tsx") (or route("blog/*", ...) for a prefix)
+import { FloconPage, getFloconMetadata, getPage } from "@flocon-ai/react"
+import type { Route } from "./+types/flocon"
+
+const url = ({ locale, path }: { locale: string; path: string }) => \`https://example.com\${path}\`
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const page = await getPage({ path: "/" + params["*"] })
+  if (!page) throw new Response("Not found", { status: 404 })
+  return page
+}
+
+export function meta({ data }: Route.MetaArgs) {
+  if (!data) return [{ title: "Not found" }]
+  const m = getFloconMetadata({ page: data, url })
+  return [
+    { title: m.title },
+    { name: "description", content: m.description },
+    { property: "og:type", content: m.openGraph.type },
+    { property: "og:title", content: m.openGraph.title },
+    { property: "og:description", content: m.openGraph.description },
+    { property: "og:url", content: m.openGraph.url },
+    { property: "og:locale", content: m.openGraph.locale },
+    { name: "twitter:card", content: m.twitter.card },
+    { name: "twitter:title", content: m.twitter.title },
+    { name: "twitter:description", content: m.twitter.description },
+    { tagName: "link", rel: "canonical", href: m.canonical },
+    ...Object.entries(m.languages).map(([hrefLang, href]) => ({ tagName: "link", rel: "alternate", hrefLang, href }))
+  ]
+}
+
+export default function Page({ loaderData }: Route.ComponentProps) {
+  return <FloconPage page={loaderData} url={url} />
+}
+`
+
+export const TEMPLATES = { nextjs, nextjsLocale, astro, astroLocale, react }