@folio-agent/handler 0.5.0 → 0.6.1

package/README.md

@@ -9,10 +9,10 @@
 ```bash
 npm install @folio-agent/handler
 
-# 対話ウィザードで初期設定（config・テーマCSS・APIルート雛形などを生成）
-npx folio-agent-init
+# 初期設定（config・APIルート雛形などを生成。引数は --help）
+npx folio-agent-init --include "/,/works/**,/about"
 
-# ビルド時: 知識ファイルの生成（ウィザードが build スクリプトに追記する）
+# ビルド時: 知識ファイルの生成（init が build スクリプトに追記する）
 npx folio-agent-ingest folio-agent.config.json knowledge.json
 ```
 

package/dist/init/cli.d.ts

@@ -8,9 +8,9 @@ export interface DevVarsAndGitignorePlan {
 }
 /**
  * Computes what to write to `.dev.vars` and `.gitignore`. `.gitignore` protection for
- * `.dev.vars` is unconditional — independent of whether a Gemini API key was entered this run —
- * because a skipped key is commonly filled in by hand afterward per the wizard's own guidance
- * (see `geminiApiKeySkipNote`), and by then the file must already be gitignored.
+ * `.dev.vars` is unconditional — independent of whether `GEMINI_API_KEY` was set this run —
+ * because a missing key is commonly filled in by hand afterward, and by then the file must
+ * already be gitignored.
  */
 export declare function planDevVarsAndGitignore(geminiApiKey: string | undefined, devVarsContent: string, gitignoreContent: string): DevVarsAndGitignorePlan;
-export declare function main(): Promise<void>;
+export declare function main(argv?: string[], env?: Record<string, string | undefined>): Promise<void>;

package/dist/init/cli.js

@@ -1,64 +1,14 @@
 #!/usr/bin/env node
 import { existsSync, realpathSync, statSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, posix } from "node:path";
 import { fileURLToPath } from "node:url";
-import * as clack from "@clack/prompts";
-import { DEFAULT_WIZARD_ANSWERS, runWizard } from "./questions.js";
+import { DEFAULT_API_ROUTE_PATH, InitArgsError, resolveInitRun, USAGE } from "./options.js";
 import { appendIngestToBuildScript, buildApiRouteTemplate, buildConfigJson, buildThemeCss, deriveEndpointPath, ensureGitignoreEntry, PUBLIC_DIR_NAME, resolveThemeCssPath, THEME_CSS_FILENAME, upsertDevVar, } from "./writers.js";
 const CONFIG_PATH = "folio-agent.config.json";
 const PACKAGE_JSON_PATH = "package.json";
 const DEV_VARS_PATH = ".dev.vars";
 const GITIGNORE_PATH = ".gitignore";
