@folio-agent/handler 0.2.1 → 0.3.0

package/README.md

@@ -9,7 +9,10 @@
 ```bash
 npm install @folio-agent/handler
 
-# ビルド時: 知識ファイルの生成
+# 対話ウィザードで初期設定（config・テーマCSS・APIルート雛形などを生成）
+npx folio-agent-init
+
+# ビルド時: 知識ファイルの生成（ウィザードが build スクリプトに追記する）
 npx folio-agent-ingest folio-agent.config.json knowledge.json
 ```
 
@@ -28,4 +31,6 @@ export default {
 };
 ```
 
+`createChatHandler` / `createGeminiGenerator` の両方に `language: "en"` を渡すと、定型文・ルーティングキーワード・システムプロンプトが英語になる（既定は `ja`）。
+
 D1 スキーマは `migrations/0001_init.sql` を `wrangler d1 migrations apply` で適用する。

package/dist/chat/gemini.d.ts

@@ -1,10 +1,11 @@
-import type { ChatRoute } from "./types.js";
-export declare function buildSystemPrompt(knowledge: string, route: Exclude<ChatRoute, "rate_limited">, contactUrl?: string): string;
+import type { ChatRoute, Language } from "./types.js";
+export declare function buildSystemPrompt(knowledge: string, route: Exclude<ChatRoute, "rate_limited">, contactUrl?: string, language?: Language): string;
 export interface GeminiGeneratorConfig {
     apiKey: string;
     knowledge: string;
     model?: string;
     contactUrl?: string;
+    language?: Language;
 }
 export type GenerateAnswerFn = (input: string, route: ChatRoute) => Promise<string>;
 export declare function createGeminiGenerator(config: GeminiGeneratorConfig): GenerateAnswerFn;

package/dist/chat/gemini.js

@@ -1,31 +1,57 @@
 import { GoogleGenAI } from "@google/genai";
-const COMMON_PREAMBLE = "あなたはポートフォリオサイト作者の代理として応対する受付エージェントです。" +
-    "丁寧だが簡潔で自然な口語で話し、「お問い合わせいただきありがとうございます」のような定型の前置き挨拶はしません。" +
-    "回答は原則3〜4文以内にまとめてください。\n\n" +
-    "以下の知識に書かれていることだけから答えてください。書かれていないことは推測・創作せず、" +
-    "「その点はサイトに記載がない」と伝えたうえでContactページを案内してください。" +
-    "用語の正式名称・展開形も、知識に書かれていなければ創作しないでください。\n\n" +
-    "Markdown記法（`**`・`#`・`-`のリストなど）は使わず、プレーンテキストで答えてください。" +
-    "回答が長くなる場合は、2〜4文ごとに空行を挟んで段落を分けてください。";
+import { DEFAULT_LANGUAGE } from "./types.js";
+const COMMON_PREAMBLE = {
+    ja: "あなたはポートフォリオサイト作者の代理として応対する受付エージェントです。" +
+        "丁寧だが簡潔で自然な口語で話し、「お問い合わせいただきありがとうございます」のような定型の前置き挨拶はしません。" +
+        "回答は原則3〜4文以内にまとめてください。\n\n" +
+        "以下の知識に書かれていることだけから答えてください。書かれていないことは推測・創作せず、" +
+        "「その点はサイトに記載がない」と伝えたうえでContactページを案内してください。" +
+        "用語の正式名称・展開形も、知識に書かれていなければ創作しないでください。\n\n" +
+        "Markdown記法（`**`・`#`・`-`のリストなど）は使わず、プレーンテキストで答えてください。" +
+        "回答が長くなる場合は、2〜4文ごとに空行を挟んで段落を分けてください。",
+    en: "You are a receptionist agent responding on behalf of the portfolio site's author. " +
+        'Speak politely but concisely and naturally, without formulaic openers such as "Thank you for reaching out." ' +
+        "Keep your answers to about 3-4 sentences.\n\n" +
+        "Only answer based on the knowledge provided below. Do not guess or invent anything that isn't written there — " +
+        "say that the site doesn't cover that point, then guide the visitor to the Contact page. " +
+        "Do not invent official names or expansions of terms that aren't in the knowledge either.\n\n" +
+        "Do not use Markdown formatting (such as `**`, `#`, or `-` lists) — answer in plain text. " +
+        "If the answer runs long, insert a blank line every 2-4 sentences to break it into paragraphs.",
+};
 const ROUTE_INSTRUCTIONS = {
-    thoughts: "訪問者は作者の考え方について質問しています。知識の内容に沿って考え方を説明してください。",
-    works: "訪問者はWorks（作品）について質問しています。知識に書かれた内容から解説し、" +
-        "対応するZenn記事へのリンクが知識中にあれば案内してください。",
-    inquiry: "訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページへの問い合わせを案内してください。",
+    ja: {
+        thoughts: "訪問者は作者の考え方について質問しています。知識の内容に沿って考え方を説明してください。",
+        works: "訪問者はWorks（作品）について質問しています。知識に書かれた内容から解説し、" +
+            "対応するZenn記事へのリンクが知識中にあれば案内してください。",
+        inquiry: "訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページへの問い合わせを案内してください。",
+    },
+    en: {
+        thoughts: "The visitor is asking about the author's thinking. Explain it based on the knowledge provided.",
+        works: "The visitor is asking about Works (projects). Explain based on the knowledge, and if a link to the " +
+            "corresponding Zenn article is included in the knowledge, share it.",
+        inquiry: "The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page.",
+    },
+};
+const KNOWLEDGE_LABEL = {
+    ja: "---- 知識 ----",
+    en: "---- Knowledge ----",
 };
