@folio-agent/handler 0.3.0 → 0.3.1

package/dist/init/cli.js

@@ -1,44 +1,60 @@
 #!/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 * 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.",
     },
 };
@@ -65,6 +81,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,15 +90,19 @@ 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);
@@ -89,14 +110,20 @@ async function main() {
     const nextDevVars = answers.geminiApiKey
         ? upsertDevVar(await readTextOrEmpty(DEV_VARS_PATH), "GEMINI_API_KEY", answers.geminiApiKey)
         : undefined;
+    const gitignoreResult = nextDevVars !== undefined ? ensureGitignoreEntry(await readTextOrEmpty(GITIGNORE_PATH), DEV_VARS_PATH) : undefined;
     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 });
@@ -105,8 +132,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);
     }
@@ -116,17 +143,35 @@ async function main() {
     }
     if (nextDevVars !== undefined) {
         await writeFile(DEV_VARS_PATH, nextDevVars);
+        if (gitignoreResult?.changed) {
+            await writeFile(GITIGNORE_PATH, gitignoreResult.content);
+        }
     }
-    const endpoint = deriveEndpointPath(answers.apiRoutePath);
-    const snippet = [
-        `<link rel="stylesheet" href="/${THEME_CSS_PATH}">`,
+    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`);
+    if (nextDevVars !== undefined) {
+        clack.note(gitignoreResult?.changed ? text.gitignoreAppendedNote : text.gitignoreAlreadyPresentNote);
+    }
     clack.note(text.d1Note);
     clack.outro(text.outroTitle);
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folio-agent/handler",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Chat handler (LangGraph.js on Cloudflare Workers) + knowledge ingestion CLI",
   "license": "MIT",
   "type": "module",