-const KNOWLEDGE_OUTPUT_PATH = "dist/knowledge.json";
-const CLI_TEXT = {
-    ja: {
-        summaryTitle: "以下の内容で書き込みます:",
-        summaryConfigLine: `${CONFIG_PATH} を生成・更新`,
-        summaryThemeLine: (path) => `${path} を生成・更新（再実行時はこのファイルの書き換えだけで dev サーバーの HMR に反映されます）`,
-        summaryApiRouteLine: (path) => `${path} を新規生成`,
-        summaryApiRouteSkippedLine: (path) => `${path} は既に存在するためスキップします`,
-        summaryApiRouteNotGeneratedLine: "API ルート雛形は生成しません（既存の配線を利用する設定）",
-        summaryBuildScriptLine: `${PACKAGE_JSON_PATH} の build スクリプトに ingest コマンドを追記`,
-        summaryBuildScriptUnchangedLine: `${PACKAGE_JSON_PATH} の build スクリプトは変更なし（既に含まれています）`,
-        summaryDevVarsLine: `${DEV_VARS_PATH} に GEMINI_API_KEY を書き込み`,
-        summaryGitignoreAppendedLine: `${GITIGNORE_PATH} に ${DEV_VARS_PATH} を追記`,
-        summaryGitignoreAlreadyPresentLine: `${GITIGNORE_PATH} には ${DEV_VARS_PATH} が既に含まれています（追記不要）`,
-        confirmMessage: "この内容で書き込みますか？",
-        writeCancelledMessage: "書き込みを中止しました。",
-        outroTitle: "セットアップが完了しました。",
-        snippetIntro: "サイトの全ページで読み込まれる共通テンプレート（Astro なら `src/layouts/` のレイアウト、素の HTML なら `</body>` の直前）に、以下を1回だけ貼り付けてください（再実行時は不要です）:",
-        snippetIntroExistingConfigNote: "既に <folio-agent-widget> を導入済みの場合は、theme.css の読み込み（`<link>` または `import`）だけ追加すれば十分です。",
-        themeImportGuidanceNote: 'バンドラを使っているサイトでは、レイアウトのスクリプトで `import "./folio-agent.theme.css";` を読み込んでください（相対パスは配置に合わせて調整してください）。',
-        apiRouteNotGeneratedSnippetNote: "API ルート雛形は生成していません。endpoint は実際の配線パスに合わせて書き換えてください。",
-        gitignoreAppendedNote: `${GITIGNORE_PATH} に ${DEV_VARS_PATH} を追記しました。`,
-        gitignoreAlreadyPresentNote: `${GITIGNORE_PATH} には ${DEV_VARS_PATH} が既に含まれていました。`,
-        d1Note: "D1 が未設定でも widget の表示とテーマ確認はローカルで動きます。チャット応答には D1 のセットアップと Gemini API キーが必要です。",
-    },
-    en: {
-        summaryTitle: "The following will be written:",
-        summaryConfigLine: `Generate/update ${CONFIG_PATH}`,
-        summaryThemeLine: (path) => `Generate/update ${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)`,
-        summaryApiRouteNotGeneratedLine: "Skip generating the API route scaffold (site already wires the handler up)",
-        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}`,
-        summaryGitignoreAppendedLine: `Append ${DEV_VARS_PATH} to ${GITIGNORE_PATH}`,
-        summaryGitignoreAlreadyPresentLine: `${GITIGNORE_PATH} already contains ${DEV_VARS_PATH} (no change needed)`,
-        confirmMessage: "Proceed with writing these files?",
-        writeCancelledMessage: "Write cancelled.",
-        outroTitle: "Setup complete.",
-        snippetIntro: "Paste the following once into the common template shared by every page (an Astro layout under `src/layouts/`, or right before `</body>` for plain HTML) — not needed again on re-runs:",
-        snippetIntroExistingConfigNote: "If <folio-agent-widget> is already set up, you only need to add the theme.css load (`<link>` or `import`).",
-        themeImportGuidanceNote: 'If your site uses a bundler, load it from your layout script with `import "./folio-agent.theme.css";` (adjust the relative path to your layout).',
-        apiRouteNotGeneratedSnippetNote: "The API route scaffold wasn't generated. Update the endpoint to match your actual routing.",
-        gitignoreAppendedNote: `Appended ${DEV_VARS_PATH} to ${GITIGNORE_PATH}.`,
-        gitignoreAlreadyPresentNote: `${GITIGNORE_PATH} already contained ${DEV_VARS_PATH}.`,
-        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;
@@ -74,37 +24,38 @@ async function readTextOrEmpty(path) {
 }
 /**
  * Computes what to write to `.dev.vars` and `.gitignore`. `.gitignore` protection for
- * `.dev.vars` is unconditional — independent of whether a Gemini API key was entered this run —
- * because a skipped key is commonly filled in by hand afterward per the wizard's own guidance
- * (see `geminiApiKeySkipNote`), and by then the file must already be gitignored.
+ * `.dev.vars` is unconditional — independent of whether `GEMINI_API_KEY` was set this run —
+ * because a missing key is commonly filled in by hand afterward, and by then the file must
+ * already be gitignored.
  */
 export function planDevVarsAndGitignore(geminiApiKey, devVarsContent, gitignoreContent) {
     const nextDevVars = geminiApiKey ? upsertDevVar(devVarsContent, "GEMINI_API_KEY", geminiApiKey) : undefined;
     const gitignoreResult = ensureGitignoreEntry(gitignoreContent, DEV_VARS_PATH);
     return { nextDevVars, gitignoreResult };
 }
-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,
-        apiRoutePath: undefined,
-    };
-}
-export async function main() {
+export async function main(argv = process.argv.slice(2), env = process.env) {
     const previousConfig = await readJson(CONFIG_PATH);
-    const answers = await runWizard(seedDefaults(previousConfig));
-    const text = CLI_TEXT[answers.language];
+    let run;
+    try {
+        run = resolveInitRun(argv, previousConfig, env);
+    }
+    catch (error) {
+        if (!(error instanceof InitArgsError))
+            throw error;
+        console.error(`folio-agent-init: ${error.message}\n\n${USAGE}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!run) {
+        console.log(USAGE);
+        return;
+    }
+    const { answers, dryRun } = run;
     const configJson = buildConfigJson(answers, previousConfig);
