@folio-agent/handler 0.3.1 → 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

@@ -2,6 +2,7 @@
 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, ensureGitignoreEntry, PUBLIC_DIR_NAME, resolveThemeCssPath, THEME_CSS_FILENAME, upsertDevVar, } from "./writers.js";
@@ -71,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;
@@ -107,10 +119,7 @@ async function main() {
     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 gitignoreResult = nextDevVars !== undefined ? ensureGitignoreEntry(await readTextOrEmpty(GITIGNORE_PATH), DEV_VARS_PATH) : undefined;
+    const { nextDevVars, gitignoreResult } = planDevVarsAndGitignore(answers.geminiApiKey, await readTextOrEmpty(DEV_VARS_PATH), await readTextOrEmpty(GITIGNORE_PATH));
     const summaryLines = [
         text.summaryConfigLine,
         text.summaryThemeLine(themeCssPath),
@@ -123,8 +132,8 @@ async function main() {
     ];
     if (nextDevVars !== undefined) {
         summaryLines.push(text.summaryDevVarsLine);
-        summaryLines.push(gitignoreResult?.changed ? text.summaryGitignoreAppendedLine : text.summaryGitignoreAlreadyPresentLine);
     }
+    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) {
@@ -143,9 +152,9 @@ async function main() {
     }
     if (nextDevVars !== undefined) {
         await writeFile(DEV_VARS_PATH, nextDevVars);
-        if (gitignoreResult?.changed) {
-            await writeFile(GITIGNORE_PATH, gitignoreResult.content);
-        }
+    }
+    if (gitignoreResult.changed) {
+        await writeFile(GITIGNORE_PATH, gitignoreResult.content);
     }
     const endpoint = deriveEndpointPath(answers.apiRoutePath ?? DEFAULT_WIZARD_ANSWERS.apiRoutePath ?? "functions/api/chat.ts");
     const snippetLines = [
@@ -169,13 +178,15 @@ async function main() {
     }
     clack.note(introNotes.join("\n\n"));
     console.log(`\n${snippet}\n`);
-    if (nextDevVars !== undefined) {
-        clack.note(gitignoreResult?.changed ? text.gitignoreAppendedNote : text.gitignoreAlreadyPresentNote);
-    }
+    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/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.1",
+  "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",