@ozzylabs/feedradar 0.1.3 → 0.1.5

package/dist/core/recipes.d.ts

@@ -0,0 +1,138 @@
+import { type RecipeFile } from "../schemas/recipe.js";
+/**
+ * Recipe loader and CLI-args merger for `radar source recipes` /
+ * `radar source add --recipe <name>` (ADR-0012 §D3, strategy A — リポ同梱).
+ *
+ * Design notes:
+ *
+ * - Recipes live in `recipes/*.yaml` at the package root and are bundled
+ *   into npm publish via the package.json `files` allowlist plus a copy
+ *   step in `scripts/copy-skills.mjs` (`recipes/` → `dist/recipes/`). The
+ *   resolver tries the compiled location first, then falls back to the
+ *   source tree (used by the test suite and `pnpm test` runs that have
+ *   not built `dist/` yet).
+ *
+ * - The directory is allowed to be empty (#178 adds the actual bundled
+ *   recipes). When the directory is missing entirely the loader behaves
+ *   the same as "no recipes" — the bundle is optional at the schema
+ *   level. The CLI surfaces a friendly "no recipes" message instead of
+ *   an error in that case.
+ *
+ * - Each recipe is independently parse-and-validate so one malformed
+ *   YAML does not prevent the rest from being listed. `listRecipes`
+ *   returns per-recipe `error` strings; `loadRecipe(name)` throws so
+ *   `--recipe <name>` can hard-fail at `source add` time.
+ *
+ * - The recipe's identifier ( `--recipe <name>` match key) is the YAML
+ *   filename stem. There is no inner "name" field that doubles as the
+ *   match key — recipe authors rename the file to rename the recipe.
+ *   `RecipeFile.name` is the *display name* (mirrors `Source.name`).
+ */
+/** A recipe loaded from disk, paired with its filename-derived identifier. */
+export interface LoadedRecipe {
+    /** Filename stem (e.g. `aws-whats-new` for `aws-whats-new.yaml`). */
+    name: string;
+    /** Absolute path of the recipe YAML, useful for error messages. */
+    path: string;
+    recipe: RecipeFile;
+}
+/** Entry returned by `listRecipes`, including malformed recipes (with `error`). */
+export interface RecipeListEntry {
+    name: string;
+    path: string;
+    /** Parsed recipe, or `null` when this entry failed to load (see `error`). */
+    recipe: RecipeFile | null;
+    /** Human-readable error string when the entry could not be loaded. */
+    error?: string;
+}
+/** Options for the loader/lister to override the recipes directory (used by tests). */
+export interface RecipeLoaderOptions {
+    recipesRoot?: string;
+}
+/**
+ * Resolve the directory holding the bundled recipes.
+ *
+ * Compiled layout (npm install): `dist/core/recipes.js` → `../recipes`.
+ * Source layout (tests / `pnpm test`): `src/core/recipes.ts` → `../../recipes`.
+ *
+ * We probe the compiled location first because that is the path users
+ * hit at runtime. Both paths can be present during local development
+ * (after `pnpm run build`); preferring compiled keeps the source tree
+ * from being the active asset directory by accident.
+ */
+export declare function resolveRecipesRoot(): Promise<string>;
+/**
+ * List all bundled recipes by reading every `*.yaml` file in the recipes
+ * directory.
+ *
+ * Behaviour:
+ *
+ * - Missing recipes directory → returns `[]` (treated as "no recipes",
+ *   not an error). This matches the bootstrap state where #178 has not
+ *   yet shipped the actual recipe files.
+ * - Each `.yaml` is independently parsed and Zod-validated. Failures are
+ *   captured in the per-entry `error` field so partial corruption never
+ *   prevents the rest from rendering.
+ * - Entries are sorted by `name` for deterministic output (tests rely on
+ *   this; users get a stable display order).
+ */
+export declare function listRecipes(opts?: RecipeLoaderOptions): Promise<RecipeListEntry[]>;
+/**
+ * Load a single recipe by its filename stem (e.g. `aws-whats-new`).
+ *
+ * Throws on:
+ *
+ * - missing recipes directory (the bundle is absent)
+ * - unknown recipe name (the file does not exist)
+ * - malformed YAML or Zod-schema violation
+ *
+ * The error messages are user-facing — `source add --recipe` surfaces
+ * them via the CLI `error()` sink without further wrapping.
+ */
+export declare function loadRecipe(name: string, opts?: RecipeLoaderOptions): Promise<LoadedRecipe>;
+/**
+ * CLI overrides applied on top of a recipe when generating a Source.
+ *
+ * The whitelist is intentionally narrow:
+ *
+ * - `id` (required) — recipes never carry an `id`; the caller picks one
+ *   per workspace
+ * - `name` (display name) — useful when a single recipe is applied
+ *   multiple times to differentiate, or to localize
+ * - `tags` — workspace-level taxonomy that varies per install
+ * - `filters.keywords` / `filters.excludeKeywords` — the only fields a
+ *   user is reliably expected to override; "what counts as a hit" is
+ *   per-workspace
+ *
+ * Other fields (`pagination`, `jsonSelectors`, `selectors`, `js`,
+ * `http`, `url`, `kind`, `trustLevel`) are NOT overridable from the
+ * CLI. Recipe authors own these "structural" fields. Users edit the
+ * generated `sources/<id>.yaml` if they need to deviate further.
+ */
+export interface RecipeOverrides {
+    /** Required — the source id chosen by the caller. */
+    id: string;
+    /** Optional override for `Source.name` (display name). */
+    name?: string;
+    /** Optional override for `Source.tags` (replaces, does not merge). */
+    tags?: string[];
+    /** Optional override for `filters.keywords` (replaces, does not merge). */
+    keywords?: string[];
+    /** Optional override for `filters.excludeKeywords` (replaces, does not merge). */
+    excludeKeywords?: string[];
+}
+/**
+ * Merge a recipe with CLI overrides to produce a plain object suitable
+ * for `SourceSchema.safeParse`.
+ *
+ * Override semantics: each field is *replaced* (not merged) when the
+ * override is present. This mirrors `source add` flag semantics
+ * (`--keywords a,b` replaces, never appends) and keeps the mental model
+ * uniform across `add` and `add --recipe`.
+ *
+ * `description` from the recipe is dropped — it is recipe metadata,
+ * not Source metadata. Strip it explicitly so the generated YAML does
+ * not carry a stray field that fails downstream schema validation.
+ */
+export declare function mergeRecipeWithOverrides(recipe: RecipeFile, overrides: RecipeOverrides): Record<string, unknown>;
+//# sourceMappingURL=recipes.d.ts.map

