@folio-agent/handler 0.3.0 → 0.4.0

package/dist/ingest/generate.js

@@ -1,11 +1,24 @@
+import { readFile, stat } from "node:fs/promises";
 import { createUrlMatcher } from "./glob.js";
 import { htmlToText } from "./html-to-text.js";
 import { readTextFile, scanDist, scanKnowledgeDir } from "./scan-dist.js";
 import { DEFAULT_TOKEN_WARNING_THRESHOLD, estimateTokens } from "./token-count.js";
 import { scanZennArticles } from "./zenn.js";
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
 export async function generateKnowledge(config) {
     const matchesUrl = createUrlMatcher(config);
     const pages = [];
+    const warnings = [];
     const distFiles = await scanDist(config.distDir);
     for (const file of distFiles.filter((f) => matchesUrl(f.urlPath))) {
         const html = await readTextFile(file.absolutePath);
@@ -20,12 +33,20 @@ export async function generateKnowledge(config) {
         }
     }
     if (config.zenn) {
-        pages.push(...(await scanZennArticles(config.zenn)));
+        if (await pathExists(config.zenn.articlesDir)) {
+            pages.push(...(await scanZennArticles(config.zenn)));
+        }
+        else if (config.zennSnapshotPath) {
+            const snapshot = JSON.parse(await readFile(config.zennSnapshotPath, "utf-8"));
+            pages.push(...snapshot);
+        }
+        else {
+            warnings.push(`articlesDir not found: ${config.zenn.articlesDir} — skipping zenn ingest`);
+        }
     }
     pages.sort((a, b) => a.url.localeCompare(b.url));
     const estimatedTokens = estimateTokens(pages.map((p) => p.text).join("\n"));
     const threshold = config.tokenWarningThreshold ?? DEFAULT_TOKEN_WARNING_THRESHOLD;
-    const warnings = [];
     if (estimatedTokens > threshold) {
         warnings.push(`estimated knowledge size (${estimatedTokens} tokens) exceeds the warning threshold (${threshold}). ` +
             "Consider narrowing include globs, or switching to a RAG-based approach.");

package/dist/ingest/types.d.ts

@@ -10,6 +10,13 @@ export interface IngestConfig {
     knowledgeDir?: string;
     /** Zenn CLI articles/ ingestion. Omit to skip Zenn articles entirely. */
     zenn?: ZennIngestConfig;
+    /**
+     * Path to a snapshot JSON produced by `folio-agent-sync-zenn`. Used as a
+     * fallback source of Zenn pages in environments where `zenn.articlesDir`
+     * cannot be read (e.g. CI, where the articles directory often comes from a
+     * separate/private repo that isn't checked out).
+     */
+    zennSnapshotPath?: string;
     /** 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. */

package/dist/init/cli.d.ts

@@ -1,2 +1,15 @@
 #!/usr/bin/env node
-export {};
+export interface DevVarsAndGitignorePlan {
+    nextDevVars: string | undefined;
+    gitignoreResult: {
+        content: string;
+        changed: boolean;
+    };
+}
+/**
+ * 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.
+ */
+export declare function planDevVarsAndGitignore(geminiApiKey: string | undefined, devVarsContent: string, gitignoreContent: string): DevVarsAndGitignorePlan;

package/dist/init/cli.js

@@ -1,44 +1,61 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as clack from "@clack/prompts";
 import { DEFAULT_WIZARD_ANSWERS, runWizard } from "./questions.js";
-import { appendIngestToBuildScript, buildApiRouteTemplate, buildConfigJson, buildThemeCss, deriveEndpointPath, upsertDevVar, } from "./writers.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 THEME_CSS_PATH = "folio-agent.theme.css";
 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: `${THEME_CSS_PATH} を生成・更新（再実行時はこのファイルの書き換えだけで dev サーバーの HMR に反映されます）`,
+        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: "レイアウトに以下を1回だけ貼り付けてください（再実行時は不要です）:",
+        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: `Generate/update ${THEME_CSS_PATH} (re-running the wizard only rewrites this file, and your dev server's HMR picks it up)`,
+        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 into your layout once (not needed again on re-runs):",
+        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.",
     },
 };
@@ -55,6 +72,17 @@ async function readJson(path) {
 async function readTextOrEmpty(path) {
     return existsSync(path) ? readFile(path, "utf-8") : "";
 }
+/**
+ * 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.
+ */
+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;
@@ -65,6 +93,7 @@ function seedDefaults(previous) {
         include: previous.include ?? DEFAULT_WIZARD_ANSWERS.include,
         zenn: previous.zenn,
         theme: previous.theme ?? DEFAULT_WIZARD_ANSWERS.theme,
+        apiRoutePath: undefined,
     };
 }
 async function main() {
@@ -73,31 +102,38 @@ async function main() {
     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({
+    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 usesPublicDirForTheme = themeCssPath === publicThemeCssPath;
+    const apiRouteExists = answers.apiRoutePath !== undefined && existsSync(answers.apiRoutePath);
+    const apiRouteContent = answers.apiRoutePath !== undefined && !apiRouteExists
+        ? buildApiRouteTemplate({
             apiRoutePath: answers.apiRoutePath,
             distDir: answers.distDir,
             contactUrl: answers.contactUrl,
             language: answers.language,
-        });
+        })
+        : undefined;
     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 { nextDevVars, gitignoreResult } = planDevVarsAndGitignore(answers.geminiApiKey, await readTextOrEmpty(DEV_VARS_PATH), await readTextOrEmpty(GITIGNORE_PATH));
     const summaryLines = [
         text.summaryConfigLine,
-        text.summaryThemeLine,
-        apiRouteExists ? text.summaryApiRouteSkippedLine(answers.apiRoutePath) : text.summaryApiRouteLine(answers.apiRoutePath),
+        text.summaryThemeLine(themeCssPath),
+        answers.apiRoutePath !== undefined
+            ? apiRouteExists
+                ? text.summaryApiRouteSkippedLine(answers.apiRoutePath)
+                : text.summaryApiRouteLine(answers.apiRoutePath)
+            : text.summaryApiRouteNotGeneratedLine,
         buildScriptChanged ? text.summaryBuildScriptLine : text.summaryBuildScriptUnchangedLine,
     ];
     if (nextDevVars !== undefined) {
         summaryLines.push(text.summaryDevVarsLine);
     }
+    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) {
@@ -105,8 +141,8 @@ async function main() {
         return;
     }
     await writeFile(CONFIG_PATH, `${JSON.stringify(configJson, null, 2)}\n`);
-    await writeFile(THEME_CSS_PATH, themeCss);
-    if (apiRouteContent) {
+    await writeFile(themeCssPath, themeCss);
+    if (apiRouteContent !== undefined && answers.apiRoutePath !== undefined) {
         await mkdir(dirname(answers.apiRoutePath), { recursive: true });
         await writeFile(answers.apiRoutePath, apiRouteContent);
     }
@@ -117,20 +153,40 @@ async function main() {
     if (nextDevVars !== undefined) {
         await writeFile(DEV_VARS_PATH, nextDevVars);
     }
-    const endpoint = deriveEndpointPath(answers.apiRoutePath);
-    const snippet = [
-        `<link rel="stylesheet" href="/${THEME_CSS_PATH}">`,
+    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}">`] : []),
         `<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);
+    ];
+    const snippet = snippetLines.join("\n");
+    const introNotes = [text.snippetIntro];
+    if (previousConfig) {
+        introNotes.push(text.snippetIntroExistingConfigNote);
+    }
+    if (!usesPublicDirForTheme) {
+        introNotes.push(text.themeImportGuidanceNote);
+    }
+    if (answers.apiRoutePath === undefined) {
+        introNotes.push(text.apiRouteNotGeneratedSnippetNote);
+    }
+    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);
 }
-main().catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
-});
+// 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.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/dist/init/questions.d.ts

@@ -9,12 +9,24 @@ export interface WizardAnswers {
     theme: ThemeColors;
     /** Non-empty only when the visitor typed a new key this run; blank means "leave .dev.vars untouched". */
     geminiApiKey?: string;
-    apiRoutePath: 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,11 +1,12 @@
 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: "functions/api/chat.ts",
+    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. */
@@ -19,6 +20,22 @@ export function parseIncludeList(value) {
         .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）",
@@ -26,7 +43,8 @@ const WIZARD_TEXT = {
         includePlaceholder: "/**",
         zennConfirmMessage: "Zenn 記事も知識に含めますか？",
         zennArticlesDirMessage: "Zenn CLI の articles/ ディレクトリへのパス",
-        zennBaseUrlMessage: "記事の公開 URL のベース（例: https://zenn.dev/<username>/articles）",
+        zennBaseUrlMessage: "記事の公開 URL のベース（例: https://zenn.dev/<username>/articles、またはユーザー名のみでも可）",
+        zennBaseUrlNormalizedNote: (baseUrl) => `✅ ${baseUrl} として登録します。`,
         contactUrlMessage: "Contact ページの URL（任意。空 Enter でスキップ）",
         contactUrlPlaceholder: "https://example.com/contact",
         accentMessage: "テーマカラー: accent（#付き hex）",
@@ -35,7 +53,8 @@ const WIZARD_TEXT = {
         colorValidationError: "#fff や #ffffff のような hex カラーコードで入力してください。",
         geminiApiKeyMessage: "Gemini API キー（任意。空 Enter でスキップ）",
         geminiApiKeySkipNote: "スキップしました。キーは https://aistudio.google.com/apikey から取得できます。",
-        apiRoutePathMessage: "API ルート雛形の出力先",
+        apiRoutePathMessage: "API ルート雛形の出力先（空 Enter で生成しない。既に別の経路で配線済みのサイト向け）",
+        apiRoutePathPlaceholder: "functions/api/chat.ts",
         cancelledMessage: "セットアップを中止しました。",
     },
     en: {
@@ -44,7 +63,8 @@ const WIZARD_TEXT = {
         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)",
+        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 #)",
@@ -53,7 +73,8 @@ const WIZARD_TEXT = {
         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",
+        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.",
     },
 };
@@ -90,10 +111,14 @@ export async function runWizard(defaults) {
             message: text.zennArticlesDirMessage,
             initialValue: defaults.zenn?.articlesDir ?? "../zenn-content/articles",
         }), text.cancelledMessage);
-        const baseUrl = unwrap(await clack.text({
+        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({
@@ -111,7 +136,12 @@ export async function runWizard(defaults) {
     if (!geminiApiKey) {
         clack.note(text.geminiApiKeySkipNote);
     }
-    const apiRoutePath = unwrap(await clack.text({ message: text.apiRoutePathMessage, initialValue: defaults.apiRoutePath }), text.cancelledMessage);
+    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,

package/dist/init/writers.d.ts

@@ -1,10 +1,19 @@
 import type { Language } from "../chat/types.js";
 import type { IngestConfig, ThemeColors } from "../ingest/types.js";
 import type { WizardAnswers } from "./questions.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. */
 export declare function buildThemeCss(theme: ThemeColors): string;
+/**
+ * Decides where `folio-agent.theme.css` should be written. A file outside `public/` (or its
+ * framework equivalent) isn't served by most static-site pipelines (Astro, Next, etc.), so a
+ * `public/` directory is preferred when present. Re-runs reuse whichever location already holds
+ * the file, so switching `public/` in and out of existence mid-project doesn't orphan a stale copy.
+ */
+export declare function resolveThemeCssPath(hasPublicDir: boolean, existingPublicFile: boolean, existingRootFile: boolean): 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).
@@ -24,3 +33,12 @@ export declare function buildApiRouteTemplate(answers: ApiRouteAnswers): string;
 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;
+/**
+ * Ensures `entry` appears as its own line in `.gitignore` content, appending it if no existing
+ * line starts with it. Intentionally doesn't interpret comments or wider patterns (e.g. `*.vars`);
+ * a duplicate append is harmless, so a plain line-start check is enough.
+ */
+export declare function ensureGitignoreEntry(content: string, entry: string): {
+    content: string;
+    changed: boolean;
+};

package/dist/init/writers.js

@@ -1,6 +1,8 @@
 import { posix } from "node:path";
 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. */
 export function buildConfigJson(answers, previous) {
     const config = {
@@ -34,6 +36,19 @@ export function buildThemeCss(theme) {
         "",
     ].join("\n");
 }
+/**
+ * Decides where `folio-agent.theme.css` should be written. A file outside `public/` (or its
+ * framework equivalent) isn't served by most static-site pipelines (Astro, Next, etc.), so a
+ * `public/` directory is preferred when present. Re-runs reuse whichever location already holds
+ * the file, so switching `public/` in and out of existence mid-project doesn't orphan a stale copy.
+ */
+export function resolveThemeCssPath(hasPublicDir, existingPublicFile, existingRootFile) {
+    if (existingPublicFile)
+        return `${PUBLIC_DIR_NAME}/${THEME_CSS_FILENAME}`;
+    if (existingRootFile)
+        return THEME_CSS_FILENAME;
+    return hasPublicDir ? `${PUBLIC_DIR_NAME}/${THEME_CSS_FILENAME}` : THEME_CSS_FILENAME;
+}
 /**
  * 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).
@@ -103,3 +118,18 @@ export function upsertDevVar(content, key, value) {
     }
     return `${lines.join("\n")}\n`;
 }
+/**
+ * Ensures `entry` appears as its own line in `.gitignore` content, appending it if no existing
+ * line starts with it. Intentionally doesn't interpret comments or wider patterns (e.g. `*.vars`);
+ * a duplicate append is harmless, so a plain line-start check is enough.
+ */
+export function ensureGitignoreEntry(content, entry) {
+    const lines = content.length > 0 ? content.split("\n") : [];
+    const alreadyPresent = lines.some((line) => line.startsWith(entry));
+    if (alreadyPresent) {
+        return { content, changed: false };
+    }
+    const trimmed = content.replace(/\n+$/, "");
+    const nextContent = trimmed.length > 0 ? `${trimmed}\n${entry}\n` : `${entry}\n`;
+    return { content: nextContent, changed: true };
+}

package/dist/sync/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import type { KnowledgePage } from "../ingest/types.js";
+/**
+ * Reads `config.zenn` from `configPath`, scans the configured articles/
+ * directory, and writes the resulting `KnowledgePage[]` to `outputPath` as
+ * JSON. Throws if `config.zenn` is not set.
+ */
+export declare function syncZennSnapshot(configPath: string, outputPath: string): Promise<KnowledgePage[]>;

package/dist/sync/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { scanZennArticles } from "../ingest/zenn.js";
+/**
+ * Reads `config.zenn` from `configPath`, scans the configured articles/
+ * directory, and writes the resulting `KnowledgePage[]` to `outputPath` as
+ * JSON. Throws if `config.zenn` is not set.
+ */
+export async function syncZennSnapshot(configPath, outputPath) {
+    const config = JSON.parse(await readFile(configPath, "utf-8"));
+    if (!config.zenn) {
+        throw new Error("config.zenn is not set");
+    }
+    const pages = await scanZennArticles(config.zenn);
+    await writeFile(outputPath, JSON.stringify(pages, null, 2));
+    return pages;
+}
+async function main() {
+    const configPath = process.argv[2];
+    const outputPath = process.argv[3];
+    if (!configPath || !outputPath) {
+        console.error("usage: folio-agent-sync-zenn <config.json> <output.json>");
+        process.exitCode = 1;
+        return;
+    }
+    const pages = await syncZennSnapshot(configPath, outputPath);
+    console.log(`wrote ${pages.length} zenn page(s) -> ${outputPath}`);
+}
+// Only run when executed directly (e.g. `folio-agent-sync-zenn ...`), not
+// when imported by tests.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folio-agent/handler",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,8 @@
   ],
   "bin": {
     "folio-agent-ingest": "dist/ingest/cli.js",
-    "folio-agent-init": "dist/init/cli.js"
+    "folio-agent-init": "dist/init/cli.js",
+    "folio-agent-sync-zenn": "dist/sync/cli.js"
   },
   "repository": {
     "type": "git",