-function buildInquiryInstruction(contactUrl) {
+function buildInquiryInstruction(language, contactUrl) {
     if (contactUrl) {
-        return `訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページ（${contactUrl}）への問い合わせを案内してください。`;
+        return language === "en"
+            ? `The visitor wants to discuss hiring or a project request. Respond briefly, then guide them to contact via the Contact page (${contactUrl}).`
+            : `訪問者は仕事の依頼・相談をしようとしています。簡潔に応じたうえで、Contactページ（${contactUrl}）への問い合わせを案内してください。`;
     }
-    return ROUTE_INSTRUCTIONS.inquiry;
+    return ROUTE_INSTRUCTIONS[language].inquiry;
 }
-export function buildSystemPrompt(knowledge, route, contactUrl) {
-    const routeInstruction = route === "inquiry" ? buildInquiryInstruction(contactUrl) : ROUTE_INSTRUCTIONS[route];
-    return [COMMON_PREAMBLE, routeInstruction, "---- 知識 ----", knowledge].join("\n\n");
+export function buildSystemPrompt(knowledge, route, contactUrl, language = DEFAULT_LANGUAGE) {
+    const routeInstruction = route === "inquiry" ? buildInquiryInstruction(language, contactUrl) : ROUTE_INSTRUCTIONS[language][route];
+    return [COMMON_PREAMBLE[language], routeInstruction, KNOWLEDGE_LABEL[language], knowledge].join("\n\n");
 }
 export function createGeminiGenerator(config) {
     const client = new GoogleGenAI({ apiKey: config.apiKey });
     const model = config.model ?? "gemini-3.1-flash-lite";
+    const language = config.language ?? DEFAULT_LANGUAGE;
     return async (input, route) => {
         if (route === "rate_limited") {
             throw new Error("generateAnswer should not be called for a rate-limited route");
@@ -33,7 +59,7 @@ export function createGeminiGenerator(config) {
         const response = await client.models.generateContent({
             model,
             contents: input,
-            config: { systemInstruction: buildSystemPrompt(config.knowledge, route, config.contactUrl) },
+            config: { systemInstruction: buildSystemPrompt(config.knowledge, route, config.contactUrl, language) },
         });
         return response.text ?? "";
     };

package/dist/chat/graph.js

@@ -1,6 +1,18 @@
 import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
 import { classifyRoute } from "./route.js";
-const GENERATION_FAILED_MESSAGE = "本日の受付上限に達したか、一時的な不具合が発生しています。恐れ入りますがContactからお問い合わせください。";
+import { DEFAULT_LANGUAGE } from "./types.js";
+const RATE_LIMIT_REASON_TEXT = {
+    ja: { daily: "本日の上限", shortWindow: "直近の質問数の上限" },
+    en: { daily: "today's limit", shortWindow: "the recent question limit" },
+};
+const OVER_LIMIT_MESSAGE = {
+    ja: (reasonText) => `${reasonText}に達しました。お急ぎの場合はContactからお問い合わせください。`,
+    en: (reasonText) => `You've reached ${reasonText}. If it's urgent, please contact us via the Contact page.`,
+};
+const GENERATION_FAILED_MESSAGE = {
+    ja: "本日の受付上限に達したか、一時的な不具合が発生しています。恐れ入りますがContactからお問い合わせください。",
+    en: "You may have reached today's limit, or a temporary issue has occurred. Please contact us via the Contact page.",
+};
 const ChatState = Annotation.Root({
     input: Annotation(),
     ip: Annotation(),
@@ -9,26 +21,27 @@ const ChatState = Annotation.Root({
     answer: Annotation(),
 });
 export function buildChatGraph(deps) {
+    const language = deps.language ?? DEFAULT_LANGUAGE;
     const graph = new StateGraph(ChatState)
         .addNode("input_guard", async (state) => {
         const result = await deps.checkRateLimit(state.ip);
         if (!result.allowed) {
-            const reasonText = result.reason === "daily" ? "本日の上限" : "直近の質問数の上限";
+            const reasonText = result.reason === "daily" ? RATE_LIMIT_REASON_TEXT[language].daily : RATE_LIMIT_REASON_TEXT[language].shortWindow;
             return {
                 overLimit: true,
-                answer: `${reasonText}に達しました。お急ぎの場合はContactからお問い合わせください。`,
+                answer: OVER_LIMIT_MESSAGE[language](reasonText),
             };
         }
         return { overLimit: false };
     })
-        .addNode("route_message", async (state) => ({ route: classifyRoute(state.input) }))
+        .addNode("route_message", async (state) => ({ route: classifyRoute(state.input, language) }))
         .addNode("generate", async (state) => {
         try {
             return { answer: await deps.generateAnswer(state.input, state.route) };
         }
         catch (error) {
             console.error("generateAnswer failed", error);
-            return { answer: GENERATION_FAILED_MESSAGE };
+            return { answer: GENERATION_FAILED_MESSAGE[language] };
         }
     })
         .addNode("log", async (state) => {

package/dist/chat/handler.d.ts

@@ -1,8 +1,9 @@
 import type { GenerateAnswerFn } from "./gemini.js";
-import type { RateLimitConfig } from "./types.js";
+import type { Language, RateLimitConfig } from "./types.js";
 export interface ChatHandlerConfig {
     db: D1Database;
     generateAnswer: GenerateAnswerFn;
     rateLimitConfig?: RateLimitConfig;
+    language?: Language;
 }
 export declare function createChatHandler(config: ChatHandlerConfig): (request: Request) => Promise<Response>;

package/dist/chat/handler.js

@@ -8,6 +8,7 @@ export function createChatHandler(config) {
         checkRateLimit: (ip) => checkRateLimit(config.db, ip, new Date(), config.rateLimitConfig ?? DEFAULT_RATE_LIMIT_CONFIG),
         generateAnswer: config.generateAnswer,
         logChat: (entry) => logChat(config.db, entry),
+        language: config.language,
     });
     return async (request) => {
         let body;

package/dist/chat/route.d.ts

@@ -1,2 +1,2 @@
-import type { ChatRoute } from "./types.js";
-export declare function classifyRoute(input: string): Exclude<ChatRoute, "rate_limited">;
+import type { ChatRoute, Language } from "./types.js";
+export declare function classifyRoute(input: string, language?: Language): Exclude<ChatRoute, "rate_limited">;

package/dist/chat/route.js

@@ -1,11 +1,20 @@
-const INQUIRY_KEYWORDS = ["依頼", "相談", "見積", "発注", "案件", "お願いしたい"];
-const WORKS_KEYWORDS = ["works", "作品", "実績", "zenn", "記事"];
-export function classifyRoute(input) {
+import { DEFAULT_LANGUAGE } from "./types.js";
+const INQUIRY_KEYWORDS = {
+    ja: ["依頼", "相談", "見積", "発注", "案件", "お願いしたい"],
+    en: ["hire", "quote", "estimate", "commission", "inquiry", "work with you", "project request"],
+};
+const WORKS_KEYWORDS = {
+    ja: ["works", "作品", "実績", "zenn", "記事"],
+    en: ["works", "portfolio", "article", "zenn", "project"],
+};
+export function classifyRoute(input, language = DEFAULT_LANGUAGE) {
     const lower = input.toLowerCase();
-    if (INQUIRY_KEYWORDS.some((keyword) => input.includes(keyword))) {
+    const inquiryKeywords = INQUIRY_KEYWORDS[language];
+    const worksKeywords = WORKS_KEYWORDS[language];
+    if (inquiryKeywords.some((keyword) => lower.includes(keyword))) {
         return "inquiry";
     }
-    if (WORKS_KEYWORDS.some((keyword) => lower.includes(keyword))) {
+    if (worksKeywords.some((keyword) => lower.includes(keyword))) {
         return "works";
     }
     return "thoughts";

package/dist/chat/types.d.ts

@@ -1,4 +1,6 @@
 export type ChatRoute = "thoughts" | "works" | "inquiry" | "rate_limited";
+export type Language = "ja" | "en";
+export declare const DEFAULT_LANGUAGE: Language;
 export interface RateLimitConfig {
     shortWindowMinutes: number;
     shortWindowMax: number;
@@ -21,4 +23,5 @@ export interface ChatGraphDeps {
     checkRateLimit: (ip: string) => Promise<RateLimitResult>;
     generateAnswer: (input: string, route: ChatRoute) => Promise<string>;
     logChat: (entry: ChatLogEntry) => Promise<void>;
+    language?: Language;
 }

package/dist/chat/types.js

@@ -1,3 +1,4 @@
+export const DEFAULT_LANGUAGE = "ja";
 export const DEFAULT_RATE_LIMIT_CONFIG = {
     shortWindowMinutes: 10,
     shortWindowMax: 3,

package/dist/ingest/types.d.ts

@@ -1,3 +1,4 @@
+import type { Language } from "../chat/types.js";
 export interface IngestConfig {
     /** Absolute or cwd-relative path to the built site (e.g. "dist"). */
     distDir: string;
@@ -11,6 +12,18 @@ export interface IngestConfig {
     zenn?: ZennIngestConfig;
     /** Token threshold above which the CLI warns that CAG may no longer fit. */
     tokenWarningThreshold?: number;
+    /** UI language captured by `folio-agent-init`. Ignored by ingest itself. */
+    language?: Language;
+    /** Widget theme colors captured by `folio-agent-init`. Ignored by ingest itself. */
+    theme?: ThemeColors;
+}
+export interface ThemeColors {
+    /** Hex color for `--folio-agent-accent`, e.g. "#2563eb". */
+    accent: string;
+    /** Hex color for `--folio-agent-surface`, e.g. "#ffffff". */
+    surface: string;
+    /** Hex color for `--folio-agent-text`, e.g. "#111827". */
+    text: string;
 }
 export interface ZennIngestConfig {
     /** Local path (absolute or cwd-relative) to the Zenn CLI articles/ directory. */

package/dist/init/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/init/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import * as clack from "@clack/prompts";
+import { DEFAULT_WIZARD_ANSWERS, runWizard } from "./questions.js";
+import { appendIngestToBuildScript, buildApiRouteTemplate, buildConfigJson, buildThemeCss, deriveEndpointPath, upsertDevVar, } from "./writers.js";
+const CONFIG_PATH = "folio-agent.config.json";
+const THEME_CSS_PATH = "folio-agent.theme.css";
+const PACKAGE_JSON_PATH = "package.json";
+const DEV_VARS_PATH = ".dev.vars";
+const KNOWLEDGE_OUTPUT_PATH = "dist/knowledge.json";
+const CLI_TEXT = {
+    ja: {
+        summaryTitle: "以下の内容で書き込みます:",
+        summaryConfigLine: `${CONFIG_PATH} を生成・更新`,
+        summaryThemeLine: `${THEME_CSS_PATH} を生成・更新（再実行時はこのファイルの書き換えだけで dev サーバーの HMR に反映されます）`,
+        summaryApiRouteLine: (path) => `${path} を新規生成`,
+        summaryApiRouteSkippedLine: (path) => `${path} は既に存在するためスキップします`,
+        summaryBuildScriptLine: `${PACKAGE_JSON_PATH} の build スクリプトに ingest コマンドを追記`,
+        summaryBuildScriptUnchangedLine: `${PACKAGE_JSON_PATH} の build スクリプトは変更なし（既に含まれています）`,
+        summaryDevVarsLine: `${DEV_VARS_PATH} に GEMINI_API_KEY を書き込み`,
+        confirmMessage: "この内容で書き込みますか？",
+        writeCancelledMessage: "書き込みを中止しました。",
+        outroTitle: "セットアップが完了しました。",
+        snippetIntro: "レイアウトに以下を1回だけ貼り付けてください（再実行時は不要です）:",
+        d1Note: "D1 が未設定でも widget の表示とテーマ確認はローカルで動きます。チャット応答には D1 のセットアップと Gemini API キーが必要です。",
+    },
+    en: {
+        summaryTitle: "The following will be written:",
+        summaryConfigLine: `Generate/update ${CONFIG_PATH}`,
+        summaryThemeLine: `Generate/update ${THEME_CSS_PATH} (re-running the wizard only rewrites this file, and your dev server's HMR picks it up)`,
+        summaryApiRouteLine: (path) => `Generate ${path}`,
+        summaryApiRouteSkippedLine: (path) => `Skip ${path} (already exists)`,
+        summaryBuildScriptLine: `Append the ingest command to ${PACKAGE_JSON_PATH}'s build script`,
+        summaryBuildScriptUnchangedLine: `No change to ${PACKAGE_JSON_PATH}'s build script (already present)`,
+        summaryDevVarsLine: `Write GEMINI_API_KEY to ${DEV_VARS_PATH}`,
+        confirmMessage: "Proceed with writing these files?",
+        writeCancelledMessage: "Write cancelled.",
+        outroTitle: "Setup complete.",
+        snippetIntro: "Paste the following into your layout once (not needed again on re-runs):",
+        d1Note: "Without D1 set up, the widget still renders and the theme can be checked locally. Chat responses require D1 and a Gemini API key.",
+    },
+};
+async function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(await readFile(path, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readTextOrEmpty(path) {
+    return existsSync(path) ? readFile(path, "utf-8") : "";
+}
+function seedDefaults(previous) {
+    if (!previous)
+        return DEFAULT_WIZARD_ANSWERS;
+    return {
+        ...DEFAULT_WIZARD_ANSWERS,
+        language: previous.language ?? DEFAULT_WIZARD_ANSWERS.language,
+        distDir: previous.distDir ?? DEFAULT_WIZARD_ANSWERS.distDir,
+        include: previous.include ?? DEFAULT_WIZARD_ANSWERS.include,
+        zenn: previous.zenn,
+        theme: previous.theme ?? DEFAULT_WIZARD_ANSWERS.theme,
+    };
+}
+async function main() {
+    const previousConfig = await readJson(CONFIG_PATH);
+    const answers = await runWizard(seedDefaults(previousConfig));
+    const text = CLI_TEXT[answers.language];
+    const configJson = buildConfigJson(answers, previousConfig);
+    const themeCss = buildThemeCss(answers.theme);
+    const apiRouteExists = existsSync(answers.apiRoutePath);
+    const apiRouteContent = apiRouteExists
+        ? undefined
+        : buildApiRouteTemplate({
+            apiRoutePath: answers.apiRoutePath,
+            distDir: answers.distDir,
+            contactUrl: answers.contactUrl,
+            language: answers.language,
+        });
+    const pkg = (await readJson(PACKAGE_JSON_PATH)) ?? {};
+    const scripts = pkg.scripts ?? {};
+    const nextBuildScript = appendIngestToBuildScript(scripts.build, CONFIG_PATH, KNOWLEDGE_OUTPUT_PATH);
+    const buildScriptChanged = nextBuildScript !== (scripts.build ?? "");
+    const nextDevVars = answers.geminiApiKey
+        ? upsertDevVar(await readTextOrEmpty(DEV_VARS_PATH), "GEMINI_API_KEY", answers.geminiApiKey)
+        : undefined;
+    const summaryLines = [
+        text.summaryConfigLine,
+        text.summaryThemeLine,
+        apiRouteExists ? text.summaryApiRouteSkippedLine(answers.apiRoutePath) : text.summaryApiRouteLine(answers.apiRoutePath),
+        buildScriptChanged ? text.summaryBuildScriptLine : text.summaryBuildScriptUnchangedLine,
+    ];
+    if (nextDevVars !== undefined) {
+        summaryLines.push(text.summaryDevVarsLine);
+    }
+    clack.note(summaryLines.join("\n"), text.summaryTitle);
+    const shouldWrite = await clack.confirm({ message: text.confirmMessage, initialValue: true });
+    if (clack.isCancel(shouldWrite) || !shouldWrite) {
+        clack.cancel(text.writeCancelledMessage);
+        return;
+    }
+    await writeFile(CONFIG_PATH, `${JSON.stringify(configJson, null, 2)}\n`);
+    await writeFile(THEME_CSS_PATH, themeCss);
+    if (apiRouteContent) {
+        await mkdir(dirname(answers.apiRoutePath), { recursive: true });
+        await writeFile(answers.apiRoutePath, apiRouteContent);
+    }
+    if (buildScriptChanged) {
+        const nextPkg = { ...pkg, scripts: { ...scripts, build: nextBuildScript } };
+        await writeFile(PACKAGE_JSON_PATH, `${JSON.stringify(nextPkg, null, 2)}\n`);
+    }
+    if (nextDevVars !== undefined) {
+        await writeFile(DEV_VARS_PATH, nextDevVars);
+    }
+    const endpoint = deriveEndpointPath(answers.apiRoutePath);
+    const snippet = [
+        `<link rel="stylesheet" href="/${THEME_CSS_PATH}">`,
+        `<folio-agent-widget endpoint="${endpoint}" policy-href="/data-policy" lang="${answers.language}"></folio-agent-widget>`,
+        '<script type="module">',
+        '  import { defineFolioAgentWidget } from "@folio-agent/widget";',
+        "  defineFolioAgentWidget();",
+        "</script>",
+    ].join("\n");
+    clack.note(snippet, text.snippetIntro);
+    clack.note(text.d1Note);
+    clack.outro(text.outroTitle);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/init/questions.d.ts

@@ -0,0 +1,20 @@
+import type { Language } from "../chat/types.js";
+import type { ThemeColors, ZennIngestConfig } from "../ingest/types.js";
+export interface WizardAnswers {
+    language: Language;
+    distDir: string;
+    include: string[];
+    zenn?: ZennIngestConfig;
+    contactUrl?: string;
+    theme: ThemeColors;
+    /** Non-empty only when the visitor typed a new key this run; blank means "leave .dev.vars untouched". */
+    geminiApiKey?: string;
+    apiRoutePath: string;
+}
+export declare const DEFAULT_WIZARD_ANSWERS: WizardAnswers;
+/** Pure hex color validation used both as a `clack.text` validator and in tests. */
+export declare function isValidHexColor(value: string): boolean;
+/** Splits a comma-separated glob list into a trimmed, non-empty array. */
+export declare function parseIncludeList(value: string): string[];
+/** Runs the interactive wizard (all-defaults-Enter-to-quick-mode) and returns the collected answers. */
+export declare function runWizard(defaults: WizardAnswers): Promise<WizardAnswers>;

package/dist/init/questions.js

@@ -0,0 +1,125 @@
+import * as clack from "@clack/prompts";
+import { DEFAULT_LANGUAGE } from "../chat/types.js";
+export const DEFAULT_WIZARD_ANSWERS = {
+    language: DEFAULT_LANGUAGE,
+    distDir: "dist",
+    include: ["/**"],
+    theme: { accent: "#2563eb", surface: "#ffffff", text: "#111827" },
+    apiRoutePath: "functions/api/chat.ts",
+};
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** Pure hex color validation used both as a `clack.text` validator and in tests. */
+export function isValidHexColor(value) {
+    return HEX_COLOR_PATTERN.test(value.trim());
+}
+/** Splits a comma-separated glob list into a trimmed, non-empty array. */
+export function parseIncludeList(value) {
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+const WIZARD_TEXT = {
+    ja: {
+        distDirMessage: "ビルド成果物のディレクトリ（distDir）",
+        includeMessage: "知識に含める URL パスのグロブ（カンマ区切りで複数可）",
+        includePlaceholder: "/**",
+        zennConfirmMessage: "Zenn 記事も知識に含めますか？",
+        zennArticlesDirMessage: "Zenn CLI の articles/ ディレクトリへのパス",
+        zennBaseUrlMessage: "記事の公開 URL のベース（例: https://zenn.dev/<username>/articles）",
+        contactUrlMessage: "Contact ページの URL（任意。空 Enter でスキップ）",
+        contactUrlPlaceholder: "https://example.com/contact",
+        accentMessage: "テーマカラー: accent（#付き hex）",
+        surfaceMessage: "テーマカラー: surface（#付き hex）",
+        textColorMessage: "テーマカラー: text（#付き hex）",
+        colorValidationError: "#fff や #ffffff のような hex カラーコードで入力してください。",
+        geminiApiKeyMessage: "Gemini API キー（任意。空 Enter でスキップ）",
+        geminiApiKeySkipNote: "スキップしました。キーは https://aistudio.google.com/apikey から取得できます。",
+        apiRoutePathMessage: "API ルート雛形の出力先",
+        cancelledMessage: "セットアップを中止しました。",
+    },
+    en: {
+        distDirMessage: "Build output directory (distDir)",
+        includeMessage: "URL path globs to include in the knowledge (comma-separated for multiple)",
+        includePlaceholder: "/**",
+        zennConfirmMessage: "Include Zenn articles in the knowledge too?",
+        zennArticlesDirMessage: "Path to the Zenn CLI articles/ directory",
+        zennBaseUrlMessage: "Base URL for published articles (e.g. https://zenn.dev/<username>/articles)",
+        contactUrlMessage: "Contact page URL (optional, press Enter to skip)",
+        contactUrlPlaceholder: "https://example.com/contact",
+        accentMessage: "Theme color: accent (hex with #)",
+        surfaceMessage: "Theme color: surface (hex with #)",
+        textColorMessage: "Theme color: text (hex with #)",
+        colorValidationError: "Enter a hex color code like #fff or #ffffff.",
+        geminiApiKeyMessage: "Gemini API key (optional, press Enter to skip)",
+        geminiApiKeySkipNote: "Skipped. Get a key at https://aistudio.google.com/apikey",
+        apiRoutePathMessage: "Output path for the API route scaffold",
+        cancelledMessage: "Setup cancelled.",
+    },
+};
+function unwrap(value, cancelledMessage) {
+    if (clack.isCancel(value)) {
+        clack.cancel(cancelledMessage);
+        process.exit(0);
+    }
+    return value;
+}
+/** Runs the interactive wizard (all-defaults-Enter-to-quick-mode) and returns the collected answers. */
+export async function runWizard(defaults) {
+    clack.intro("folio-agent-init");
+    const language = unwrap(await clack.select({
+        message: "Language / 言語",
+        options: [
+            { value: "ja", label: "日本語" },
+            { value: "en", label: "English" },
+        ],
+        initialValue: defaults.language,
+    }), WIZARD_TEXT[defaults.language].cancelledMessage);
+    const text = WIZARD_TEXT[language];
+    const distDir = unwrap(await clack.text({ message: text.distDirMessage, initialValue: defaults.distDir }), text.cancelledMessage);
+    const includeInput = unwrap(await clack.text({
+        message: text.includeMessage,
+        placeholder: text.includePlaceholder,
+        initialValue: defaults.include.join(", "),
+    }), text.cancelledMessage);
+    const include = parseIncludeList(includeInput);
+    const wantsZenn = unwrap(await clack.confirm({ message: text.zennConfirmMessage, initialValue: Boolean(defaults.zenn) }), text.cancelledMessage);
+    let zenn;
+    if (wantsZenn) {
+        const articlesDir = unwrap(await clack.text({
+            message: text.zennArticlesDirMessage,
+            initialValue: defaults.zenn?.articlesDir ?? "../zenn-content/articles",
+        }), text.cancelledMessage);
+        const baseUrl = unwrap(await clack.text({
+            message: text.zennBaseUrlMessage,
+            initialValue: defaults.zenn?.baseUrl ?? "",
+        }), text.cancelledMessage);
+        zenn = { articlesDir, baseUrl };
+    }
+    const contactUrlInput = unwrap(await clack.text({
+        message: text.contactUrlMessage,
+        placeholder: text.contactUrlPlaceholder,
+        initialValue: defaults.contactUrl ?? "",
+    }), text.cancelledMessage);
+    const contactUrl = contactUrlInput.trim().length > 0 ? contactUrlInput.trim() : undefined;
+    const colorValidate = (value) => isValidHexColor(value ?? "") ? undefined : text.colorValidationError;
+    const accent = unwrap(await clack.text({ message: text.accentMessage, initialValue: defaults.theme.accent, validate: colorValidate }), text.cancelledMessage);
+    const surface = unwrap(await clack.text({ message: text.surfaceMessage, initialValue: defaults.theme.surface, validate: colorValidate }), text.cancelledMessage);
+    const textColor = unwrap(await clack.text({ message: text.textColorMessage, initialValue: defaults.theme.text, validate: colorValidate }), text.cancelledMessage);
+    const geminiApiKeyInput = unwrap(await clack.password({ message: text.geminiApiKeyMessage }), text.cancelledMessage);
+    const geminiApiKey = geminiApiKeyInput.trim().length > 0 ? geminiApiKeyInput.trim() : undefined;
+    if (!geminiApiKey) {
+        clack.note(text.geminiApiKeySkipNote);
+    }
+    const apiRoutePath = unwrap(await clack.text({ message: text.apiRoutePathMessage, initialValue: defaults.apiRoutePath }), text.cancelledMessage);
+    return {
+        language,
+        distDir,
+        include,
+        zenn,
+        contactUrl,
+        theme: { accent, surface, text: textColor },
+        geminiApiKey,
+        apiRoutePath,
+    };
+}

package/dist/init/writers.d.ts

@@ -0,0 +1,26 @@
+import type { Language } from "../chat/types.js";
+import type { IngestConfig, ThemeColors } from "../ingest/types.js";
+import type { WizardAnswers } from "./questions.js";
+/** Builds `folio-agent.config.json` content, preserving fields the wizard never asks about. */
+export declare function buildConfigJson(answers: WizardAnswers, previous?: IngestConfig): IngestConfig;
+/** Builds `folio-agent.theme.css` content. Re-running the wizard only rewrites this file, which HMR picks up. */
+export declare function buildThemeCss(theme: ThemeColors): string;
+/**
+ * Computes the relative import specifier from the API route file to `<distDir>/knowledge.json`,
+ * independent of the OS path separator (config values are always POSIX-style project-relative paths).
+ */
+export declare function buildKnowledgeImportPath(apiRoutePath: string, distDir: string): string;
+/** Derives the widget `endpoint` URL path from a Pages Functions file path, e.g. "functions/api/chat.ts" -> "/api/chat". */
+export declare function deriveEndpointPath(apiRoutePath: string): string;
+export interface ApiRouteAnswers {
+    apiRoutePath: string;
+    distDir: string;
+    contactUrl?: string;
+    language: Language;
+}
+/** Builds a minimal Cloudflare Pages Function that wires up `createChatHandler`. */
+export declare function buildApiRouteTemplate(answers: ApiRouteAnswers): string;
+/** Appends the ingest command to a `build` script if it isn't already present; otherwise returns it unchanged. */
+export declare function appendIngestToBuildScript(buildScript: string | undefined, configPath: string, knowledgeOutputPath: string): string;
+/** Adds or replaces a single `KEY=value` line in `.dev.vars` content, leaving other lines untouched. */
+export declare function upsertDevVar(content: string, key: string, value: string): string;

package/dist/init/writers.js

@@ -0,0 +1,105 @@
+import { posix } from "node:path";
+import { DEFAULT_LANGUAGE } from "../chat/types.js";
+const INGEST_COMMAND_PREFIX = "folio-agent-ingest";
+/** Builds `folio-agent.config.json` content, preserving fields the wizard never asks about. */
+export function buildConfigJson(answers, previous) {
+    const config = {
+        distDir: answers.distDir,
+        include: answers.include,
+        language: answers.language,
+        theme: answers.theme,
+    };
+    if (previous?.exclude) {
+        config.exclude = previous.exclude;
+    }
+    if (previous?.knowledgeDir) {
+        config.knowledgeDir = previous.knowledgeDir;
+    }
+    if (previous?.tokenWarningThreshold !== undefined) {
+        config.tokenWarningThreshold = previous.tokenWarningThreshold;
+    }
+    if (answers.zenn) {
+        config.zenn = answers.zenn;
+    }
+    return config;
+}
+/** Builds `folio-agent.theme.css` content. Re-running the wizard only rewrites this file, which HMR picks up. */
+export function buildThemeCss(theme) {
+    return [
+        "folio-agent-widget {",
+        `  --folio-agent-accent: ${theme.accent};`,
+        `  --folio-agent-surface: ${theme.surface};`,
+        `  --folio-agent-text: ${theme.text};`,
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * Computes the relative import specifier from the API route file to `<distDir>/knowledge.json`,
+ * independent of the OS path separator (config values are always POSIX-style project-relative paths).
+ */
+export function buildKnowledgeImportPath(apiRoutePath, distDir) {
+    const fromDir = posix.dirname(apiRoutePath);
+    const target = posix.join(distDir, "knowledge.json");
+    const relative = posix.relative(fromDir, target);
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+/** Derives the widget `endpoint` URL path from a Pages Functions file path, e.g. "functions/api/chat.ts" -> "/api/chat". */
+export function deriveEndpointPath(apiRoutePath) {
+    const withoutExt = apiRoutePath.replace(/\.tsx?$/, "");
+    const withoutFunctionsPrefix = withoutExt.replace(/^functions\//, "");
+    return `/${withoutFunctionsPrefix}`;
+}
+/** Builds a minimal Cloudflare Pages Function that wires up `createChatHandler`. */
+export function buildApiRouteTemplate(answers) {
+    const knowledgeImportPath = buildKnowledgeImportPath(answers.apiRoutePath, answers.distDir);
+    const languageLine = answers.language === DEFAULT_LANGUAGE ? "" : `\n    language: ${JSON.stringify(answers.language)},`;
+    const contactUrlLine = answers.contactUrl ? `\n      contactUrl: ${JSON.stringify(answers.contactUrl)},` : "";
+    return [
+        'import { createChatHandler, createGeminiGenerator } from "@folio-agent/handler";',
+        `import knowledgeDoc from "${knowledgeImportPath}";`,
+        "",
+        'const knowledge = knowledgeDoc.pages.map((page) => `# ${page.url}\\n\\n${page.text}`).join("\\n\\n");',
+        "",
+        "interface Env {",
+        "  DB: D1Database;",
+        "  GEMINI_API_KEY: string;",
+        "}",
+        "",
+        "export const onRequestPost: PagesFunction<Env> = async (context) => {",
+        "  const handle = createChatHandler({",
+        `    db: context.env.DB,${languageLine}`,
+        "    generateAnswer: createGeminiGenerator({",
+        "      apiKey: context.env.GEMINI_API_KEY,",
+        `      knowledge,${contactUrlLine}`,
+        "    }),",
+        "  });",
+        "  return handle(context.request);",
+        "};",
+        "",
+    ].join("\n");
+}
+/** Appends the ingest command to a `build` script if it isn't already present; otherwise returns it unchanged. */
+export function appendIngestToBuildScript(buildScript, configPath, knowledgeOutputPath) {
+    const ingestCommand = `${INGEST_COMMAND_PREFIX} ${configPath} ${knowledgeOutputPath}`;
+    const base = (buildScript ?? "").trim();
+    if (base.includes(ingestCommand)) {
+        return base;
+    }
+    return base.length > 0 ? `${base} && ${ingestCommand}` : ingestCommand;
+}
+/** Adds or replaces a single `KEY=value` line in `.dev.vars` content, leaving other lines untouched. */
+export function upsertDevVar(content, key, value) {
+    const trimmed = content.replace(/\n+$/, "");
+    const lines = trimmed.length > 0 ? trimmed.split("\n") : [];
+    const prefix = `${key}=`;
+    const newLine = `${prefix}${value}`;
+    const index = lines.findIndex((line) => line.startsWith(prefix));
+    if (index >= 0) {
+        lines[index] = newLine;
+    }
+    else {
+        lines.push(newLine);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folio-agent/handler",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
     "migrations"
   ],
   "bin": {
-    "folio-agent-ingest": "dist/ingest/cli.js"
+    "folio-agent-ingest": "dist/ingest/cli.js",
+    "folio-agent-init": "dist/init/cli.js"
   },
   "repository": {
     "type": "git",
@@ -37,6 +38,7 @@
     "prepublishOnly": "tsc -b --force"
   },
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "@google/genai": "^2.10.0",
     "@langchain/langgraph": "^1.4.7",
     "node-html-parser": "^8.0.4",