package/dist/core/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../../src/core/recipes.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,sBAAsB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS1D;AAWD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CA8D5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAyDvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,eAAe,GACzB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+CzB"}

package/dist/core/recipes.js

@@ -0,0 +1,238 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { RecipeFileSchema } from "../schemas/recipe.js";
+/**
+ * Resolve the directory holding the bundled recipes.
+ *
+ * Compiled layout (npm install): `dist/core/recipes.js` → `../recipes`.
+ * Source layout (tests / `pnpm test`): `src/core/recipes.ts` → `../../recipes`.
+ *
+ * We probe the compiled location first because that is the path users
+ * hit at runtime. Both paths can be present during local development
+ * (after `pnpm run build`); preferring compiled keeps the source tree
+ * from being the active asset directory by accident.
+ */
+export async function resolveRecipesRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const compiled = resolve(here, "../recipes");
+    if (await pathExists(compiled)) {
+        return compiled;
+    }
+    // Source layout fallback. We walk two levels up from src/core/ to find
+    // the package root, then descend into `recipes/`.
+    return resolve(here, "../../recipes");
+}
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * List all bundled recipes by reading every `*.yaml` file in the recipes
+ * directory.
+ *
+ * Behaviour:
+ *
+ * - Missing recipes directory → returns `[]` (treated as "no recipes",
+ *   not an error). This matches the bootstrap state where #178 has not
+ *   yet shipped the actual recipe files.
+ * - Each `.yaml` is independently parsed and Zod-validated. Failures are
+ *   captured in the per-entry `error` field so partial corruption never
+ *   prevents the rest from rendering.
+ * - Entries are sorted by `name` for deterministic output (tests rely on
+ *   this; users get a stable display order).
+ */
+export async function listRecipes(opts = {}) {
+    const root = opts.recipesRoot ?? (await resolveRecipesRoot());
+    if (!(await pathExists(root))) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    // `.gitkeep` (or any other dotfile) must not be picked up as a recipe;
+    // the `*.yaml` glob is enforced by suffix rather than a separate
+    // exclude list.
+    const yamlFiles = entries.filter((f) => f.endsWith(".yaml")).sort();
+    const results = [];
+    for (const filename of yamlFiles) {
+        const path = join(root, filename);
+        const name = filename.slice(0, -".yaml".length);
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (e) {
+            results.push({
+                name,
+                path,
+                recipe: null,
+                error: `failed to read: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseYaml(raw);
+        }
+        catch (e) {
+            results.push({
+                name,
+                path,
+                recipe: null,
+                error: `invalid YAML: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            continue;
+        }
+        const result = RecipeFileSchema.safeParse(parsed);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+                .join("; ");
+            results.push({
+                name,
+                path,
+                recipe: null,
+                error: `schema validation failed: ${issues}`,
+            });
+            continue;
+        }
+        results.push({ name, path, recipe: result.data });
+    }
+    return results;
+}
+/**
+ * Load a single recipe by its filename stem (e.g. `aws-whats-new`).
+ *
+ * Throws on:
+ *
+ * - missing recipes directory (the bundle is absent)
+ * - unknown recipe name (the file does not exist)
+ * - malformed YAML or Zod-schema violation
+ *
+ * The error messages are user-facing — `source add --recipe` surfaces
+ * them via the CLI `error()` sink without further wrapping.
+ */
+export async function loadRecipe(name, opts = {}) {
+    // Reject path-separator / traversal characters defensively. `--recipe`
+    // is positional CLI input and could be copied from arbitrary sources;
+    // the same posture as `isSafeSourceId` keeps the lookup confined to
+    // the recipes directory.
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes("..")) {
+        throw new Error(`invalid recipe name '${name}' (must match [A-Za-z0-9][A-Za-z0-9._-]*)`);
+    }
+    const root = opts.recipesRoot ?? (await resolveRecipesRoot());
+    if (!(await pathExists(root))) {
+        throw new Error(`no bundled recipes available (recipes/ not found at ${root}); recipe '${name}' cannot be resolved`);
+    }
+    const path = join(root, `${name}.yaml`);
+    if (!(await pathExists(path))) {
+        // Surface available names so the user can self-correct without having
+        // to run a second command. List failures are swallowed here (best
+        // effort) so the primary error message is the one the user sees.
+        let available = [];
+        try {
+            const all = await listRecipes({ recipesRoot: root });
+            available = all.map((r) => r.name);
+        }
+        catch {
+            // ignore — we already have the primary error to report
+        }
+        const hint = available.length === 0 ? "" : ` (available: ${available.join(", ")})`;
+        throw new Error(`recipe '${name}' not found${hint}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (e) {
+        throw new Error(`failed to read recipe '${name}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (e) {
+        throw new Error(`invalid YAML in recipe '${name}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const result = RecipeFileSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
+            .join("; ");
+        throw new Error(`recipe '${name}' failed schema validation: ${issues}`);
+    }
+    return { name, path, recipe: result.data };
+}
+/**
+ * Merge a recipe with CLI overrides to produce a plain object suitable
+ * for `SourceSchema.safeParse`.
+ *
+ * Override semantics: each field is *replaced* (not merged) when the
+ * override is present. This mirrors `source add` flag semantics
+ * (`--keywords a,b` replaces, never appends) and keeps the mental model
+ * uniform across `add` and `add --recipe`.
+ *
+ * `description` from the recipe is dropped — it is recipe metadata,
+ * not Source metadata. Strip it explicitly so the generated YAML does
+ * not carry a stray field that fails downstream schema validation.
+ */
+export function mergeRecipeWithOverrides(recipe, overrides) {
+    // Build the candidate as a fresh object so the recipe object on disk
+    // is not mutated and we get control over field ordering in the output
+    // YAML (id first → kind → url → ...).
+    const candidate = {
+        id: overrides.id,
+        kind: recipe.kind,
+        url: recipe.url,
+    };
+    // Display name: caller override wins, then recipe.name, then nothing.
+    if (overrides.name !== undefined) {
+        candidate.name = overrides.name;
+    }
+    else if (recipe.name !== undefined) {
+        candidate.name = recipe.name;
+    }
+    // Tags: override replaces; otherwise inherit recipe tags (which defaults
+    // to []). Emit only when non-empty so the YAML stays minimal for the
+    // common case "no tags in either place".
+    const tags = overrides.tags ?? recipe.tags;
+    if (tags.length > 0) {
+        candidate.tags = tags;
+    }
+    // Filters: override the include/exclude keyword arrays; preserve the
+    // recipe's other filter knobs (matchMode / matchFields / caseSensitive)
+    // because those reflect adapter-specific tuning that the recipe author
+    // already picked.
+    const mergedFilters = {
+        ...recipe.filters,
+        keywords: overrides.keywords ?? recipe.filters.keywords,
+        excludeKeywords: overrides.excludeKeywords ?? recipe.filters.excludeKeywords,
+    };
+    candidate.filters = mergedFilters;
+    // Structural fields that the recipe owns. Drop undefined entries to
+    // keep the generated YAML free of explicit nulls.
+    if (recipe.selectors !== undefined)
+        candidate.selectors = recipe.selectors;
+    if (recipe.js !== undefined)
+        candidate.js = recipe.js;
+    if (recipe.http !== undefined)
+        candidate.http = recipe.http;
+    if (recipe.pagination !== undefined)
+        candidate.pagination = recipe.pagination;
+    if (recipe.jsonSelectors !== undefined)
+        candidate.jsonSelectors = recipe.jsonSelectors;
+    candidate.trustLevel = recipe.trustLevel;
+    return candidate;
+}
+//# sourceMappingURL=recipes.js.map

package/dist/core/recipes.js.map

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

package/dist/core/watcher.d.ts

@@ -1,6 +1,7 @@
 import type { Item, Source, SourceState } from "../schemas/index.js";
-import type { FeedAdapter, FetchLike } from "./feeds/index.js";
+import type { FeedAdapter, FeedFetchDiag, FetchLike } from "./feeds/index.js";
 import { installChromium, type ProbeOptions } from "./playwright-check.js";
+import type { ProgressReporter } from "./progress.js";
 export interface WorkspacePaths {
     /** Workspace root; defaults to process.cwd() at the CLI layer. */
     cwd: string;
@@ -17,6 +18,20 @@ export interface WatchRunOptions extends WorkspacePaths {
      * backlogs (ADR-0008 §運用: 初回ノイズ抑制).
      */
     bootstrap?: boolean;
+    /**
+     * Backfill mode (ADR-0012 §D4): walk paginated sources to ingest all
+     * available history into items/. Emits items AND updates state, unlike
+     * `bootstrap` which only updates state. Mutually exclusive with
+     * `bootstrap`; the CLI layer enforces the exclusivity, the watcher accepts
+     * whichever flag was passed.
+     */
+    backfill?: boolean;
+    /**
+     * Override the per-source `pagination.maxPages` cap. Threaded straight
+     * through to adapters that paginate (json-api / github-releases /
+     * npm-registry). Only honored when `backfill` is true.
+     */
+    maxPagesOverride?: number;
     /**
      * Dry-run mode: run the full fetch + filter pipeline but do not persist
      * anything to disk — neither item YAMLs under `items/` nor the updated
@@ -52,6 +67,17 @@ export interface WatchRunOptions extends WorkspacePaths {
      * records invocation without actually spawning `npx playwright install`.
      */
     installChromiumImpl?: typeof installChromium;
+    /**
+     * Optional progress reporter for per-source fetch phases (#198 /
+     * ADR-0015). The watcher gates wiring on a heuristic
+     * ({@link shouldEnableProgress}) so the typical small / fast workspace
+     * never sees flicker: progress is enabled only when at least 3 sources
+     * run together OR any source uses a slow kind (`html-js` / `json-api`).
+     *
+     * When the reporter is unset (or the heuristic is off) every source runs
+     * with no progress wiring — byte-equivalent to the pre-#198 behaviour.
+     */
+    progress?: ProgressReporter;
 }
 export interface WatchRunResult {
     /** Map of sourceId → detected (filter-passing, not previously seen) items. */
@@ -78,6 +104,17 @@ export interface WatchRunResult {
         fetched: number;
         filtered: number;
     }>;
+    /**
+     * Per-source diagnostic payload returned by adapters that produce one
+     * (currently only `kind: json-api` — see `FeedFetchDiag`). Populated for
+     * every source whose fetch returned a `diag` field; missing entries are
+     * legal and indicate the adapter does not surface diagnostics.
+     *
+     * Consumers (`radar source test --show-content`) render this alongside
+     * the matched-items preview so users can audit which default selector
+     * chain candidate was adopted and how pagination would advance.
+     */
+    diag: Record<string, FeedFetchDiag>;
 }
 /**
  * Load all enabled sources from `sources/*.yaml`.
@@ -87,6 +124,29 @@ export interface WatchRunResult {
  * behaves (see `src/cli/source.ts`).
  */
 export declare function loadSources(sourcesDir: string, onError: (message: string) => void): Promise<Source[]>;
+/**
+ * Heuristic: should the watcher actively report per-source progress to the
+ * supplied {@link ProgressReporter}?
+ *
+ * The typical small workspace (1-2 RSS sources, ~3 seconds end-to-end)
+ * gains nothing from a spinner that flashes in and out faster than the eye
+ * can track. We therefore enable progress only when:
+ *
+ * 1. There are 3 or more sources to fetch in this run — at that scale the
+ *    user wants per-source orientation as the loop iterates, OR
+ * 2. Any source uses a slow kind — `html-js` (Playwright launch + render =
+ *    seconds-to-tens-of-seconds) or `json-api` in `--backfill` mode
+ *    (~80 page traversal). Even a single one of these makes the per-source
+ *    indicator worth the noise.
+ *
+ * The heuristic is intentionally NOT user-configurable (ADR-0015 D5 /
+ * issue #198 note). `--quiet` / `RADAR_NO_PROGRESS=1` are the documented
+ * escape hatches when even the heuristic-on output is undesirable.
+ *
+ * Exported so the watcher / CLI can share one definition; tests pin
+ * behaviour against this single source of truth.
+ */
+export declare function shouldEnableProgress(sources: Source[], backfill: boolean): boolean;
 /**
  * Execute one full watch cycle.
  *

package/dist/core/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/core/watcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK/D,OAAO,EAEL,eAAe,EAGf,KAAK,YAAY,EAElB,MAAM,uBAAuB,CAAC;AA2C/B,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC;IACnD,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,YAAY,CAAC;IACtC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,eAAe,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACjC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,6EAA6E;IAC7E,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAWD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAoMhF;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAQ9D"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/core/watcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK9E,OAAO,EAEL,eAAe,EAGf,KAAK,YAAY,EAElB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AA2CtD,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC;IACnD,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,YAAY,CAAC;IACtC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,eAAe,CAAC;IAC7C;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACjC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,6EAA6E;IAC7E,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD;;;;;;;;;;OAUG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACrC;AAWD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAOlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA0QhF;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAQ9D"}

package/dist/core/watcher.js

@@ -97,6 +97,39 @@ export async function loadSources(sourcesDir, onError) {
     }
     return sources;
 }
+/**
+ * Heuristic: should the watcher actively report per-source progress to the
+ * supplied {@link ProgressReporter}?
+ *
+ * The typical small workspace (1-2 RSS sources, ~3 seconds end-to-end)
+ * gains nothing from a spinner that flashes in and out faster than the eye
+ * can track. We therefore enable progress only when:
+ *
+ * 1. There are 3 or more sources to fetch in this run — at that scale the
+ *    user wants per-source orientation as the loop iterates, OR
+ * 2. Any source uses a slow kind — `html-js` (Playwright launch + render =
+ *    seconds-to-tens-of-seconds) or `json-api` in `--backfill` mode
+ *    (~80 page traversal). Even a single one of these makes the per-source
+ *    indicator worth the noise.
+ *
+ * The heuristic is intentionally NOT user-configurable (ADR-0015 D5 /
+ * issue #198 note). `--quiet` / `RADAR_NO_PROGRESS=1` are the documented
+ * escape hatches when even the heuristic-on output is undesirable.
+ *
+ * Exported so the watcher / CLI can share one definition; tests pin
+ * behaviour against this single source of truth.
+ */
+export function shouldEnableProgress(sources, backfill) {
+    if (sources.length >= 3)
+        return true;
+    for (const s of sources) {
+        if (s.kind === "html-js")
+            return true;
+        if (s.kind === "json-api" && backfill)
+            return true;
+    }
+    return false;
+}
 /**
  * Execute one full watch cycle.
  *
@@ -130,9 +163,22 @@ export async function watchRun(options) {
         else {
             log("watch run: no sources defined (use `radar source add ...`)");
         }
-        return { detected: {}, states: {}, errors: [], stats: {} };
+        return { detected: {}, states: {}, errors: [], stats: {}, diag: {} };
     }
-    const result = { detected: {}, states: {}, errors: [], stats: {} };
+    const result = {
+        detected: {},
+        states: {},
+        errors: [],
+        stats: {},
+        diag: {},
+    };
+    // Heuristic gate: only wire the reporter when the run is worth narrating.
+    // Without this guard, `radar watch run` on a 1-source RSS workspace would
+    // spam the spinner for ~3 seconds straight with no informational value.
+    // `options.progress` being unset already means no output regardless.
+    const progress = options.progress && shouldEnableProgress(filtered, options.backfill === true)
+        ? options.progress
+        : undefined;
     // Lazy Playwright probe cache. We only run the probe when the first
     // `html-js` source comes up so RSS / GitHub / npm-only workspaces never pay
     // for the dynamic import. The result is reused across every subsequent
@@ -204,17 +250,58 @@ export async function watchRun(options) {
         let fetched;
         let nextStatePatch;
         let notModified = false;
+        // Per-source phase markers (#198). `Fetching…` is the start-of-source
+        // boundary the user sees in the spinner; the adapter may emit its own
+        // sub-phases (html-js Chromium lifecycle, json-api page x/n) between
+        // here and `Completed`. Side metrics for the spinner row default to
+        // the source kind so even non-paginating adapters surface useful info.
+        progress?.phase(`[${source.id}] Fetching…`, `kind: ${source.kind}`);
+        progress?.start(`[${source.id}] ${source.kind}`);
+        const sourceStartedAt = Date.now();
         try {
             const fetchResult = await adapter.fetch(source, {
                 fetch: options.fetch,
                 state: previousState,
+                backfill: options.backfill,
+                maxPagesOverride: options.maxPagesOverride,
+                env: options.env,
+                // In dry-run mode (`radar source test`), paginating adapters fetch
+                // only page 0 so the preview never walks past the recipe's first
+                // window. Non-paginating adapters ignore the flag.
+                dryRun: options.dryRun,
+                // Surface adapter-level non-fatal hints (default-selector misses on
+                // json-api, etc.) through the same warn sink we use for
+                // schema-mismatch / playwright-skip messages.
+                warn: (m) => warn(`watch run: ${m}`),
+                // Forward the source-scoped reporter so adapter phases nest under
+                // the parent `[<source-id>] …` marker. html-js uses it for the
+                // Chromium lifecycle; other kinds currently ignore it.
+                onProgress: progress,
+                // Per-page hook for paginating adapters (json-api). We translate
+                // each page event into a phase marker so non-TTY logs preserve the
+                // narrative ("Page 3/80: 100 items") and TTY rows pick up the
+                // metric on the spinner.
+                onPage: progress
+                    ? ({ pageIndex, pageTotal, items: pageItems }) => {
+                        const human = `Page ${pageIndex + 1}/${pageTotal}: ${pageItems} items fetched`;
+                        progress.phase(`[${source.id}] ${human}`);
+                        progress.update({
+                            page: `${pageIndex + 1}/${pageTotal}`,
+                            items: String(pageItems),
+                        });
+                    }
+                    : undefined,
             });
             fetched = fetchResult.items;
             nextStatePatch = fetchResult.state;
             notModified = fetchResult.notModified ?? false;
+            if (fetchResult.diag) {
+                result.diag[source.id] = fetchResult.diag;
+            }
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
+            progress?.fail(`[${source.id}] Failed`, message);
             error(`watch run: '${source.id}' fetch failed: ${message}`);
             result.errors.push({ sourceId: source.id, message });
             continue;
@@ -298,6 +385,16 @@ export async function watchRun(options) {
         result.detected[source.id] = detectedItems;
         result.states[source.id] = nextState;
         result.stats[source.id] = { fetched: fetched.length, filtered: filteredCount };
+        // Per-source completion phase. We use the reporter's `succeed()` so the
+        // spinner row stops cleanly and the user gets a single summary line
+        // (`[<source-id>] Completed: <items> total, <new> new (<duration>)`).
+        // The legacy plain log lines further up the loop are intentionally
+        // preserved (acceptance criterion #7) so scripts that grep stdout
+        // continue to work.
+        if (progress) {
+            const duration = Date.now() - sourceStartedAt;
+            progress.succeed(`[${source.id}] Completed: ${fetched.length} total, ${detectedItems.length} new`, duration);
+        }
     }
     return result;
 }