amenbo 0.1.0

package/dist/cache.js

@@ -0,0 +1,286 @@
+/**
+ * cache.ts — better-sqlite3によるURL単位のローカルキャッシュ。
+ *
+ * 保存場所: $AMENBO_CACHE_DIR または ~/.cache/amenbo/cache.sqlite
+ * URL毎にETag/Last-Modified/本文ハッシュ/変換済みMarkdown/取得時刻を保存する。
+ * TTL内はローカル返却(fresh)、TTL超過時はIf-None-Match/If-Modified-Sinceで再検証し、
+ * 304なら再変換せず返す(revalidated)。未キャッシュ/再検証不可はmiss。
+ *
+ * スクリーンショット(screenshotツール/mode:auto→screenshot)もキャッシュ対象とする。
+ * バイナリ本体はSQLiteに入れず、$AMENBO_CACHE_DIR/screenshots/配下にファイル保存し、
+ * SQLiteにはそのパスのみを保存する(DBの肥大化を避けるため)。
+ * 画像はレンダリング結果でありETag等の安価な再検証手段が無いため、TTLベースの
+ * fresh/miss判定のみとする(revalidatedは無い)。
+ *
+ * Phase 4 テンプレート学習: ドメイン毎に直近ページのブロックハッシュ集合を domain_pages に
+ * 記録し、直近N ページ全てに共通して出現したハッシュを定型ブロック(ヘッダ/フッタ/定型ナビ等)
+ * と判定する(getTemplateBlockHashes)。除去処理自体はtemplateLearning.tsが行う。
+ *
+ * CLI併設対応: politenessのドメイン毎レート制御(直近リクエスト時刻)は元々プロセス内メモリ
+ * のみで保持していたが、CLIは1コマンド=1プロセスのためプロセスを跨いで状態を引き継げず、
+ * 短時間に連続実行すると同一ドメインへの最小間隔が守られない。host_requests テーブルへ
+ * 最終リクエスト時刻を永続化し、PolitenessManagerのstoreオプションとして注入することで
+ * MCPサーバー/CLIの複数プロセス間で共有する(再起動直後の連続アクセスも守れる副次効果あり)。
+ * journal_mode=WAL は複数プロセスからの同時アクセスを想定して設定している。
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+const DEFAULT_TTL_MS = 15 * 60 * 1000; // 15分
+/** Phase 4テンプレート学習: 定型ブロック判定に使う「直近ページ数」の既定値。 */
+const DEFAULT_TEMPLATE_RECENT_PAGES = 3;
+function resolveCacheDir() {
+    const dir = process.env.AMENBO_CACHE_DIR ?? join(homedir(), ".cache", "amenbo");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+export function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** スクリーンショットのキャッシュキー(url+撮影パラメータの組)を計算する。 */
+export function computeScreenshotCacheKey(url, width, scale, fullPage) {
+    return hashContent(`${url}|w=${width}|s=${scale}|full=${fullPage}`);
+}
+export class PageCache {
+    db;
+    cacheDir;
+    ttlMs;
+    now;
+    constructor(options = {}) {
+        this.cacheDir = options.cacheDir ?? resolveCacheDir();
+        if (!existsSync(this.cacheDir)) {
+            mkdirSync(this.cacheDir, { recursive: true });
+        }
+        this.db = new Database(options.dbPath ?? join(this.cacheDir, "cache.sqlite"));
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.now = options.now ?? Date.now;
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS pages (
+        url TEXT PRIMARY KEY,
+        etag TEXT,
+        last_modified TEXT,
+        content_hash TEXT NOT NULL,
+        markdown TEXT NOT NULL,
+        metadata TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS screenshots (
+        cache_key TEXT PRIMARY KEY,
+        url TEXT NOT NULL,
+        tile_paths TEXT NOT NULL,
+        metadata TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS domain_pages (
+        domain TEXT NOT NULL,
+        url TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL,
+        block_hashes TEXT NOT NULL,
+        PRIMARY KEY (domain, url)
+      )
+    `);
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_domain_pages_domain_fetched_at ON domain_pages (domain, fetched_at DESC)`);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS host_requests (
+        host TEXT PRIMARY KEY,
+        last_request_at INTEGER NOT NULL
+      )
+    `);
+        // M3: TTL超過削除・サイズ上限が無くディスクが無制限に増加する問題への対応。
+        // 起動(コンストラクタ)のたびにTTL超過エントリを掃除する。
+        this.pruneExpired();
+    }
+    /**
+     * M3: TTL超過エントリを削除する(ディスク無制限増加の防止)。起動時に自動実行される。
+     * screenshotsはSQLite行に加え、対応するPNGファイル(タイル)もあわせて削除する。
+     */
+    pruneExpired() {
+        const cutoff = this.now() - this.ttlMs;
+        this.db.prepare("DELETE FROM pages WHERE fetched_at < ?").run(cutoff);
+        this.db.prepare("DELETE FROM domain_pages WHERE fetched_at < ?").run(cutoff);
+        // code-reviewer指摘: host_requestsもM3の対象から漏れていた(訪問ホスト毎に1行増える
+        // 無制限増加テーブルという点でdomain_pages等と同じ性質を持つため、他テーブルと一貫させる)。
+        this.db.prepare("DELETE FROM host_requests WHERE last_request_at < ?").run(cutoff);
+        const expiredScreenshots = this.db.prepare("SELECT * FROM screenshots WHERE fetched_at < ?").all(cutoff);
+        for (const row of expiredScreenshots) {
+            const tilePaths = JSON.parse(row.tile_paths);
+            for (const filePath of tilePaths) {
+                try {
+                    rmSync(filePath, { force: true });
+                }
+                catch {
+                    // 既に削除済み等のファイルシステムエラーはベストエフォートで無視する
+                }
+            }
+        }
+        this.db.prepare("DELETE FROM screenshots WHERE fetched_at < ?").run(cutoff);
+    }
+    /** 保存済みエントリを取得する(TTL判定は行わない。判定は isFresh を使う)。 */
+    get(url) {
+        const row = this.db.prepare("SELECT * FROM pages WHERE url = ?").get(url);
+        if (!row)
+            return undefined;
+        return {
+            url: row.url,
+            etag: row.etag,
+            lastModified: row.last_modified,
+            contentHash: row.content_hash,
+            markdown: row.markdown,
+            metadata: JSON.parse(row.metadata),
+            fetchedAt: row.fetched_at,
+        };
+    }
+    /** エントリ(ページ/スクリーンショットいずれも可)がTTL内(再検証不要)かどうかを判定する。 */
+    isFresh(entry) {
+        return this.now() - entry.fetchedAt < this.ttlMs;
+    }
+    /** 保存済みスクリーンショットエントリを取得する(TTL判定は isFresh を使う)。 */
+    getScreenshot(cacheKey) {
+        const row = this.db.prepare("SELECT * FROM screenshots WHERE cache_key = ?").get(cacheKey);
+        if (!row)
+            return undefined;
+        return {
+            cacheKey: row.cache_key,
+            url: row.url,
+            tilePaths: JSON.parse(row.tile_paths),
+            metadata: JSON.parse(row.metadata),
+            fetchedAt: row.fetched_at,
+        };
+    }
+    /** スクリーンショットのタイル群をファイル保存し、パスをSQLiteへ記録する。 */
+    setScreenshot(input) {
+        const tileDir = join(this.cacheDir, "screenshots", input.cacheKey);
+        mkdirSync(tileDir, { recursive: true });
+        const tilePaths = input.tiles.map((buffer, index) => {
+            const filePath = join(tileDir, `tile-${index}.png`);
+            writeFileSync(filePath, buffer);
+            return filePath;
+        });
+        const fetchedAt = this.now();
+        this.db
+            .prepare(`INSERT INTO screenshots (cache_key, url, tile_paths, metadata, fetched_at)
+         VALUES (@cacheKey, @url, @tilePaths, @metadata, @fetchedAt)
+         ON CONFLICT(cache_key) DO UPDATE SET
+           url = excluded.url,
+           tile_paths = excluded.tile_paths,
+           metadata = excluded.metadata,
+           fetched_at = excluded.fetched_at`)
+            .run({
+            cacheKey: input.cacheKey,
+            url: input.url,
+            tilePaths: JSON.stringify(tilePaths),
+            metadata: JSON.stringify(input.metadata),
+            fetchedAt,
+        });
+        return { cacheKey: input.cacheKey, url: input.url, tilePaths, metadata: input.metadata, fetchedAt };
+    }
+    /** 新規取得結果を保存(既存があれば上書き)する。 */
+    set(input) {
+        const contentHash = hashContent(input.markdown);
+        const fetchedAt = this.now();
+        this.db
+            .prepare(`INSERT INTO pages (url, etag, last_modified, content_hash, markdown, metadata, fetched_at)
+         VALUES (@url, @etag, @lastModified, @contentHash, @markdown, @metadata, @fetchedAt)
+         ON CONFLICT(url) DO UPDATE SET
+           etag = excluded.etag,
+           last_modified = excluded.last_modified,
+           content_hash = excluded.content_hash,
+           markdown = excluded.markdown,
+           metadata = excluded.metadata,
+           fetched_at = excluded.fetched_at`)
+            .run({
+            url: input.url,
+            etag: input.etag,
+            lastModified: input.lastModified,
+            contentHash,
+            markdown: input.markdown,
+            metadata: JSON.stringify(input.metadata),
+            fetchedAt,
+        });
+        return {
+            url: input.url,
+            etag: input.etag,
+            lastModified: input.lastModified,
+            contentHash,
+            markdown: input.markdown,
+            metadata: input.metadata,
+            fetchedAt,
+        };
+    }
+    /** 304再検証成功時: 本文は変えず取得時刻のみ更新する(再変換しない)。 */
+    touch(url) {
+        this.db.prepare("UPDATE pages SET fetched_at = ? WHERE url = ?").run(this.now(), url);
+    }
+    /** Phase 4テンプレート学習: このページの(除去前・全)ブロックハッシュ集合をドメイン別に記録する。 */
+    recordDomainPageBlocks(domain, url, blockHashes) {
+        this.db
+            .prepare(`INSERT INTO domain_pages (domain, url, fetched_at, block_hashes)
+         VALUES (@domain, @url, @fetchedAt, @blockHashes)
+         ON CONFLICT(domain, url) DO UPDATE SET
+           fetched_at = excluded.fetched_at,
+           block_hashes = excluded.block_hashes`)
+            .run({ domain, url, fetchedAt: this.now(), blockHashes: JSON.stringify(blockHashes) });
+    }
+    /**
+     * 直近recentPages件のページ全てに共通して出現したブロックハッシュを定型ブロック
+     * (ヘッダ/フッタ/定型ナビ等)とみなして返す。まだrecentPages件分のページ履歴が
+     * 無い場合(コールドスタート)は誤除去を避けるため空集合を返す。
+     */
+    getTemplateBlockHashes(domain, recentPages = DEFAULT_TEMPLATE_RECENT_PAGES) {
+        const rows = this.db
+            .prepare("SELECT * FROM domain_pages WHERE domain = ? ORDER BY fetched_at DESC LIMIT ?")
+            .all(domain, recentPages);
+        if (rows.length < recentPages)
+            return new Set();
+        const occurrenceCount = new Map();
+        for (const row of rows) {
+            const hashes = JSON.parse(row.block_hashes);
+            for (const hash of hashes) {
+                occurrenceCount.set(hash, (occurrenceCount.get(hash) ?? 0) + 1);
+            }
+        }
+        const templateHashes = new Set();
+        for (const [hash, count] of occurrenceCount) {
+            if (count >= recentPages)
+                templateHashes.add(hash);
+        }
+        return templateHashes;
+    }
+    /**
+     * CLI併設対応: ホスト(例 "example.com")の最終リクエスト時刻を返す(未記録ならnull)。
+     * PolitenessManagerのstoreオプションとして注入し、プロセス間でレート制御状態を共有するために使う。
+     */
+    getHostLastRequestAt(host) {
+        const row = this.db.prepare("SELECT * FROM host_requests WHERE host = ?").get(host);
+        return row ? row.last_request_at : null;
+    }
+    /**
+     * ホストの最終リクエスト時刻を記録する。
+     *
+     * code-reviewer指摘: MCPサーバー/CLIの複数プロセスが同一ホストへほぼ同時にwaitTurnを
+     * 実行すると、「読み取り→待機→書き込み」の3ステップがプロセス間でアトミックではないため
+     * 後勝ちの書き込みが古い時刻で新しい時刻を上書きし、最小間隔がすり抜けうる
+     * (完全な直列化はプロセス内のみ。プロセス間はベストエフォート。PolitenessManagerの
+     * store JSDoc参照)。せめて時刻が巻き戻らないよう、SQL側でMAXを取って単調増加を保証する。
+     */
+    setHostLastRequestAt(host, at) {
+        this.db
+            .prepare(`INSERT INTO host_requests (host, last_request_at)
+         VALUES (@host, @lastRequestAt)
+         ON CONFLICT(host) DO UPDATE SET last_request_at = MAX(last_request_at, excluded.last_request_at)`)
+            .run({ host, lastRequestAt: at });
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { type ImageBlock, type TextBlock } from "./core.js";
+/** 引数の使い方が不正な場合に投げる(cli.ts側でusageを表示しexit code 2にする)。 */
+export declare class CliUsageError extends Error {
+}
+declare const FETCH_MODES: readonly ["auto", "markdown", "outline", "screenshot"];
+export type CliFetchMode = (typeof FETCH_MODES)[number];
+export type ParsedCommand = {
+    kind: "serve";
+} | {
+    kind: "version";
+} | {
+    kind: "help";
+    topic?: "fetch" | "links" | "screenshot";
+} | ParsedFetchCommand | ParsedLinksCommand | ParsedScreenshotCommand;
+export interface ParsedFetchCommand {
+    kind: "fetch";
+    url: string;
+    mode?: CliFetchMode;
+    selector?: string;
+    section?: string;
+    page?: number;
+    maxTokens?: number;
+    forceFull?: boolean;
+    outDir?: string;
+}
+export interface ParsedLinksCommand {
+    kind: "links";
+    url: string;
+    filter?: string;
+}
+export interface ParsedScreenshotCommand {
+    kind: "screenshot";
+    url: string;
+    viewportOnly?: boolean;
+    width?: number;
+    scale?: number;
+    outDir?: string;
+}
+/** CLI引数(process.argv.slice(2)相当)をコマンドへパースする純関数。 */
+export declare function parseCliArgs(argv: string[]): ParsedCommand;
+/** TextBlockは標準出力へ、ImageBlockはoutDir配下へ保存しパスを列挙する。テスト用export。 */
+export declare function writeBlocks(blocks: Array<TextBlock | ImageBlock>, url: string, outDir: string): void;
+/** CLIのメイン処理。テスト用export(引数を受け取り終了コードを返す純粋な形にしてある)。 */
+export declare function run(argv: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * cli.ts — amenboのコマンドラインエントリ。MCPサーバー(server.ts)と同一のコア(core.ts)を
+ * 共有し、シェルスクリプト/CI/デバッグ用途で同じfetch/links/screenshotをコマンドとして使えるようにする。
+ *
+ * - 引数なし、または `amenbo serve` はMCPサーバーとして起動する(既存の.mcp.jsonの
+ *   `"command": "amenbo"` との後方互換のため最重要)。
+ * - `amenbo fetch/links/screenshot <url> [options]` は対応するcore.tsのハンドラを呼び、
+ *   TextBlockはそのまま標準出力へ、ImageBlock(スクリーンショット/スキャンPDF画像)は
+ *   --out-dir配下へファイル保存しパスを列挙する(エージェント/ユーザーがそのまま開けるように)。
+ * - 引数パース(parseCliArgs)は純関数として切り出し、ユニットテストできるようにしている。
+ * - キャッシュ・差分応答・レート制御の状態はMCPサーバーと同じ ~/.cache/amenbo (cache.ts)を
+ *   共有する。CLIは1コマンド=1プロセスのため、politenessのドメイン毎レート制御は
+ *   core.ts側でcacheをstoreとして注入したPolitenessManagerがプロセス間永続化する。
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { cache, formatLinksResponse, handleFetchTool, handleScreenshotTool, politeness, resolvePackageVersion, } from "./core.js";
+import { AmenboError } from "./errors.js";
+import { closeBrowser } from "./fetcher/browser.js";
+import { discoverLinks } from "./links.js";
+import { runServer } from "./server.js";
+// ---- 引数パース(純関数。ユニットテスト対象) ----
+/** 引数の使い方が不正な場合に投げる(cli.ts側でusageを表示しexit code 2にする)。 */
+export class CliUsageError extends Error {
+}
+const FETCH_MODES = ["auto", "markdown", "outline", "screenshot"];
+function parsePositiveInt(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        throw new CliUsageError(`${flag}は正の整数で指定してください: ${raw}`);
+    }
+    return n;
+}
+function parsePositiveFloat(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new CliUsageError(`${flag}は正の数値で指定してください: ${raw}`);
+    }
+    return n;
+}
+function requireUrl(positionals, command) {
+    const url = positionals[0];
+    if (!url) {
+        throw new CliUsageError(`${command}: URLを指定してください`);
+    }
+    if (positionals.length > 1) {
+        throw new CliUsageError(`${command}: 不明な引数です: ${positionals[1]}`);
+    }
+    return url;
+}
+/** node:util parseArgsの例外(不明なオプション等)をCliUsageErrorへ変換する。 */
+function safeParseArgs(args, command, options) {
+    try {
+        // node:util parseArgsは第2型引数を渡さなくてもoptions定義から値の型を推論するが、
+        // このジェネリックラッパー越しだと推論が効かないため戻り値側で明示キャストする。
+        const result = parseArgs({ args, allowPositionals: true, options });
+        return result;
+    }
+    catch (error) {
+        throw new CliUsageError(`${command}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function parseFetchArgs(args) {
+    const { values, positionals } = safeParseArgs(args, "fetch", {
+        mode: { type: "string" },
+        selector: { type: "string" },
+        section: { type: "string" },
+        page: { type: "string" },
+        "max-tokens": { type: "string" },
+        "force-full": { type: "boolean" },
+        "out-dir": { type: "string" },
+        help: { type: "boolean", short: "h" },
+    });
+    if (values.help)
+        return { kind: "help", topic: "fetch" };
+    const url = requireUrl(positionals, "fetch");
+    if (values.mode !== undefined && !FETCH_MODES.includes(values.mode)) {
+        throw new CliUsageError(`fetch: --modeは${FETCH_MODES.join("/")}のいずれかで指定してください: ${values.mode}`);
+    }
+    return {
+        kind: "fetch",
+        url,
+        ...(values.mode !== undefined ? { mode: values.mode } : {}),
+        ...(values.selector !== undefined ? { selector: values.selector } : {}),
+        ...(values.section !== undefined ? { section: values.section } : {}),
+        ...(values.page !== undefined ? { page: parsePositiveInt(values.page, "--page") } : {}),
+        ...(values["max-tokens"] !== undefined ? { maxTokens: parsePositiveInt(values["max-tokens"], "--max-tokens") } : {}),
+        ...(values["force-full"] ? { forceFull: true } : {}),
+        ...(values["out-dir"] !== undefined ? { outDir: values["out-dir"] } : {}),
+    };
+}
+function parseLinksArgs(args) {
+    const { values, positionals } = safeParseArgs(args, "links", {
+        filter: { type: "string" },
+        help: { type: "boolean", short: "h" },
+    });
+    if (values.help)
+        return { kind: "help", topic: "links" };
+    const url = requireUrl(positionals, "links");
+    return {
+        kind: "links",
+        url,
+        ...(values.filter !== undefined ? { filter: values.filter } : {}),
+    };
+}
+function parseScreenshotArgs(args) {
+    const { values, positionals } = safeParseArgs(args, "screenshot", {
+        "viewport-only": { type: "boolean" },
+        width: { type: "string" },
+        scale: { type: "string" },
+        "out-dir": { type: "string" },
+        help: { type: "boolean", short: "h" },
+    });
+    if (values.help)
+        return { kind: "help", topic: "screenshot" };
+    const url = requireUrl(positionals, "screenshot");
+    return {
+        kind: "screenshot",
+        url,
+        ...(values["viewport-only"] ? { viewportOnly: true } : {}),
+        ...(values.width !== undefined ? { width: parsePositiveInt(values.width, "--width") } : {}),
+        ...(values.scale !== undefined ? { scale: parsePositiveFloat(values.scale, "--scale") } : {}),
+        ...(values["out-dir"] !== undefined ? { outDir: values["out-dir"] } : {}),
+    };
+}
+/** CLI引数(process.argv.slice(2)相当)をコマンドへパースする純関数。 */
+export function parseCliArgs(argv) {
+    if (argv.length === 0)
+        return { kind: "serve" };
+    const [first, ...rest] = argv;
+    if (first === "--version" || first === "-v")
+        return { kind: "version" };
+    if (first === "--help" || first === "-h")
+        return { kind: "help" };
+    if (first === "serve")
+        return { kind: "serve" };
+    if (first === "fetch")
+        return parseFetchArgs(rest);
+    if (first === "links")
+        return parseLinksArgs(rest);
+    if (first === "screenshot")
+        return parseScreenshotArgs(rest);
+    throw new CliUsageError(`不明なコマンドです: ${first}`);
+}
+// ---- ヘルプ/usage文言 ----
+function usageText() {
+    return [
+        "amenbo [command] [options]",
+        "",
+        "Commands:",
+        "  serve                          MCPサーバーとして起動する(既定。引数省略時と同じ)",
+        "  fetch <url> [options]          ページをMarkdownとして取得する",
+        "  links <url> [options]          ページ内のリンクを列挙する(sitemap/RSS優先)",
+        "  screenshot <url> [options]     ページのスクリーンショットを撮影する",
+        "",
+        "Options:",
+        "  -h, --help       ヘルプを表示する",
+        "  -v, --version    バージョンを表示する",
+        "",
+        "各コマンドの詳細は `amenbo <command> --help` を参照してください。",
+    ].join("\n");
+}
+function fetchHelpText() {
+    return [
+        "amenbo fetch <url> [options]",
+        "",
+        "Options:",
+        "  --mode <auto|markdown|outline|screenshot>   取得モード(既定 auto)",
+        "  --selector <css>                            本文を絞り込むCSSセレクタ",
+        "  --section <id>                              outlineで得たsection ID。その節のMarkdownのみ返す",
+        "  --page <n>                                  ページ番号(既定 1)",
+        "  --max-tokens <n>                             1ページの概算トークン上限(既定 8000)",
+        "  --force-full                                 差分応答(unchanged/diff)と定型ブロック除去を無効化し常に全文を返す",
+        "  --out-dir <dir>                              screenshot切替時の画像保存先(既定 カレントディレクトリ)",
+    ].join("\n");
+}
+function linksHelpText() {
+    return ["amenbo links <url> [options]", "", "Options:", "  --filter <pattern>   URL/リンクテキストの部分一致、または*を使ったglob"].join("\n");
+}
+function screenshotHelpText() {
+    return [
+        "amenbo screenshot <url> [options]",
+        "",
+        "Options:",
+        "  --viewport-only     最初のビューポート分のみ撮影する(既定はfullPage)",
+        "  --width <n>         タイル幅px(既定 1280)",
+        "  --scale <x>         解像度スケール(既定 1.0)。小さいほど画像トークンが減る",
+        "  --out-dir <dir>     画像保存先(既定 カレントディレクトリ)",
+    ].join("\n");
+}
+function helpText(topic) {
+    if (topic === "fetch")
+        return fetchHelpText();
+    if (topic === "links")
+        return linksHelpText();
+    if (topic === "screenshot")
+        return screenshotHelpText();
+    return usageText();
+}
+// ---- 出力(TextBlockはstdout、ImageBlockはファイル保存) ----
+/** ファイル名として安全なホスト名(取れなければ"page")。amenbo-<hostname>-<連番>.pngの命名に使う。 */
+function hostnameForFilename(url) {
+    try {
+        return new URL(url).hostname.replace(/[^A-Za-z0-9.-]/g, "_") || "page";
+    }
+    catch {
+        return "page";
+    }
+}
+/** TextBlockは標準出力へ、ImageBlockはoutDir配下へ保存しパスを列挙する。テスト用export。 */
+export function writeBlocks(blocks, url, outDir) {
+    const hostname = hostnameForFilename(url);
+    const savedPaths = [];
+    let sequence = 0;
+    for (const block of blocks) {
+        if (block.type === "text") {
+            process.stdout.write(`${block.text}\n`);
+            continue;
+        }
+        sequence++;
+        if (savedPaths.length === 0) {
+            mkdirSync(outDir, { recursive: true });
+        }
+        const extension = block.mimeType === "image/png" ? "png" : "bin";
+        const filePath = join(outDir, `amenbo-${hostname}-${sequence}.${extension}`);
+        writeFileSync(filePath, Buffer.from(block.data, "base64"));
+        savedPaths.push(filePath);
+    }
+    if (savedPaths.length > 0) {
+        process.stdout.write(`\n画像を保存しました:\n${savedPaths.map((filePath) => `- ${filePath}`).join("\n")}\n`);
+    }
+}
+// ---- 実行 ----
+async function dispatch(command) {
+    if (command.kind === "fetch") {
+        const input = {
+            url: command.url,
+            ...(command.mode !== undefined ? { mode: command.mode } : {}),
+            ...(command.selector !== undefined ? { selector: command.selector } : {}),
+            ...(command.section !== undefined ? { section: command.section } : {}),
+            ...(command.page !== undefined ? { page: command.page } : {}),
+            ...(command.maxTokens !== undefined ? { max_tokens: command.maxTokens } : {}),
+            ...(command.forceFull !== undefined ? { force_full: command.forceFull } : {}),
+        };
+        const blocks = await handleFetchTool(input);
+        writeBlocks(blocks, command.url, command.outDir ?? process.cwd());
+        return;
+    }
+    if (command.kind === "links") {
+        const result = await discoverLinks(command.url, politeness, command.filter !== undefined ? { filter: command.filter } : {});
+        process.stdout.write(`${formatLinksResponse(command.url, result)}\n`);
+        return;
+    }
+    const input = {
+        url: command.url,
+        fullPage: !command.viewportOnly,
+        ...(command.width !== undefined ? { width: command.width } : {}),
+        ...(command.scale !== undefined ? { scale: command.scale } : {}),
+    };
+    const blocks = await handleScreenshotTool(input);
+    writeBlocks(blocks, command.url, command.outDir ?? process.cwd());
+}
+/** CLIのメイン処理。テスト用export(引数を受け取り終了コードを返す純粋な形にしてある)。 */
+export async function run(argv) {
+    let command;
+    try {
+        command = parseCliArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            process.stderr.write(`${error.message}\n\n${usageText()}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    if (command.kind === "help") {
+        process.stdout.write(`${helpText(command.topic)}\n`);
+        return 0;
+    }
+    if (command.kind === "version") {
+        process.stdout.write(`${resolvePackageVersion()}\n`);
+        return 0;
+    }
+    if (command.kind === "serve") {
+        // MCPサーバーはstdioで待受け続けるプロセスのため、closeBrowser/cache.closeは呼ばない
+        // (呼ぶとサーバー起動直後にキャッシュ/ブラウザが使えなくなる)。
+        await runServer();
+        return 0;
+    }
+    try {
+        await dispatch(command);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof AmenboError) {
+            process.stderr.write(`${error.message}\n`);
+        }
+        else {
+            console.error(error);
+        }
+        return 1;
+    }
+    finally {
+        // playwrightのブラウザが開いたままだとプロセスがハングするため、サブコマンド完了後は
+        // 確実にクローズしてから終了する(1実行=1プロセスのCLIではプロセス終了時のcloseに頼れない)。
+        await closeBrowser();
+        cache.close();
+    }
+}
+/** server.tsのisDirectlyExecutedと同様、テストからparseCliArgs等をimportした際にrun()が走らないようにするガード。 */
+function isDirectlyExecuted() {
+    return typeof process.argv[1] === "string" && fileURLToPath(import.meta.url) === process.argv[1];
+}
+if (isDirectlyExecuted()) {
+    run(process.argv.slice(2))
+        .then((exitCode) => {
+        process.exitCode = exitCode;
+    })
+        .catch((error) => {
+        console.error(error);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map