@ozzylabs/feedradar 0.1.3 → 0.1.5

package/dist/schemas/source.js

@@ -5,6 +5,8 @@ export const SourceKindSchema = z.enum([
     "html-js",
     "github-releases",
     "npm-registry",
+    "json-feed",
+    "json-api",
 ]);
 /**
  * Match modes for keyword evaluation (ADR-0006).
@@ -93,6 +95,114 @@ export const SourceJsOptionsSchema = z.object({
     timeout: z.number().int().positive().default(30000),
     userAgent: z.string().optional(),
 });
+/**
+ * HTTP options for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Phase 1 supports GET only. `headers` accepts arbitrary key/value pairs and
+ * supports `${VAR}` env-var interpolation (resolved by the adapter, never
+ * persisted to log / frontmatter — see ADR-0012 §D5c).
+ *
+ * The schema deliberately does not validate header values against env names —
+ * the adapter handles unresolved `${VAR}` placeholders by omitting the header
+ * (degraded fetch). This lets public APIs work without env wiring while
+ * authenticated APIs fail-fast with a 401/403 at runtime.
+ */
+export const SourceHttpOptionsSchema = z.object({
+    method: z.literal("GET").default("GET"),
+    headers: z.record(z.string(), z.string()).default({}),
+});
+/**
+ * Pagination configuration for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Five wire formats are supported:
+ *
+ *   page         — `?page=K&pageSize=N` (e.g. AWS What's New, dev.to)
+ *   offset       — `?offset=K&limit=N`
+ *   cursor       — `?after=<cursorValue>` with `nextCursor` extracted via JSONPath
+ *   link-header  — `Link: <...>; rel="next"` HTTP header
+ *   token        — `?pageToken=<opaque>` opaque continuation token
+ *   none         — single request, no pagination
+ *
+ * `maxPages` is a hard cap to prevent runaway loops / DoS on misconfigured
+ * recipes. The default (20) matches a conservative bound for normal-mode
+ * fetching; `--backfill` can override via `--max-pages` to walk further.
+ *
+ * `nextCursorPath` / `totalPath` are JSONPath-lite expressions resolved against
+ * the parsed response body. `totalPath` is consulted in backfill mode to
+ * compute an upper bound on pages and short-circuit early when the total is
+ * known.
+ */
+export const SourcePaginationSchema = z.object({
+    type: z.enum(["page", "offset", "cursor", "link-header", "token", "none"]),
+    /**
+     * Query parameter name for the page / offset / token (e.g. `page`, `offset`,
+     * `after`, `pageToken`). Required for `page` / `offset` / `cursor` / `token`;
+     * ignored for `link-header` / `none`.
+     */
+    param: z.string().min(1).optional(),
+    /** Initial value (e.g. 0 for offset, 1 for page-number, undefined for cursor/token). */
+    start: z.number().int().optional(),
+    /** Items per page (e.g. 100 for AWS, 30 for dev.to). */
+    pageSize: z.number().int().positive().optional(),
+    /** Query parameter name for the page-size value. Defaults to `pageSize` when present. */
+    pageSizeParam: z.string().min(1).optional(),
+    /** JSONPath-lite to the next-cursor / next-token value in the response body. */
+    nextCursorPath: z.string().min(1).optional(),
+    /** JSONPath-lite to the total-count value in the response body (backfill-mode early-stop hint). */
+    totalPath: z.string().min(1).optional(),
+    /** Hard cap on pages traversed. Default 20 (normal mode); `--max-pages` overrides in backfill. */
+    maxPages: z.number().int().positive().default(20),
+});
+/**
+ * Selector ruleset for `kind: json-api` sources (ADR-0012 §D2).
+ *
+ * Every selector is a JSONPath-lite expression (`src/core/feeds/_jsonpath.ts`).
+ *
+ * Every field is optional. When omitted the adapter falls back to a default
+ * selector chain per field (#174 / ADR-0012 §D2 defaults). For "simple"
+ * page-based APIs (dev.to, JSON Feed-shaped) the recipe can therefore omit
+ * `jsonSelectors` entirely (or use just `{}`) and rely on:
+ *
+ *   items       — `$.items[*] || $.data[*] || $.results[*] || $.posts[*] || $.entries[*] || $[*]`
+ *   title       — `$.title || $.name || $.headline`
+ *   link        — `$.url || $.link || $.permalink || $.html_url`
+ *   publishedAt — `$.publishedAt || $.published_at || $.date || $.created_at || $.pubDate`
+ *   summary     — `$.summary || $.description || $.excerpt || $.body`
+ *
+ * - `publisherId` has no fallback chain (stable id derivation falls through
+ *   to `link` URL by default; see `derive-id.ts`).
+ * - `body` / `tags` have no fallback chain (rarely needed for normalization).
+ * - `linkBase` resolves relative `link` values against an explicit base URL
+ *   (defaults to `source.url`). See field-level docstring for details (#204).
+ *
+ * Note that selectors are evaluated against each item element (already
+ * dereferenced via `items`), so paths inside this schema commonly use `$` as
+ * the per-item root (e.g. `$.title`, `$.created_at`).
+ */
+export const SourceJsonApiSelectorsSchema = z.object({
+    items: z.string().min(1).optional(),
+    title: z.string().min(1).optional(),
+    link: z.string().min(1).optional(),
+    publisherId: z.string().min(1).optional(),
+    summary: z.string().min(1).optional(),
+    publishedAt: z.string().min(1).optional(),
+    body: z.string().min(1).optional(),
+    tags: z.string().min(1).optional(),
+    /**
+     * Base URL used to resolve relative `link` values returned by the API
+     * (#204). Many APIs (e.g. AWS What's New) return `headlineUrl` as a path
+     * like `/about-aws/whats-new/.../` instead of a full URL, which causes
+     * every item to be silently dropped at `ItemSchema` validation. When
+     * `linkBase` is set, the adapter resolves relative `link` values against
+     * it (`new URL(raw, linkBase)`); when omitted, `source.url` is used as
+     * the base, mirroring how the html adapter resolves `<a href="/...">`.
+     * Absolute links pass through untouched in either case.
+     *
+     * Must be a fully-qualified http(s) URL — invalid bases would silently
+     * mis-resolve, so we fail-fast at schema parse time.
+     */
+    linkBase: z.string().url().optional(),
+});
 /**
  * Validate `Source.url` per kind.
  *
@@ -137,6 +247,13 @@ export const SourceSchema = z
     // existing source YAMLs (and `kind: html` ones) parse unchanged; the
     // adapter applies defaults when the field is omitted entirely.
     js: SourceJsOptionsSchema.optional(),
+    // `http` / `pagination` / `jsonSelectors` are consulted only by the
+    // `json-api` adapter (ADR-0012). Marked optional so existing source YAMLs
+    // and other kinds parse unchanged. The `jsonSelectors` name disambiguates
+    // from the css-selector `selectors` field that html / html-js use.
+    http: SourceHttpOptionsSchema.optional(),
+    pagination: SourcePaginationSchema.optional(),
+    jsonSelectors: SourceJsonApiSelectorsSchema.optional(),
     // `trustLevel` defaults to `"untrusted"` so existing source YAMLs (which
     // omit the field entirely) keep their current treatment. Per ADR-0009 M4
     // this is schema-only; policy branches that read `trustLevel` arrive in a
@@ -158,5 +275,18 @@ export const SourceSchema = z
             message: `selectors is required when kind is '${value.kind}'`,
         });
     }
+    if (value.kind === "json-api") {
+        // `jsonSelectors` is now optional — when omitted the adapter relies on
+        // its default selector chain (ADR-0012 §D2 / #174). Most "simple"
+        // page-based APIs work with just `pagination` set; complex shapes
+        // (AWS What's New, nested fields) still need explicit selectors.
+        if (value.pagination === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["pagination"],
+                message: "pagination is required when kind is 'json-api'",
+            });
+        }
+    }
 });
 //# sourceMappingURL=source.js.map

package/dist/schemas/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/schemas/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC;IACrC,KAAK;IACL,MAAM;IACN,SAAS;IACT,iBAAiB;IACjB,cAAc;IACd,WAAW;IACX,UAAU;CACX,CAAC,CAAC;AAGH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAGtE,qGAAqG;AACrG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAG7E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;AAGjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACzC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAChD,SAAS,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;IAC1C,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAC1C,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,kBAAkB,EAAE,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;IACrF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAGH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACtD,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1E;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnC,wFAAwF;IACxF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAClC,wDAAwD;IACxD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAChD,yFAAyF;IACzF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,gFAAgF;IAChF,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5C,mGAAmG;IACnG,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,kGAAkG;IAClG,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CAClD,CAAC,CAAC;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClC;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,gBAAgB;IACtB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACrC,wEAAwE;IACxE,sEAAsE;IACtE,mEAAmE;IACnE,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC;QACnC,QAAQ,EAAE,EAAE;QACZ,eAAe,EAAE,EAAE;QACnB,SAAS,EAAE,MAAM;QACjB,WAAW,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;QACjC,aAAa,EAAE,KAAK;KACrB,CAAC;IACF,wEAAwE;IACxE,sEAAsE;IACtE,0EAA0E;IAC1E,sDAAsD;IACtD,SAAS,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IAC3C,sEAAsE;IACtE,qEAAqE;IACrE,+DAA+D;IAC/D,EAAE,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IACpC,oEAAoE;IACpE,0EAA0E;IAC1E,0EAA0E;IAC1E,mEAAmE;IACnE,IAAI,EAAE,uBAAuB,CAAC,QAAQ,EAAE;IACxC,UAAU,EAAE,sBAAsB,CAAC,QAAQ,EAAE;IAC7C,aAAa,EAAE,4BAA4B,CAAC,QAAQ,EAAE;IACtD,yEAAyE;IACzE,yEAAyE;IACzE,0EAA0E;IAC1E,sBAAsB;IACtB,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,WAAW,CAAC;CAClD,CAAC;KACD,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;IAC1B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,KAAK,CAAC;YACb,OAAO,EAAE,aAAa;SACvB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACzF,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,WAAW,CAAC;YACnB,OAAO,EAAE,uCAAuC,KAAK,CAAC,IAAI,GAAG;SAC9D,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC9B,uEAAuE;QACvE,kEAAkE;QAClE,kEAAkE;QAClE,iEAAiE;QACjE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACnC,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,YAAY,CAAC;gBACpB,OAAO,EAAE,gDAAgD;aAC1D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/templates/agents/AGENTS.md

@@ -48,22 +48,50 @@ radar init --with-actions           # .github/workflows/watch.yaml を生成
 radar init --force                  # 既存ファイルを上書き
 
 # 監視対象の管理
-radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry> --url <url> [options]
+radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry|json-feed|json-api> --url <url> [options]
 radar source list
+radar source recipes                                   # バンドル recipe を一覧表示 (ADR-0012)
+radar source add <id> --recipe <name> [--keywords ... --tags ... --name ...]  # recipe ベースで 1 行追加
 radar source test <id> [--limit N] [--show-content]   # state/items を書き換えず取得 + フィルタを試す
 radar source remove <id>
 
+# JSON API recipe を pagination 付きで追加（ADR-0012）
+radar source add aws-whats-new --kind json-api \
+  --url "https://aws.amazon.com/api/dirs/items/search?item.directoryId=whats-new&size=100&page=0" \
+  --keywords "Bedrock,Claude" \
+  --pagination-strategy page --page-size 100 --max-pages 200
+
+# 同じことを bundled recipe で 1 行で
+radar source add aws-watch --recipe aws-whats-new --keywords "Bedrock,Claude"
+
+# JSON Feed (1.0 / 1.1) は URL のみで動く zero-config
+radar source add example-microblog --kind json-feed \
+  --url https://example.micro.blog/feed.json \
+  --keywords "release"
+
 # 監視実行 (新着検出 → items/*.yaml に detected で書く)
 radar watch run
 
+# 過去全履歴の一括取り込み (kind: json-api / github-releases / npm-registry)
+radar watch run --source aws-whats-new --backfill --max-pages 200
+
 # 検出済み item に対する操作
-radar research <item-id> --agent <agent>     # 調査レポートを生成 (status: detected -> researched)
+radar research <item-id> --agent <agent> [--verbose]   # 調査レポートを生成 (status: detected -> researched)。--verbose で agent stdout を直接見る (ADR-0015)
 radar research --digest <item-id> <item-id> ... [--agent <agent>]  # 複数 item を 1 digest にまとめる (ADR-0011)
+radar research --batch [--max-items N] [--filter-tags <list>] [--agent <agent>]  # detected を一括 research (ADR-0014 D3a、--max-items 既定 10)
 radar review <research-id> --agent <agent>   # 既存レポートをレビュー (status: researched -> reviewed)
 radar update <research-id> --agent <agent>   # v+1 を生成 (item status は変えない)
 radar dismiss <item-id>                       # LLM 不要、item を dismissed に
+
+# GitHub Actions workflow の後追い生成 (ADR-0014)
+radar workflow generate watch [--cron "<expr>"] [--agent <agent>] [--output <path>]
+radar workflow generate combined [--watch-cron "<expr>"] [--max-items N] [--filter-tags <list>] [--agent <agent>] [--output <path>]
 ```
 
+> **自動 research のコスト管理 (重要)**: `radar workflow generate combined` は watch → 自動 research を連鎖する workflow を生成し、`--max-items N` (既定 10) のハードキャップを YAML literal + CLI default の **二重防御**で焼き込む (ADR-0014 D3a)。`--max-items 100` のように大きい値を渡す前に必ず agent provider の billing alert を設定すること。暴走に気付いたら GitHub UI から workflow を `Disable workflow` で即停止する。詳細は `docs/user-guide.md` の「[`radar workflow generate`](https://github.com/ozzy-labs/feedradar/blob/main/docs/user-guide.md#radar-workflow-generate)」を参照。
+>
+> **進捗表示 (ADR-0015)**: `research` / `review` / `update` / `watch run --backfill` / html-js fetch / `source test` は stderr に phase markers + spinner + 副次メトリクス (`stdout` / `output` / `page x/N`) を出力する。`--verbose` で agent stdout を pass-through（デバッグ・「フリーズに見える」時の第一手）、`--quiet` または `RADAR_NO_PROGRESS=1` で完全に黙らせる。詳細は `docs/user-guide.md` の「[進捗表示 / verbose / quiet](https://github.com/ozzy-labs/feedradar/blob/main/docs/user-guide.md#進捗表示--verbose--quiet)」を参照。
+
 `<agent>` の値: `claude-code` / `codex-cli` / `gemini-cli` / `copilot`
 
 ## 利用可能な slash commands (4 agent 共通)
@@ -145,7 +173,7 @@ agent の選択は CLI が強制せず、ユーザー判断です。
 
 ## セキュリティ警告 (untrusted external content)
 
-`radar` が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry) のコンテンツは **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
+`radar` が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry / JSON Feed / JSON API) のコンテンツは **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
 
 - agent に渡すコンテンツは boundary marker で囲まれ、procedure 本体と分離される
 - `sources/<id>.yaml` の `trustLevel` で `"trusted" | "untrusted"` を per-source で指定可能 (既定 `"untrusted"`)

package/dist/templates/feedradar.md

@@ -24,7 +24,7 @@ radar watch run
 # (c) あとは AI エージェントに頼む (次セクション)
 ```
 
-`source add` と `watch run` は scheduler 連携を想定して CLI のままです。`--with-actions` / `--with-routines` を付けて init すれば、GitHub Actions / Claude Routines で定期実行する雛形が出ます。
+`source add` と `watch run` は scheduler 連携を想定して CLI のままです。`--with-actions` / `--with-routines` を付けて init すれば、GitHub Actions / Claude Routines で定期実行する雛形が出ます。後から workflow を追加 / cadence 切替 / watch + 自動 research の連鎖が必要になったら `radar workflow generate watch | combined` で後追い生成できます ([ADR-0014](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0014-workflow-generate-and-auto-research-safety.md))。
 
 ## 主要操作: エージェントに頼む
 
@@ -111,19 +111,34 @@ slash で直接呼ぶなら:
 エージェントを起動しない自動化文脈では CLI を直接呼びます。`radar <subcommand> --help` で全コマンドのヘルプが出ます。
 
 ```bash
-radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry> --url <url> [options]
+radar source add <id> --kind <rss|html|html-js|github-releases|npm-registry|json-feed|json-api> --url <url> [options]
+radar source add <id> --recipe <name> [--keywords ... --tags ... --name ...]  # バンドル recipe で 1 行追加 (ADR-0012)
 radar source list
+radar source recipes                                  # バンドル recipe を一覧表示
 radar source test <id> [--limit N] [--show-content]
 radar source remove <id>
-radar watch run [--source <id>] [--bootstrap]
-radar research <item-id> --agent <agent>
+radar watch run [--source <id>] [--bootstrap | --backfill [--max-pages N]] [-v|--verbose | -q|--quiet]
+radar research <item-id> --agent <agent> [--verbose | --quiet]    # 進捗表示・stdout pass-through は --verbose で有効化 (ADR-0015)
 radar research --digest <item-id> <item-id> ... [--agent <agent>]   # 複数 item を 1 digest にまとめる (ADR-0011)
-radar review <research-id> --agent <agent>
-radar update <research-id> --agent <agent>
+radar review <research-id> --agent <agent> [--verbose | --quiet]
+radar update <research-id> --agent <agent> [--verbose | --quiet]
 radar dismiss <item-id>
+radar research --batch [--max-items N] [--filter-tags <list>] [--agent <agent>] [--verbose | --quiet]  # detected を一括 research (ADR-0014)
+radar workflow generate watch [--cron "<expr>"] [--agent <agent>] [--output <path>]            # GitHub Actions watch 雛形を後追い生成 (ADR-0014)
+radar workflow generate combined [--watch-cron "<expr>"] [--max-items N] [--filter-tags <list>] [--agent <agent>] [--output <path>]   # watch + 自動 research を --max-items ハードキャップ付きで生成 (ADR-0014)
 ```
 
-定期実行の雛形 (GitHub Actions / Claude Routines) は `radar init --with-actions` / `--with-routines` で生成できます。
+JSON API は recipe ベースで、`kind: json-api` を選んで `pagination` を YAML に書く（[ADR-0012](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0012-json-api-adapter-and-recipe-strategy.md)）。JSON Feed 1.0 / 1.1 標準に準拠したサイトは URL だけで動く zero-config kind (`kind: json-feed`)。過去の全件取り込みは `radar watch run --backfill` を使う (kind: json-api / github-releases / npm-registry 対応)。
+
+長時間実行コマンド (`research` / `review` / `update` / `watch run --backfill` / html-js fetch / `source test`) は stderr に phase markers + spinner + 副次メトリクス (`stdout` / `output` / `page x/N`) を表示します（[ADR-0015](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0015-progress-reporting-ux.md)）。挙動切替は env > flag > TTY auto-detect の優先順:
+
+- `--verbose`（または `-v`）: agent CLI / Playwright の stdout/stderr を pass-through。デバッグや「フリーズに見える」ときの第一手
+- `--quiet`（または `-q`）: reporter を完全に黙らせ、CLI の従来 1 行ログだけ残す
+- `RADAR_NO_PROGRESS=1`（env）: 上記より強い escape hatch。CI script で flag を消さずに reporter だけ off にしたいケース向け
+
+詳細・トラブルシュート（`Agent running [mm:ss]` で動いていないように見える時の対処等）は [docs/user-guide.md → 進捗表示 / verbose / quiet](https://github.com/ozzy-labs/feedradar/blob/main/docs/user-guide.md#進捗表示--verbose--quiet) を参照。
+
+定期実行の雛形 (GitHub Actions / Claude Routines) は `radar init --with-actions` / `--with-routines` で初回 bootstrap として生成できます。後追いで cadence 切替 / 複数 workflow 共存 / `combined` (watch + 自動 research) を追加したい場合は `radar workflow generate <type>` ([ADR-0014](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0014-workflow-generate-and-auto-research-safety.md)) を使います。`combined` は `--max-items` ハードキャップを YAML literal + CLI default の二重防御で焼き込むため、暴走 feed (publisher 側 bug / `--backfill` 事故) による LLM cost 爆発を設計レベルで遮断します。
 
 ## このディレクトリのレイアウト
 
@@ -154,7 +169,7 @@ radar dismiss <item-id>
 
 ## セキュリティ警告
 
-FeedRadar が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry) は **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
+FeedRadar が fetch する外部 feed (RSS / HTML / HTML (JS rendered, `kind: html-js`) / GitHub Releases / npm registry / JSON Feed / JSON API) は **untrusted** として扱われます ([ADR-0009](https://github.com/ozzy-labs/feedradar/blob/main/docs/adr/0009-untrusted-external-content-handling.md))。攻撃者が feed 内容に prompt injection を仕込む可能性があるため:
 
 - 信頼できる公式 source のみ登録するのが第一の防御線
 - `sources/<id>.yaml` の `trustLevel: trusted` で個別 opt-in 可 (既定 `untrusted`)

package/dist/templates/workflows/combined.template.yaml.tmpl

@@ -0,0 +1,110 @@
+# `radar workflow generate combined` template (ADR-0014 D2 / D3 / D4 / D5).
+#
+# Chains `radar watch run` -> "skip if no new items" guard -> `radar research
+# --batch` -> `git commit/push --rebase` retry inside a single job so the
+# detection-to-research delay collapses to one cron tick instead of two
+# stacked workflows.
+#
+# Placeholders rendered by `src/cli/workflow/generate-combined.ts`:
+#   {{cron}}        — schedule cron expression (default "0 0 * * *")
+#   {{maxItems}}    — `--max-items` hard cap (ADR-0014 D3a; default 10)
+#   {{filterTags}}  — `--filter-tags` arg as a single CLI literal (empty when
+#                     filtering is off so the line collapses to bare `--batch`)
+#   {{agent}}       — agent id literal (claude-code|codex-cli|gemini-cli|copilot)
+#   {{secretsBlock}} — agent-specific `env:` body (no shared default; the
+#                     CLI generator selects one of four prebuilt fragments,
+#                     never injecting OAuth tokens per ADR-0014 D5)
+#
+# Hard-cap rationale: this YAML embeds `--max-items {{maxItems}}` as a literal
+# so a workflow audit shows the cap without needing to re-read CLI source.
+# The CLI re-enforces the cap (`RESEARCH_BATCH_DEFAULT_MAX_ITEMS` in
+# `src/cli/research.ts`) so even hand-edited YAML cannot blow it inside one
+# invocation (ADR-0014 D3a 二重防御).
+
+name: feedradar-combined
+
+on:
+  schedule:
+    - cron: "{{cron}}"
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+concurrency:
+  # Type-scoped concurrency group: watch-only and combined workflows must not
+  # serialize each other (different cadence, different scope), so each type
+  # has its own `feedradar-<type>-${{ github.ref }}` group.
+  group: feedradar-combined-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  combined:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout workspace
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.21"
+
+      - name: Install FeedRadar
+        run: npm install -g @ozzylabs/feedradar
+
+      - name: Run watch
+        env:
+{{secretsBlock}}
+        run: radar watch run
+
+      - name: Skip research when no new items
+        id: detect_changes
+        # ADR-0014: skip the research step entirely when `watch run` produced
+        # no new items. Otherwise a runaway-detection cap would still burn a
+        # full `radar research --batch` invocation (template load, item walk)
+        # on a fresh-empty queue.
+        run: |
+          if [ -z "$(git status --porcelain items/)" ]; then
+            echo "no new items in items/; skipping research step"
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changes=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run research on detected items (capped at {{maxItems}}, agent={{agent}})
+        if: steps.detect_changes.outputs.has_changes == 'true'
+        env:
+{{secretsBlock}}
+        # `--batch` walks items/ for status=detected, applies the filter-tags
+        # allow-list, and stops once `--max-items` reports are written. The CLI
+        # re-enforces the cap so a hand-edited YAML cannot exceed it.
+        run: radar research --batch --status detected --max-items {{maxItems}}{{filterTags}} --agent {{agent}}
+
+      - name: Commit and push with retry
+        if: steps.detect_changes.outputs.has_changes == 'true'
+        # ADR-0014 D4: three-attempt push with `git pull --rebase --autostash`
+        # between failures. Tuned for two concurrent feedradar workflows (e.g.
+        # watch-hourly + combined-weekly) racing on items/ / state/ / research/.
+        run: |
+          git config user.name "feedradar-bot"
+          git config user.email "feedradar-bot@users.noreply.github.com"
+          git add items/ state/ research/
+          if git diff --cached --quiet; then
+            echo "nothing staged; exiting cleanly"
+            exit 0
+          fi
+          git commit -m "chore(feedradar): combined watch + research $(date -u +%Y-%m-%d)"
+          for attempt in 1 2 3; do
+            if git push origin "${GITHUB_REF_NAME}"; then
+              exit 0
+            fi
+            echo "push failed (attempt ${attempt}/3), rebasing..."
+            git pull --rebase --autostash origin "${GITHUB_REF_NAME}"
+          done
+          echo "push failed after 3 attempts" >&2
+          exit 1

package/dist/templates/workflows/watch.template.yaml.tmpl

@@ -0,0 +1,103 @@
+# GitHub Actions scaffold generated by `radar workflow generate watch`.
+# Edit the cron schedule, sources, and commit message to match your workflow.
+# Auth policy: API key only (ADR-0004 / ADR-0014). The Claude Code OAuth token
+# is forbidden for unattended workflows per Anthropic's usage policy.
+#
+# This template is the placeholder-driven, post-init regeneration variant of
+# `src/templates/workflows/watch.yaml`. The latter is emitted by
+# `radar init --with-actions` for first-time workspace bootstrap and is
+# preserved verbatim for backward compatibility (ADR-0014 D1). Differences:
+#
+#   - Cron schedule, output path, and agent secret name are substituted by
+#     `generate-watch.ts` from CLI flags before the file is written.
+#   - `concurrency.group` is scoped to `feedradar-watch-` so multiple workflow
+#     types (watch / combined) can run side by side without cancelling each
+#     other; ADR-0014 D4 push-conflict mitigation pairs with the rebase retry
+#     below.
+#   - `Commit and push with retry` step has up to 3 `git pull --rebase`
+#     retries to recover from concurrent cron pushes (ADR-0014 D4).
+
+name: feedradar-watch
+
+on:
+  schedule:
+    - cron: "{{cron}}"
+  workflow_dispatch: {}
+
+permissions:
+  # Required to commit detected items / state back to the workspace branch.
+  contents: write
+
+concurrency:
+  # Per-type group so `watch` and `combined` workflows don't cancel each other.
+  # Same-type concurrent firings still serialize via this group.
+  group: feedradar-watch-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  watch:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout workspace
+        uses: actions/checkout@v4
+        with:
+          # Need history so we can rebase on top of concurrent pushes.
+          fetch-depth: 0
+          persist-credentials: true
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          # Node 22.21+ (or 24.5+) is required so radar can auto-detect
+          # HTTPS_PROXY / HTTP_PROXY and respawn with --use-env-proxy.
+          node-version: "22.21"
+
+      - name: Install FeedRadar
+        # Pin to a release once you've decided on a version; this scaffold
+        # installs the latest published build.
+        run: npm install -g @ozzylabs/feedradar
+
+      - name: Run watch
+        env:
+          # Authenticate against the agent API per ADR-0004 / ADR-0014 D5.
+          # The secret name below follows the per-agent convention; see the
+          # post-generation stdout for the exact secret you must add.
+          {{agentEnvKey}}: ${{ secrets.{{agentEnvKey}} }}
+          # Raises GitHub REST API rate limit from 60 → 5000 req/h for the
+          # github-releases adapter (ADR-0002 / Phase 3).
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: radar watch run
+
+      - name: Commit and push with retry
+        # Persist updates to items/ and state/ so the next scheduled run can
+        # diff against the previous lastSeenIds. Routines / Actions both
+        # fresh-clone, so state must live in git.
+        #
+        # Push conflict mitigation (ADR-0014 D4): if another workflow (e.g.
+        # combined.yaml) pushed concurrently, `git push` fails with
+        # non-fast-forward. We retry up to 3 times, rebasing on each attempt;
+        # autostash keeps any unindexed bot-side changes safe across the
+        # rebase. 4+ attempts indicate a structural problem (branch
+        # protection, token failure, true merge conflict) so we fail fast
+        # instead of retrying further.
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet items/ state/; then
+            echo "no changes detected; skipping commit"
+            exit 0
+          fi
+          git add items/ state/
+          git commit -m "chore(watch): detected items $(date -u +%Y-%m-%d)"
+          for attempt in 1 2 3; do
+            if git push origin "${GITHUB_REF_NAME}"; then
+              echo "push succeeded on attempt ${attempt}"
+              exit 0
+            fi
+            echo "push failed (attempt ${attempt}/3), rebasing..."
+            git pull --rebase --autostash origin "${GITHUB_REF_NAME}"
+          done
+          echo "push failed after 3 attempts" >&2
+          exit 1

package/dist/templates/workflows/watch.yaml

@@ -36,7 +36,11 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          # Node 22.21+ (or 24.5+) is required so radar can auto-detect
+          # HTTPS_PROXY / HTTP_PROXY and respawn with --use-env-proxy.
+          # Older 22.x lacks the flag and `radar` runs without proxy
+          # support even when HTTPS_PROXY is set.
+          node-version: "22.21"
 
       - name: Install FeedRadar
         # Pin to a release once you've decided on a version; this scaffold

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozzylabs/feedradar",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Multi-agent CLI that watches blogs and release feeds, then turns keyword hits into Markdown research reports",
   "type": "module",
   "publishConfig": {
@@ -8,7 +8,6 @@
   },
   "files": [
     "dist",
-    "dist/skills",
     "LICENSE",
     "README.md"
   ],
@@ -78,6 +77,6 @@
   ],
   "author": "ozzy-labs",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.21.0 || >=24.5.0"
   }
 }