-    const themeCss = buildThemeCss(answers.theme);
     const hasPublicDir = existsSync(PUBLIC_DIR_NAME) && statSync(PUBLIC_DIR_NAME).isDirectory();
     const publicThemeCssPath = `${PUBLIC_DIR_NAME}/${THEME_CSS_FILENAME}`;
     const themeCssPath = resolveThemeCssPath(hasPublicDir, existsSync(publicThemeCssPath), existsSync(THEME_CSS_FILENAME));
+    const themeCssExists = existsSync(themeCssPath);
     const usesPublicDirForTheme = themeCssPath === publicThemeCssPath;
     const apiRouteExists = answers.apiRoutePath !== undefined && existsSync(answers.apiRoutePath);
     const apiRouteContent = answers.apiRoutePath !== undefined && !apiRouteExists
@@ -117,73 +68,78 @@ export async function main() {
         : undefined;
     const pkg = (await readJson(PACKAGE_JSON_PATH)) ?? {};
     const scripts = pkg.scripts ?? {};
-    const nextBuildScript = appendIngestToBuildScript(scripts.build, CONFIG_PATH, KNOWLEDGE_OUTPUT_PATH);
+    // API ルート雛形は <distDir>/knowledge.json を import するので、出力先もそこに揃える
+    const knowledgeOutputPath = posix.join(answers.distDir, "knowledge.json");
+    const nextBuildScript = appendIngestToBuildScript(scripts.build, CONFIG_PATH, knowledgeOutputPath);
     const buildScriptChanged = nextBuildScript !== (scripts.build ?? "");
     const { nextDevVars, gitignoreResult } = planDevVarsAndGitignore(answers.geminiApiKey, await readTextOrEmpty(DEV_VARS_PATH), await readTextOrEmpty(GITIGNORE_PATH));
-    const summaryLines = [
-        text.summaryConfigLine,
-        text.summaryThemeLine(themeCssPath),
-        answers.apiRoutePath !== undefined
-            ? apiRouteExists
-                ? text.summaryApiRouteSkippedLine(answers.apiRoutePath)
-                : text.summaryApiRouteLine(answers.apiRoutePath)
-            : text.summaryApiRouteNotGeneratedLine,
-        buildScriptChanged ? text.summaryBuildScriptLine : text.summaryBuildScriptUnchangedLine,
+    const plan = [
+        `write   ${CONFIG_PATH}`,
+        answers.theme
+            ? `write   ${themeCssPath}`
+            : themeCssExists
+                ? `remove  ${themeCssPath} (theme: auto)`
+                : "skip    theme CSS (theme: auto, the widget follows the site's colors)",
+        answers.apiRoutePath === undefined
+            ? "skip    API route scaffold"
+            : apiRouteExists
+                ? `skip    ${answers.apiRoutePath} (already exists)`
+                : `create  ${answers.apiRoutePath}`,
+        buildScriptChanged ? `update  ${PACKAGE_JSON_PATH} (append ingest to the build script)` : `keep    ${PACKAGE_JSON_PATH}`,
+        nextDevVars !== undefined ? `write   ${DEV_VARS_PATH} (GEMINI_API_KEY)` : `skip    ${DEV_VARS_PATH} (GEMINI_API_KEY is not set)`,
+        gitignoreResult.changed ? `update  ${GITIGNORE_PATH} (add ${DEV_VARS_PATH})` : `keep    ${GITIGNORE_PATH}`,
     ];
-    if (nextDevVars !== undefined) {
-        summaryLines.push(text.summaryDevVarsLine);
+    console.log(`folio-agent-init${dryRun ? " (dry run)" : ""}\n${plan.map((line) => `  ${line}`).join("\n")}\n`);
+    if (!dryRun) {
+        await writeFile(CONFIG_PATH, `${JSON.stringify(configJson, null, 2)}\n`);
+        if (answers.theme) {
+            await writeFile(themeCssPath, buildThemeCss(answers.theme));
+        }
+        else if (themeCssExists) {
+            await rm(themeCssPath);
+        }
+        if (apiRouteContent !== undefined && answers.apiRoutePath !== undefined) {
+            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);
+        }
+        if (gitignoreResult.changed) {
+            await writeFile(GITIGNORE_PATH, gitignoreResult.content);
+        }
     }
-    summaryLines.push(gitignoreResult.changed ? text.summaryGitignoreAppendedLine : text.summaryGitignoreAlreadyPresentLine);
-    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(themeCssPath, themeCss);
-    if (apiRouteContent !== undefined && answers.apiRoutePath !== undefined) {
-        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);
-    }
-    if (gitignoreResult.changed) {
-        await writeFile(GITIGNORE_PATH, gitignoreResult.content);
-    }
-    const endpoint = deriveEndpointPath(answers.apiRoutePath ?? DEFAULT_WIZARD_ANSWERS.apiRoutePath ?? "functions/api/chat.ts");
-    const snippetLines = [
-        ...(usesPublicDirForTheme ? [`<link rel="stylesheet" href="/${THEME_CSS_FILENAME}">`] : []),
+    const endpoint = deriveEndpointPath(answers.apiRoutePath ?? DEFAULT_API_ROUTE_PATH);
+    const snippet = [
+        ...(answers.theme && usesPublicDirForTheme ? [`<link rel="stylesheet" href="/${THEME_CSS_FILENAME}">`] : []),
         `<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");
+    const notes = [
+        "Add this once to the layout shared by every page (an Astro layout, or just before </body>). Not needed again on re-runs:",
+        "",
+        snippet,
     ];
-    const snippet = snippetLines.join("\n");
-    const introNotes = [text.snippetIntro];
-    if (previousConfig) {
-        introNotes.push(text.snippetIntroExistingConfigNote);
-    }
-    if (!usesPublicDirForTheme) {
-        introNotes.push(text.themeImportGuidanceNote);
+    if (answers.theme && !usesPublicDirForTheme) {
+        notes.push("", `With a bundler, load the theme from the layout script: import "./${THEME_CSS_FILENAME}"; (adjust the path).`);
     }
     if (answers.apiRoutePath === undefined) {
-        introNotes.push(text.apiRouteNotGeneratedSnippetNote);
+        notes.push("", "No API route scaffold was generated. Point endpoint at your actual route.");
+    }
+    if (nextDevVars === undefined) {
+        notes.push("", `Chat answers need GEMINI_API_KEY in ${DEV_VARS_PATH} (re-run with the variable set, or add it by hand) and a D1 database.`);
     }
-    clack.note(introNotes.join("\n\n"));
-    console.log(`\n${snippet}\n`);
-    clack.note(gitignoreResult.changed ? text.gitignoreAppendedNote : text.gitignoreAlreadyPresentNote);
-    clack.note(text.d1Note);
-    clack.outro(text.outroTitle);
+    console.log(notes.join("\n"));
 }
-// Only run the wizard when executed directly (the bin entry point); importing this module for
-// unit tests (e.g. `planDevVarsAndGitignore`) must not trigger the interactive CLI as a side effect.
+// Only run when executed directly (the bin entry point); importing this module for unit tests
+// (e.g. `planDevVarsAndGitignore`) must not run the CLI as a side effect.
 // Compares realpaths, not raw paths: npm's node_modules/.bin/ entries are symlinks, so
 // process.argv[1] stays the symlink path while import.meta.url is already the resolved target
 // (see sync/cli.ts for the fuller rationale).

package/dist/init/options.d.ts

@@ -0,0 +1,35 @@
+import type { Language } from "../chat/types.js";
+import type { IngestConfig, ThemeColors, ZennIngestConfig } from "../ingest/types.js";
+export interface InitAnswers {
+    language: Language;
+    distDir: string;
+    include: string[];
+    zenn?: ZennIngestConfig;
+    contactUrl?: string;
+    /** `undefined` means "auto": no theme CSS, the widget follows the host's colors. */
+    theme?: ThemeColors;
+    /** Taken from the `GEMINI_API_KEY` environment variable; `undefined` leaves `.dev.vars` untouched. */
+    geminiApiKey?: string;
+    /** `undefined` means "don't generate the API route scaffold". */
+    apiRoutePath?: string;
+}
+export interface InitRun {
+    answers: InitAnswers;
+    dryRun: boolean;
+}
+export type ThemePreset = "auto" | "poimandres" | "custom";
+export declare const DEFAULT_API_ROUTE_PATH = "functions/api/chat.ts";
+export declare const THEME_PRESETS: Record<Exclude<ThemePreset, "auto" | "custom">, ThemeColors>;
+export declare const USAGE = "Usage: folio-agent-init [options]\n\nWrites folio-agent.config.json, the theme CSS, an API route scaffold, the ingest step in\npackage.json's build script, and .dev.vars. Re-running keeps every value you don't pass.\n\nOptions:\n  --lang <ja|en>              UI and prompt language (default: ja)\n  --dist <dir>                Built site directory (default: dist)\n  --include <globs>           Comma-separated URL globs to ingest (default: /**)\n  --zenn-dir <path>           Zenn CLI articles/ directory (with --zenn-user)\n  --zenn-user <name|url>      Zenn username or articles base URL (with --zenn-dir)\n  --no-zenn                   Stop ingesting Zenn articles\n  --contact-url <url>         Contact page URL used in the API route scaffold\n  --theme <preset>            auto | poimandres | custom (default: auto)\n  --accent <hex>              Theme accent color (implies --theme custom)\n  --surface <hex>             Theme surface color (implies --theme custom)\n  --text <hex>                Theme text color (implies --theme custom)\n  --api-route <path>          Generate the API route scaffold at this path\n                              (default on a fresh setup: functions/api/chat.ts)\n  --no-api-route              Don't generate the API route scaffold\n  --dry-run                   Print what would be written, write nothing\n  -h, --help                  Show this help\n\nEnvironment:\n  GEMINI_API_KEY              Written to .dev.vars when set. Never pass the key as an argument.\n";
+export declare class InitArgsError extends Error {
+}
+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[];
+/**
+ * Normalizes a Zenn `baseUrl` answer. A bare username (no `http(s)://` prefix) is expanded to the
+ * canonical Zenn articles URL; an already-fully-qualified URL passes through unchanged.
+ */
+export declare function normalizeZennBaseUrl(input: string): string;
+/** Returns `undefined` when help was requested; throws `InitArgsError` on invalid input. */
+export declare function resolveInitRun(argv: string[], previous: IngestConfig | undefined, env: Record<string, string | undefined>): InitRun | undefined;

package/dist/init/options.js

@@ -0,0 +1,160 @@
+import { parseArgs } from "node:util";
+import { DEFAULT_LANGUAGE } from "../chat/types.js";
+export const DEFAULT_API_ROUTE_PATH = "functions/api/chat.ts";
+const DEFAULT_DIST_DIR = "dist";
+const DEFAULT_INCLUDE = ["/**"];
+export const THEME_PRESETS = {
+    poimandres: { surface: "#1b1e28", text: "#e4f0fb", accent: "#5de4c7" },
+};
+export const USAGE = `Usage: folio-agent-init [options]
+
+Writes folio-agent.config.json, the theme CSS, an API route scaffold, the ingest step in
+package.json's build script, and .dev.vars. Re-running keeps every value you don't pass.
+
+Options:
+  --lang <ja|en>              UI and prompt language (default: ja)
+  --dist <dir>                Built site directory (default: dist)
+  --include <globs>           Comma-separated URL globs to ingest (default: /**)
+  --zenn-dir <path>           Zenn CLI articles/ directory (with --zenn-user)
+  --zenn-user <name|url>      Zenn username or articles base URL (with --zenn-dir)
+  --no-zenn                   Stop ingesting Zenn articles
+  --contact-url <url>         Contact page URL used in the API route scaffold
+  --theme <preset>            auto | poimandres | custom (default: auto)
+  --accent <hex>              Theme accent color (implies --theme custom)
+  --surface <hex>             Theme surface color (implies --theme custom)
+  --text <hex>                Theme text color (implies --theme custom)
+  --api-route <path>          Generate the API route scaffold at this path
+                              (default on a fresh setup: ${DEFAULT_API_ROUTE_PATH})
+  --no-api-route              Don't generate the API route scaffold
+  --dry-run                   Print what would be written, write nothing
+  -h, --help                  Show this help
+
+Environment:
+  GEMINI_API_KEY              Written to .dev.vars when set. Never pass the key as an argument.
+`;
+export class InitArgsError extends Error {
+}
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+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);
+}
+/**
+ * Normalizes a Zenn `baseUrl` answer. A bare username (no `http(s)://` prefix) is expanded to the
+ * canonical Zenn articles URL; an already-fully-qualified URL passes through unchanged.
+ */
+export function normalizeZennBaseUrl(input) {
+    const trimmed = input.trim();
+    return /^https?:\/\//i.test(trimmed) ? trimmed : `https://zenn.dev/${trimmed}/articles`;
+}
+const OPTIONS = {
+    lang: { type: "string" },
+    dist: { type: "string" },
+    include: { type: "string" },
+    "zenn-dir": { type: "string" },
+    "zenn-user": { type: "string" },
+    "no-zenn": { type: "boolean" },
+    "contact-url": { type: "string" },
+    theme: { type: "string" },
+    accent: { type: "string" },
+    surface: { type: "string" },
+    text: { type: "string" },
+    "api-route": { type: "string" },
+    "no-api-route": { type: "boolean" },
+    "dry-run": { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+};
+function parseInitArgs(argv) {
+    try {
+        return parseArgs({ args: argv, options: OPTIONS, strict: true, allowPositionals: false }).values;
+    }
+    catch (error) {
+        throw new InitArgsError(error instanceof Error ? error.message : String(error));
+    }
+}
+/** Returns `undefined` when help was requested; throws `InitArgsError` on invalid input. */
+export function resolveInitRun(argv, previous, env) {
+    const values = parseInitArgs(argv);
+    if (values.help)
+        return undefined;
+    const language = values.lang ?? previous?.language ?? DEFAULT_LANGUAGE;
+    if (language !== "ja" && language !== "en") {
+        throw new InitArgsError(`--lang must be "ja" or "en" (got "${language}")`);
+    }
+    const include = values.include !== undefined ? parseIncludeList(values.include) : (previous?.include ?? DEFAULT_INCLUDE);
+    if (include.length === 0)
+        throw new InitArgsError("--include needs at least one URL glob");
+    const apiRoutePath = resolveApiRoutePath(values["api-route"], values["no-api-route"], previous !== undefined);
+    const geminiApiKey = env.GEMINI_API_KEY?.trim() || undefined;
+    return {
+        dryRun: values["dry-run"] ?? false,
+        answers: {
+            language,
+            distDir: values.dist ?? previous?.distDir ?? DEFAULT_DIST_DIR,
+            include,
+            zenn: resolveZenn(values["zenn-dir"], values["zenn-user"], values["no-zenn"], previous?.zenn),
+            contactUrl: values["contact-url"]?.trim() || undefined,
+            theme: resolveTheme(values, previous?.theme),
+            geminiApiKey,
+            apiRoutePath,
+        },
+    };
+}
+function resolveApiRoutePath(path, skip, hasPreviousConfig) {
+    if (path !== undefined && skip)
+        throw new InitArgsError("--api-route and --no-api-route can't be combined");
+    if (skip)
+        return undefined;
+    if (path !== undefined)
+        return path;
+    // 既存の設定がある再実行では、サイトが別の経路で handler を配線済みのことが多い
+    return hasPreviousConfig ? undefined : DEFAULT_API_ROUTE_PATH;
+}
+function resolveZenn(dir, user, remove, previous) {
+    if (remove) {
+        if (dir !== undefined || user !== undefined)
+            throw new InitArgsError("--no-zenn can't be combined with --zenn-dir / --zenn-user");
+        return undefined;
+    }
+    const articlesDir = dir ?? previous?.articlesDir;
+    const baseUrl = user !== undefined ? normalizeZennBaseUrl(user) : previous?.baseUrl;
+    if (articlesDir === undefined && baseUrl === undefined)
+        return undefined;
+    if (articlesDir === undefined || baseUrl === undefined) {
+        throw new InitArgsError("Zenn ingest needs both --zenn-dir and --zenn-user");
+    }
+    return { articlesDir, baseUrl };
+}
+function resolveTheme(values, previous) {
+    const hasColor = values.accent !== undefined || values.surface !== undefined || values.text !== undefined;
+    const preset = values.theme ?? (hasColor ? "custom" : undefined);
+    if (preset === undefined)
+        return previous;
+    if (preset !== "custom" && hasColor) {
+        throw new InitArgsError(`--accent / --surface / --text only apply to --theme custom (got --theme ${preset})`);
+    }
+    if (preset === "auto")
+        return undefined;
+    if (preset === "poimandres")
+        return THEME_PRESETS.poimandres;
+    if (preset !== "custom")
+        throw new InitArgsError(`--theme must be auto, poimandres or custom (got "${preset}")`);
+    const theme = {
+        accent: values.accent ?? previous?.accent,
+        surface: values.surface ?? previous?.surface,
+        text: values.text ?? previous?.text,
+    };
+    for (const [key, value] of Object.entries(theme)) {
+        if (value === undefined)
+            throw new InitArgsError(`--theme custom needs --${key}`);
+        if (!isValidHexColor(value))
+            throw new InitArgsError(`--${key} must be a hex color like #fff or #ffffff (got "${value}")`);
+    }
+    return { accent: theme.accent.trim(), surface: theme.surface.trim(), text: theme.text.trim() };
+}

package/dist/init/writers.d.ts

@@ -1,11 +1,11 @@
 import type { Language } from "../chat/types.js";
 import type { IngestConfig, ThemeColors } from "../ingest/types.js";
-import type { WizardAnswers } from "./questions.js";
+import type { InitAnswers } from "./options.js";
 export declare const THEME_CSS_FILENAME = "folio-agent.theme.css";
 export declare const PUBLIC_DIR_NAME = "public";
-/** 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. */
+/** Builds `folio-agent.config.json` content, keeping every previous field that init doesn't manage. */
+export declare function buildConfigJson(answers: InitAnswers, previous?: IngestConfig): IngestConfig;
+/** Builds `folio-agent.theme.css` content. Re-running init only rewrites this file, which HMR picks up. */
 export declare function buildThemeCss(theme: ThemeColors): string;
 /**
  * Decides where `folio-agent.theme.css` should be written. A file outside `public/` (or its
@@ -29,7 +29,11 @@ export interface ApiRouteAnswers {
 }
 /** 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. */
+/**
+ * Appends the ingest command to a `build` script unless it already runs ingest. Any existing
+ * `folio-agent-ingest` counts, whatever its arguments: sites often write to a different output
+ * path than the default, and appending a second run would ingest twice.
+ */
 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

@@ -3,29 +3,25 @@ import { DEFAULT_LANGUAGE } from "../chat/types.js";
 const INGEST_COMMAND_PREFIX = "folio-agent-ingest";
 export const THEME_CSS_FILENAME = "folio-agent.theme.css";
 export const PUBLIC_DIR_NAME = "public";
-/** Builds `folio-agent.config.json` content, preserving fields the wizard never asks about. */
+/** Builds `folio-agent.config.json` content, keeping every previous field that init doesn't manage. */
 export function buildConfigJson(answers, previous) {
     const config = {
+        ...previous,
         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;
+    delete config.theme;
+    delete config.zenn;
+    if (answers.theme) {
+        config.theme = answers.theme;
     }
     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. */
+/** Builds `folio-agent.theme.css` content. Re-running init only rewrites this file, which HMR picks up. */
 export function buildThemeCss(theme) {
     return [
         "folio-agent-widget {",
@@ -94,11 +90,15 @@ export function buildApiRouteTemplate(answers) {
         "",
     ].join("\n");
 }
-/** Appends the ingest command to a `build` script if it isn't already present; otherwise returns it unchanged. */
+/**
+ * Appends the ingest command to a `build` script unless it already runs ingest. Any existing
+ * `folio-agent-ingest` counts, whatever its arguments: sites often write to a different output
+ * path than the default, and appending a second run would ingest twice.
+ */
 export function appendIngestToBuildScript(buildScript, configPath, knowledgeOutputPath) {
     const ingestCommand = `${INGEST_COMMAND_PREFIX} ${configPath} ${knowledgeOutputPath}`;
     const base = (buildScript ?? "").trim();
-    if (base.includes(ingestCommand)) {
+    if (base.includes(INGEST_COMMAND_PREFIX)) {
         return base;
     }
     return base.length > 0 ? `${base} && ${ingestCommand}` : ingestCommand;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folio-agent/handler",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
   "license": "MIT",
   "type": "module",
@@ -39,15 +39,14 @@
     "prepublishOnly": "tsc -b --force"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "@google/genai": "^2.21.0",
-    "@langchain/langgraph": "^1.4.14",
-    "node-html-parser": "^9.0.3",
+    "@google/genai": "^2.23.0",
+    "@langchain/langgraph": "^1.4.16",
+    "node-html-parser": "^9.0.4",
     "picomatch": "^4.0.7"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260906.1",
+    "@cloudflare/workers-types": "^5.20260920.1",
     "@types/picomatch": "^4.0.2",
-    "wrangler": "^4.129.0"
+    "wrangler": "^4.135.0"
   }
 }

package/dist/init/questions.d.ts

@@ -1,32 +0,0 @@
-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;
-    /** `undefined` means "don't generate the API route scaffold" (site already wires the handler elsewhere). */
-    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[];
-/**
- * Normalizes a Zenn `baseUrl` answer. A bare username (no `http(s)://` prefix) is expanded to the
- * canonical Zenn articles URL; an already-fully-qualified URL passes through unchanged.
- */
-export declare function normalizeZennBaseUrl(input: string): string;
-/**
- * Default answer for the "API route scaffold output path" question: the scaffold path for a
- * fresh setup (no previous config), or `undefined` ("don't generate") when re-running against an
- * existing config, since the site likely already wires the handler up some other way.
- */
-export declare function defaultApiRoutePath(hasPreviousConfig: boolean): string | undefined;
-/** 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

@@ -1,155 +0,0 @@
-import * as clack from "@clack/prompts";
-import { DEFAULT_LANGUAGE } from "../chat/types.js";
-const DEFAULT_API_ROUTE_PATH = "functions/api/chat.ts";
-export const DEFAULT_WIZARD_ANSWERS = {
-    language: DEFAULT_LANGUAGE,
-    distDir: "dist",
-    include: ["/**"],
-    theme: { accent: "#2563eb", surface: "#ffffff", text: "#111827" },
-    apiRoutePath: DEFAULT_API_ROUTE_PATH,
-};
-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);
-}
-/**
- * Normalizes a Zenn `baseUrl` answer. A bare username (no `http(s)://` prefix) is expanded to the
- * canonical Zenn articles URL; an already-fully-qualified URL passes through unchanged.
- */
-export function normalizeZennBaseUrl(input) {
-    const trimmed = input.trim();
-    return /^https?:\/\//i.test(trimmed) ? trimmed : `https://zenn.dev/${trimmed}/articles`;
-}
-/**
- * Default answer for the "API route scaffold output path" question: the scaffold path for a
- * fresh setup (no previous config), or `undefined` ("don't generate") when re-running against an
- * existing config, since the site likely already wires the handler up some other way.
- */
-export function defaultApiRoutePath(hasPreviousConfig) {
-    return hasPreviousConfig ? undefined : DEFAULT_API_ROUTE_PATH;
-}
-const WIZARD_TEXT = {
-    ja: {
-        distDirMessage: "ビルド成果物のディレクトリ（distDir）",
-        includeMessage: "知識に含める URL パスのグロブ（カンマ区切りで複数可）",
-        includePlaceholder: "/**",
-        zennConfirmMessage: "Zenn 記事も知識に含めますか？",
-        zennArticlesDirMessage: "Zenn CLI の articles/ ディレクトリへのパス",
-        zennBaseUrlMessage: "記事の公開 URL のベース（例: https://zenn.dev/<username>/articles、またはユーザー名のみでも可）",
-        zennBaseUrlNormalizedNote: (baseUrl) => `✅ ${baseUrl} として登録します。`,
-        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 ルート雛形の出力先（空 Enter で生成しない。既に別の経路で配線済みのサイト向け）",
-        apiRoutePathPlaceholder: "functions/api/chat.ts",
-        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, or just your username)",
-        zennBaseUrlNormalizedNote: (baseUrl) => `✅ Registering as ${baseUrl}.`,
-        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 (blank to skip generating it, e.g. if already wired up elsewhere)",
-        apiRoutePathPlaceholder: "functions/api/chat.ts",
-        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 baseUrlInput = unwrap(await clack.text({
-            message: text.zennBaseUrlMessage,
-            initialValue: defaults.zenn?.baseUrl ?? "",
-        }), text.cancelledMessage);
-        const baseUrl = normalizeZennBaseUrl(baseUrlInput);
-        if (baseUrl !== baseUrlInput.trim()) {
-            clack.note(text.zennBaseUrlNormalizedNote(baseUrl));
-        }
-        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 apiRoutePathInput = unwrap(await clack.text({
-        message: text.apiRoutePathMessage,
-        placeholder: text.apiRoutePathPlaceholder,
-        initialValue: defaults.apiRoutePath ?? "",
-    }), text.cancelledMessage);
-    const apiRoutePath = apiRoutePathInput.trim().length > 0 ? apiRoutePathInput.trim() : undefined;
-    return {
-        language,
-        distDir,
-        include,
-        zenn,
-        contactUrl,
-        theme: { accent, surface, text: textColor },
-        geminiApiKey,
-        apiRoutePath,
-    };
-}