dsh-mishu 0.7.1 → 0.7.3

package/lib/core/ask.js

@@ -16,6 +16,7 @@ import { mailReportKey } from "./mail/sync.js";
 import { isActive } from "./matters.js";
 import { CATEGORY_LABELS, describeRepeat, occurrence, remindDay } from "./recur.js";
 import { dayOf, formatMoment } from "./time.js";
+import { watchById, watchReportKey } from "./watch/source.js";
 /** The tools the model can use in that chat, so it can look further and act only with your OK. */
 function toolsHint(lang, id) {
     return lang === 'zh'
@@ -128,5 +129,20 @@ export function buildAsk(store, request, options) {
                 ? `我想让小秘书只读地查看我的「${preset.label.zh}」收件箱，需要开通 IMAP 并拿到客户端授权码（或应用专用密码）。请一步步教我怎么做，包括在网页上点哪里、要注意什么。\n\n小秘书给的说明：${preset.howTo.zh}\nIMAP 服务器：${preset.host || '（自己填）'}:${preset.port}${lines('\n测试连接时报错：', request.error)}`
                 : `I want my secretary to read my ${preset.label.en} inbox (read-only), which needs IMAP turned on and an app password. Walk me through it step by step, including where to click and what to watch out for.\n\nThe secretary's note: ${preset.howTo.en}\nIMAP server: ${preset.host || '(enter your own)'}:${preset.port}${lines('\nThe connection test said: ', request.error)}`;
         }
+        case 'watch-error': {
+            const source = watchById(store, request.watchId);
+            if (source === undefined)
+                throw notFound();
+            const report = store.get(watchReportKey(source.id));
+            const error = report?.error?.[lang] ?? (zh ? '（没有记录到错误）' : '(no error recorded)');
+            return zh
+                ? `我让小秘书盯着「${source.label}」这个网址，但它读不到内容，帮我弄明白原因、怎么解决：\n\n网址：${source.url}\n多久看一次：${source.intervalMinutes} 分钟\n我关注的字：${source.keywords.length === 0 ? '（没设，有任何变化就告诉我）' : source.keywords.join('、')}\n报错：${error}\n\n小秘书是怎么读的：普通 GET，20 秒超时，能读 RSS/Atom、JSON 列表或普通网页。如果这个网站要登录才能看，或者防爬，告诉我该怎么办。`
+                : `I asked my secretary to keep an eye on ${source.url}, but it cannot read it. Help me understand why and what to do:\n\nAddress: ${source.url}\nCheck every: ${source.intervalMinutes} minutes\nWords I watch for: ${source.keywords.length === 0 ? '(none — tell me about any change)' : source.keywords.join(', ')}\nError: ${error}\n\nHow it reads: a plain GET with a 20-second timeout, working on RSS/Atom, a JSON list or a plain page. If the site needs a login or blocks robots, tell me what to do instead.`;
+        }
+        case 'watch-setup': {
+            return zh
+                ? '我想让小秘书帮我盯着一些我自己关心的东西：某个公告页、某个商品的价格、某个职位的招聘页、某个订阅源。请告诉我：哪些网址它读得到、哪些读不到（要登录的、全靠 JS 渲染的、防爬的），RSS 和普通网页分别会怎么处理，关键词该怎么写才能不漏也不吵，检查间隔设多长合适。'
+                : 'I want my secretary to watch a few things I care about myself: a page of announcements, the price of something, a job posting, a feed. Tell me which addresses it can read and which it cannot (login walls, JS-only pages, bot blocking), how it treats a feed versus a plain page, how to write the words I watch for so nothing is missed and nothing is noisy, and how often to check.';
+        }
     }
 }

package/lib/core/board.js

@@ -13,6 +13,7 @@ import { decode } from "./i18n.js";
 import { manualExplain, storedExplain } from "./explain.js";
 import { isActive } from "./matters.js";
 import { mailReportKey } from "./mail/sync.js";
+import { watchReportKey } from "./watch/source.js";
 import { CATEGORY_LABELS, describeRepeat, occurrence, remindDay } from "./recur.js";
 import { addDays, dayOf, dayStart, daysBetween, formatMoment, relativeDay, weekday } from "./time.js";
 const zhOr = (lang, zh, en) => (lang === 'zh' ? zh : en);
@@ -43,7 +44,7 @@ function matterCard(store, m, today, now, lang, column) {
     }
     else {
         const label = CATEGORY_LABELS[m.kind];
-        const where = m.source === 'mail' ? zhOr(lang, '邮件', 'Mail') : 'GitHub';
+        const where = m.source === 'mail' ? zhOr(lang, '邮件', 'Mail') : m.source === 'watch' ? zhOr(lang, '关注', 'Watching') : 'GitHub';
         meta = manual && label !== undefined ? label[lang] : `${where} · ${reasonLabel(m.reason, lang)}`;
     }
     const actions = column === 'handle'
@@ -61,7 +62,8 @@ function matterCard(store, m, today, now, lang, column) {
         explain.why += zhOr(lang, `你说了"明天再说"，${m.snoozeUntil} 会回到"要你处理"。`, ` You put it off; it comes back on ${m.snoozeUntil}.`);
     }
     // The open button says what it opens ("Turn off Actions", "Open the failing log").
-    return { id: m.id, target: 'matter', source: manual ? 'manual' : m.source === 'mail' ? 'mail' : 'github', title, meta, note: note === '' ? null : note, url: explain?.link?.url ?? m.url, tone, actions, explain };
+    const source = manual ? 'manual' : m.source === 'mail' ? 'mail' : m.source === 'watch' ? 'watch' : 'github';
+    return { id: m.id, target: 'matter', source, title, meta, note: note === '' ? null : note, url: explain?.link?.url ?? m.url, tone, actions, explain };
 }
 export function buildBoard(store, options) {
     const { now, lang } = options;
@@ -121,6 +123,14 @@ export function buildBoard(store, options) {
             return { id: account.id, label: account.label, state: 'error', text: zhOr(lang, `${account.label}：${report.error.zh}`, `${account.label}: ${report.error.en}`) };
         return { id: account.id, label: account.label, state: 'ok', text: zhOr(lang, `${account.label} ${formatMoment(report.at, now)} 收信`, `${account.label} checked ${formatMoment(report.at, now)}`) };
     });
+    const watch = (options.watches ?? []).map((source) => {
+        const report = store.get(watchReportKey(source.id));
+        if (report === undefined)
+            return { id: source.id, label: source.label, state: 'never', text: zhOr(lang, `${source.label} 还没看过`, `${source.label} not checked yet`) };
+        if (report.error !== undefined)
+            return { id: source.id, label: source.label, state: 'error', text: zhOr(lang, `${source.label}：${report.error.zh}`, `${source.label}: ${report.error.en}`) };
+        return { id: source.id, label: source.label, state: 'ok', text: zhOr(lang, `${source.label} ${formatMoment(report.at, now)} 看过`, `${source.label} checked ${formatMoment(report.at, now)}`) };
+    });
     const github = !options.github.enabled
         ? { state: 'off', text: zhOr(lang, 'GitHub 未开启', 'GitHub off') }
         : last === undefined
@@ -143,12 +153,14 @@ export function buildBoard(store, options) {
         parts.push(zhOr(lang, 'GitHub 这次没同步成。', 'The last GitHub sync failed.'));
     for (const box of mail.filter(b => b.state === 'error'))
         parts.push(zhOr(lang, `邮箱「${box.label}」这次没收成。`, `Mail "${box.label}" could not be checked.`));
+    for (const box of watch.filter(b => b.state === 'error'))
+        parts.push(zhOr(lang, `关注「${box.label}」这次没读成。`, `Watch "${box.label}" could not be read.`));
     return {
         lang,
         at: now,
         summary: parts.join(lang === 'zh' ? '' : ' '),
         metrics: { handle: handle.length, overdue, dueSoon, closedToday, shadow },
-        sources: { github, manual: { series: store.activeSeries().length }, mail },
+        sources: { github, manual: { series: store.activeSeries().length }, mail, watch },
         markRead: options.github.markRead,
         columns: {
             handle: handle.map(m => matterCard(store, m, today, now, lang, 'handle')),

package/lib/core/brief.js

@@ -10,6 +10,7 @@ import { isActive } from "./matters.js";
 import { mailReportKey } from "./mail/sync.js";
 import { CATEGORY_LABELS } from "./recur.js";
 import { dayOf, daysBetween, formatMoment, relativeDay, weekday } from "./time.js";
+import { watchReportKey } from "./watch/source.js";
 export const REASON_LABELS = {
     merged: bi('已合并', 'merged'),
     closed: bi('已关闭', 'closed'),
@@ -43,6 +44,10 @@ export const REASON_LABELS = {
     'mail-cc': bi('只是抄送', 'Cc only'),
     'read-in-mail': bi('你在邮箱里看过了', 'read in your mail'),
     'account-removed': bi('邮箱账户已移除', 'mail account removed'),
+    'watch-new': bi('有新内容', 'new entries'),
+    'watch-changed': bi('内容有变化', 'changed'),
+    'watch-keyword': bi('提到你关注的字', 'mentioned your words'),
+    'watch-removed': bi('你删掉了这个关注', 'watch removed'),
 };
 export function reasonLabel(reason, lang) {
     if (reason === null)
@@ -75,6 +80,8 @@ function sourceTag(m, lang) {
         return 'GitHub';
     if (m.source === 'mail')
         return pick(bi('邮件', 'Mail'), lang);
+    if (m.source === 'watch')
+        return pick(bi('关注', 'Watching'), lang);
     return m.source;
 }
 /** One matter as a few lines. */
@@ -181,6 +188,15 @@ export function renderBrief(store, options) {
         else
             out.push(zh ? `邮件「${account.label}」：${formatMoment(report.at, now)} 收信，${report.messages} 封未读。` : `Mail "${account.label}": checked ${formatMoment(report.at, now)}, ${report.messages} unread.`);
     }
+    for (const source of options.watches ?? []) {
+        const report = store.get(watchReportKey(source.id));
+        if (report === undefined)
+            out.push(zh ? `关注「${source.label}」：还没看过。` : `Watching "${source.label}": not checked yet.`);
+        else if (report.error !== undefined)
+            out.push(zh ? `关注「${source.label}」：${formatMoment(report.at, now)} 没读成：${report.error.zh}` : `Watching "${source.label}": failed at ${formatMoment(report.at, now)}: ${report.error.en}`);
+        else
+            out.push(zh ? `关注「${source.label}」：${formatMoment(report.at, now)} 看过，${report.items} 条内容。` : `Watching "${source.label}": checked ${formatMoment(report.at, now)}, ${report.items} entries.`);
+    }
     return out.join('\n');
 }
 /** Recently closed matters with reasons, so a wrong closure can be reopened. */

package/lib/core/index.js

@@ -29,6 +29,9 @@ export { DEFAULT_NOTIFY, deliver, inQuiet, localClock, notifySettings, notifyTic
 export { restartPlan, scheduleRestart } from "./restart.js";
 export { FileSecrets, KeychainOrFile, MemorySecrets, secretEnvName, secretFromEnv, systemSecrets } from "./secrets.js";
 export { deleteMailAccount, effectiveSettings, mailAccounts, saveMailAccount, saveSettings } from "./settings.js";
+export { deleteWatch, dueWatches, entryKey, parseKeywords, resolveWatch, saveWatch, watchById, watchReportKey, watchSources, WATCH_SOURCE, } from "./watch/source.js";
+export { describeWatchError, httpFetch, parseFeed, parseJson, parsePage, plainText, readWatchBody } from "./watch/fetch.js";
+export { describeKeywords, describeWatch, diffItems, judgeWatch, syncWatch } from "./watch/sync.js";
 export const DEFAULT_HOME = '~/.mishu';
 /** `~` and `~/…` expand to the home directory on every platform. */
 export function expandHome(path) {

package/lib/core/watch/fetch.js

@@ -0,0 +1,169 @@
+/**
+ * Reading a watched address: a feed, a JSON list, or just a page.
+ *
+ * Whatever comes back is turned into a handful of items — a title, a bit of
+ * text and a stable key — so the rest of the code never has to care whether
+ * it was RSS, Atom, JSON or plain HTML. No parser library: the shapes that
+ * matter here are small, and a wrong guess costs nothing (the page is read
+ * as text and still works).
+ */
+import { createHash } from 'node:crypto';
+import { bi } from "../i18n.js";
+import { entryKey } from "./source.js";
+/** The real fetch: a plain GET with a short timeout and no cookies. */
+export const httpFetch = async (url) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 20_000);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            redirect: 'follow',
+            signal: controller.signal,
+            headers: {
+                'user-agent': 'dsh-mishu/1 (+https://github.com/AIcivilization/dsh-mishu)',
+                accept: 'application/rss+xml, application/atom+xml, application/json, text/html;q=0.9, */*;q=0.8',
+            },
+        });
+        const body = await response.text();
+        return { status: response.status, body, contentType: response.headers.get('content-type') ?? '' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+function unescape(text) {
+    return text
+        .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (whole, name) => {
+        if (name.startsWith('#')) {
+            const code = name[1]?.toLowerCase() === 'x' ? Number.parseInt(name.slice(2), 16) : Number.parseInt(name.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code < 0x110000 ? String.fromCodePoint(code) : whole;
+        }
+        return ENTITIES[name.toLowerCase()] ?? whole;
+    });
+}
+/** Markup out, whitespace collapsed. */
+export function plainText(markup) {
+    return unescape(markup
+        .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<[^>]+>/g, ' '))
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function tag(block, name) {
+    const match = new RegExp(`<${name}\\b[^>]*>([\\s\\S]*?)</${name}>`, 'i').exec(block);
+    if (match === null)
+        return undefined;
+    const inner = match[1];
+    const cdata = /^\s*<!\[CDATA\[([\s\S]*?)\]\]>\s*$/.exec(inner);
+    return plainText(cdata === null ? inner : cdata[1]);
+}
+function attr(block, name) {
+    const match = new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`, 'i').exec(block);
+    return match === null ? undefined : unescape(match[1]);
+}
+/** RSS `<item>` and Atom `<entry>` blocks, whichever the document has. */
+export function parseFeed(body, now, base) {
+    const blocks = [...body.matchAll(/<(item|entry)\b[\s\S]*?<\/\1>/gi)].map(m => m[0]);
+    if (blocks.length === 0)
+        return undefined;
+    return blocks.map((block) => {
+        const title = tag(block, 'title') ?? '';
+        const link = tag(block, 'link') ?? (() => {
+            const href = attr(block, 'href');
+            return href === undefined ? undefined : href;
+        })();
+        const bodyText = tag(block, 'description') ?? tag(block, 'summary') ?? tag(block, 'content') ?? '';
+        const guid = tag(block, 'guid') ?? tag(block, 'id');
+        const when = tag(block, 'pubDate') ?? tag(block, 'updated') ?? tag(block, 'published') ?? tag(block, 'dc:date');
+        const at = when === undefined ? now : Date.parse(when);
+        const href = link === undefined ? null : absolute(link, base);
+        return {
+            key: entryKey({ id: guid ?? href ?? undefined, link: href ?? undefined, title }),
+            title: title === '' ? (href ?? '?') : title,
+            text: bodyText,
+            url: href,
+            at: Number.isFinite(at) ? at : now,
+        };
+    });
+}
+function absolute(link, base) {
+    try {
+        return new URL(link, base).toString();
+    }
+    catch {
+        return link;
+    }
+}
+/**
+ * A JSON body: an array of objects, or an object with one array inside. Each
+ * element's title-like and text-like fields become an item.
+ */
+export function parseJson(body, now, base) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const list = Array.isArray(value)
+        ? value
+        : Object.values(value).find(Array.isArray);
+    if (list === undefined || list.length === 0)
+        return undefined;
+    const str = (item, names) => {
+        for (const name of names) {
+            const found = item[name];
+            if (typeof found === 'string' && found.trim() !== '')
+                return found;
+            if (typeof found === 'number')
+                return String(found);
+        }
+        return undefined;
+    };
+    return list.slice(0, 60).map((raw) => {
+        if (typeof raw !== 'object' || raw === null)
+            return { key: entryKey({ title: String(raw) }), title: String(raw), text: '', url: null, at: now };
+        const item = raw;
+        const title = str(item, ['title', 'name', 'subject', 'headline', 'version', 'label']) ?? JSON.stringify(item).slice(0, 120);
+        const text = str(item, ['description', 'body', 'content', 'summary', 'text', 'excerpt', 'details']) ?? '';
+        const link = str(item, ['url', 'link', 'html_url', 'permalink', 'href']);
+        const when = str(item, ['date', 'published', 'updated', 'pubDate', 'created_at', 'time', 'timestamp']);
+        const at = when === undefined ? now : Date.parse(when);
+        const href = link === undefined ? null : absolute(link, base);
+        return {
+            key: entryKey({ id: str(item, ['id', 'guid', 'uuid', 'key']) ?? href ?? undefined, link: href ?? undefined, title }),
+            title, text, url: href, at: Number.isFinite(at) ? at : now,
+        };
+    });
+}
+/** A page with no feed: its title and text, as one item keyed by a hash of the text. */
+export function parsePage(body, now, base) {
+    const title = plainText(/<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(body)?.[1] ?? '') || new URL(base).hostname;
+    const text = plainText(/<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(body)?.[1] ?? body).slice(0, 20_000);
+    const key = createHash('sha256').update(text).digest('hex').slice(0, 16);
+    return [{ key, title, text, url: base, at: now }];
+}
+/** Whatever the address returned, as items. */
+export function readWatchBody(options) {
+    const { body, contentType, url, now } = options;
+    const looksJson = /json/i.test(contentType) || /^\s*[[{]/.test(body);
+    const looksFeed = /xml|rss|atom/i.test(contentType) || /<(rss|feed)\b/i.test(body);
+    if (looksFeed || (!looksJson && /<(item|entry)\b/i.test(body)))
+        return parseFeed(body, now, url) ?? parsePage(body, now, url);
+    if (looksJson)
+        return parseJson(body, now, url) ?? parsePage(body, now, url);
+    return parsePage(body, now, url);
+}
+/** The sentence shown when a watch cannot be read. */
+export function describeWatchError(error, source) {
+    const raw = error.message ?? String(error);
+    if (/abort/i.test(raw))
+        return bi(`${source.label} 20 秒没有回应，可能是网站太慢或打不开。`, `${source.label} did not answer within 20 seconds; the site may be slow or down.`);
+    if (/ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(raw))
+        return bi(`${source.label} 的网址找不到服务器：检查一下网址有没有写错。`, `The server for ${source.label} was not found: check the address.`);
+    if (/certificate|self.signed|SSL|TLS/i.test(raw))
+        return bi(`${source.label} 的证书有问题，读不了。`, `${source.label} has a certificate problem and could not be read.`);
+    return bi(`读 ${source.label} 失败：${raw}`, `Could not read ${source.label}: ${raw}`);
+}

package/lib/core/watch/source.js

@@ -0,0 +1,116 @@
+/**
+ * Things you watch yourself: a page, a feed or an API you care about.
+ *
+ * GitHub and mail are sources the secretary knows how to read. Everything
+ * else a person cares about — a game's patch notes, a job posting, a price,
+ * a status page — is a URL. You add it here with the words that matter to
+ * you, and the secretary looks at it now and then: when it changes, or when
+ * one of your words shows up, it becomes a card like anything else.
+ *
+ * Only where and what to look for is kept here. What was seen last lives in
+ * the notebook's key-value table, so an entry never grows without bound.
+ */
+import { createHash } from 'node:crypto';
+import { bi, MishuError } from "../i18n.js";
+export const WATCH_SOURCE = 'watch';
+const SOURCES_KEY = 'watch.sources';
+const NEXT_ID_KEY = 'watch.nextId';
+export function watchSources(store) {
+    return store.get(SOURCES_KEY) ?? [];
+}
+export function watchById(store, id) {
+    return watchSources(store).find(s => s.id === id);
+}
+export function watchReportKey(id) {
+    return `watch.lastSync.${id}`;
+}
+/** Where one watch keeps what it has already seen. */
+export function watchStateKey(id) {
+    return `watch.state.${id}`;
+}
+export function watchSeenKey(id) {
+    return `watch.seen.${id}`;
+}
+/** A stable id for a feed entry: its guid, else its link, else its title. */
+export function entryKey(entry) {
+    const basis = entry.id ?? entry.link ?? entry.title ?? '';
+    return createHash('sha256').update(basis).digest('hex').slice(0, 16);
+}
+/** Split what you typed into words: commas, 、, spaces or new lines all work. */
+export function parseKeywords(value) {
+    const list = Array.isArray(value) ? value : String(value ?? '').split(/[,，、;\n]+/);
+    const words = list.map(w => w.trim().toLowerCase()).filter(w => w !== '');
+    return [...new Set(words)].slice(0, 20);
+}
+/** Check and complete what the settings page sent; throws a sentence a person can act on. */
+export function resolveWatch(input, id) {
+    const raw = String(input.url ?? '').trim();
+    if (raw === '')
+        throw new MishuError(bi('还没填网址', 'the address is empty'));
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new MishuError(bi(`网址看不懂：${raw}。要完整的一串，比如 https://example.com/news`, `that is not a web address: ${raw}. It should look like https://example.com/news`));
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new MishuError(bi('只支持 http 和 https 的网址', 'only http and https addresses work'));
+    }
+    const label = String(input.label ?? '').trim() || url.hostname;
+    if (label.length > 60)
+        throw new MishuError(bi('名字太长了，60 个字以内', 'the name is too long; keep it under 60 characters'));
+    const intervalMinutes = Number(input.intervalMinutes ?? 60);
+    if (!Number.isInteger(intervalMinutes) || intervalMinutes < 15 || intervalMinutes > 1440) {
+        throw new MishuError(bi('多久看一次要是 15 到 1440 分钟', 'how often to look must be 15 to 1440 minutes'));
+    }
+    return {
+        id,
+        label,
+        url: url.toString(),
+        keywords: parseKeywords(input.keywords),
+        enabled: input.enabled !== false,
+        intervalMinutes,
+    };
+}
+/** Add (no id) or update one watch. */
+export function saveWatch(store, input, now) {
+    const sources = watchSources(store);
+    const existing = input.id === undefined ? undefined : sources.find(s => s.id === input.id);
+    if (input.id !== undefined && existing === undefined)
+        throw new MishuError(bi(`没有 #${input.id} 这个关注`, `there is no watch #${input.id}`));
+    const id = existing?.id ?? (store.get(NEXT_ID_KEY) ?? 1);
+    const source = resolveWatch({ ...existing, ...input }, id);
+    store.set(SOURCES_KEY, existing === undefined ? [...sources, source] : sources.map(s => (s.id === id ? source : s)));
+    if (existing === undefined)
+        store.set(NEXT_ID_KEY, id + 1);
+    store.log(now, existing === undefined ? 'watch-add' : 'watch-update', { id, url: source.url, keywords: source.keywords.length });
+    return source;
+}
+/** Remove one watch and close whatever it still has open. */
+export function deleteWatch(store, id, now) {
+    const sources = watchSources(store);
+    if (!sources.some(s => s.id === id))
+        return false;
+    store.transaction(() => {
+        store.set(SOURCES_KEY, sources.filter(s => s.id !== id));
+        store.set(watchStateKey(id), null);
+        store.set(watchSeenKey(id), null);
+        for (const matter of store.mattersOfSource(WATCH_SOURCE)) {
+            if (matter.status === 'open' && (matter.key === `watch:${id}` || matter.key.startsWith(`watch:${id}:`))) {
+                store.updateMatter(matter.id, { status: 'done', reason: 'watch-removed', closedBy: 'source', closedAt: now }, now);
+            }
+        }
+        store.log(now, 'watch-delete', { id });
+    });
+    return true;
+}
+/** The watches whose next check is due. */
+export function dueWatches(store, now) {
+    return watchSources(store).filter((source) => {
+        if (!source.enabled)
+            return false;
+        const report = store.get(watchReportKey(source.id));
+        return report === undefined || now - report.at >= source.intervalMinutes * 60_000;
+    });
+}

package/lib/core/watch/sync.js

@@ -0,0 +1,171 @@
+/**
+ * One watch, one check: read the address, compare with what was seen last
+ * time, and turn anything new into a card.
+ *
+ * A card per watch, not per entry: "补丁公告 · 3 条新内容" is what you want to
+ * see, not three cards that say the same thing. Marking it done closes it;
+ * the next change opens it again with what changed.
+ *
+ * The first check only writes down what is there now — otherwise adding a
+ * feed would hand you every entry it ever published. Words you asked to watch
+ * for are the exception: those are shown right away, because you asked.
+ */
+import { applyVerdict } from "../fold.js";
+import { bi, MishuError } from "../i18n.js";
+import { shortDay } from "../time.js";
+import { describeWatchError, readWatchBody } from "./fetch.js";
+import { WATCH_SOURCE, watchReportKey, watchSeenKey, watchStateKey } from "./source.js";
+/** How many entry keys one watch remembers. A feed longer than this is fine; the tail ages out. */
+const SEEN_LIMIT = 500;
+function readState(store, id) {
+    return store.get(watchStateKey(id)) ?? { seen: [], primed: false };
+}
+/** Which items are new since last time, and whether the whole page changed. */
+export function diffItems(items, state) {
+    const seen = new Set(state.seen);
+    const fresh = items.filter(item => !seen.has(item.key));
+    // A single-item read is a page: its key is a hash of the text, so "new" means "the text changed".
+    const digest = items.length === 1 ? items[0].key : items.map(i => i.key).sort().join(',');
+    return { fresh, changed: state.digest !== undefined && state.digest !== digest, digest };
+}
+function matches(item, keywords) {
+    if (keywords.length === 0)
+        return undefined;
+    const haystack = `${item.title}\n${item.text}`.toLowerCase();
+    return keywords.find(word => haystack.includes(word));
+}
+function quote(items, lang) {
+    const shown = items.slice(0, 3).map(i => `「${i.title.slice(0, 80)}」`);
+    const more = items.length - shown.length;
+    if (lang === 'zh')
+        return more > 0 ? `${shown.join('、')} 等 ${items.length} 条` : shown.join('、');
+    return more > 0 ? `${shown.join(', ')} and ${more} more` : shown.join(', ');
+}
+export function judgeWatch(options) {
+    const { source, items, fresh, changed, first, now } = options;
+    const hit = (list) => list
+        .map(item => ({ item, word: matches(item, source.keywords) }))
+        .filter((x) => x.word !== undefined);
+    const freshHits = hit(fresh);
+    const allHits = hit(items);
+    const keywordMode = source.keywords.length > 0;
+    let reason;
+    let relevant;
+    let word;
+    if (keywordMode) {
+        // A word you watch for is worth a card even on the very first check.
+        relevant = (first ? allHits : freshHits).map(x => x.item);
+        if (relevant.length === 0)
+            return undefined;
+        word = (first ? allHits : freshHits)[0].word;
+        reason = 'watch-keyword';
+    }
+    else if (first) {
+        return undefined;
+    }
+    else if (fresh.length > 0) {
+        relevant = fresh;
+        reason = items.length > 1 ? 'watch-new' : 'watch-changed';
+    }
+    else if (changed) {
+        relevant = items.slice(0, 1);
+        reason = 'watch-changed';
+    }
+    else {
+        return undefined;
+    }
+    const when = shortDay(now);
+    const what = bi(`你关注「${source.label}」（${new URL(source.url).hostname}）`, `The thing you watch: "${source.label}" (${new URL(source.url).hostname})`);
+    const why = keywordMode && word !== undefined
+        ? bi(`${when} 检查时，这里有内容提到你关注的字「${word}」：${quote(relevant, 'zh')}。`, `On ${when} it mentioned "${word}", one of your words: ${quote(relevant, 'en')}.`)
+        : reason === 'watch-new'
+            ? bi(`${when} 检查时出现了 ${fresh.length} 条新内容：${quote(relevant, 'zh')}。`, `On ${when} there were ${fresh.length} new entries: ${quote(relevant, 'en')}.`)
+            : bi(`${when} 检查时，${source.label} 的内容变了：${quote(relevant, 'zh')}。`, `On ${when} "${source.label}" changed: ${quote(relevant, 'en')}.`);
+    const link = relevant.find(i => i.url !== null)?.url ?? source.url;
+    return {
+        matterKey: `watch:${source.id}`,
+        kind: 'watch',
+        title: source.label,
+        url: link,
+        status: 'open',
+        reason,
+        note: bi(keywordMode ? `提到「${word}」` : reason === 'watch-new' ? `${fresh.length} 条新内容` : '内容有变化', keywordMode ? `mentions "${word}"` : reason === 'watch-new' ? `${fresh.length} new entries` : 'changed'),
+        explain: {
+            what,
+            why,
+            fix: bi('打开看一眼；处理完点"办完了"。不想再关注了，在设置里删掉这一条。', 'Open it and have a look; mark it done afterwards. To stop watching, delete it in Settings.'),
+            link: { label: bi('打开看看', 'Open it'), url: link },
+        },
+    };
+}
+export async function syncWatch(options) {
+    const { store, source, fetcher, now } = options;
+    const report = { at: now, id: source.id, items: 0, opened: 0, closed: 0 };
+    let body;
+    try {
+        body = await fetcher(source.url);
+    }
+    catch (error) {
+        report.error = describeWatchError(error, source);
+        store.set(watchReportKey(source.id), report);
+        return report;
+    }
+    if (body.status >= 400) {
+        report.error = body.status === 404
+            ? bi(`${source.label} 打不开了（404）：这个网址可能已经变了。`, `${source.label} is gone (404): the address may have moved.`)
+            : bi(`${source.label} 返回 ${body.status}，读不到内容。`, `${source.label} answered ${body.status}, so there was nothing to read.`);
+        store.set(watchReportKey(source.id), report);
+        return report;
+    }
+    if (body.body.trim() === '') {
+        report.error = bi(`${source.label} 这次读到的是空页面。`, `${source.label} came back empty.`);
+        store.set(watchReportKey(source.id), report);
+        return report;
+    }
+    const items = readWatchBody({ body: body.body, contentType: body.contentType, url: source.url, now });
+    if (items.length === 0) {
+        report.error = bi(`${source.label} 这次读到的是空页面。`, `${source.label} came back empty.`);
+        store.set(watchReportKey(source.id), report);
+        return report;
+    }
+    report.items = items.length;
+    const state = readState(store, source.id);
+    const { fresh, changed, digest } = diffItems(items, state);
+    const verdict = judgeWatch({ source, items, fresh, changed, first: !state.primed, now });
+    store.transaction(() => {
+        if (verdict !== undefined) {
+            const counts = { opened: 0, closed: 0 };
+            applyVerdict(store, WATCH_SOURCE, { ...verdict, activityAt: Math.max(...items.map(i => i.at), now) }, now, counts);
+            report.opened = counts.opened;
+            report.closed = counts.closed;
+        }
+        const seen = [...state.seen, ...fresh.map(i => i.key)];
+        const trimmed = seen.length > SEEN_LIMIT ? seen.slice(seen.length - SEEN_LIMIT) : seen;
+        store.set(watchStateKey(source.id), { seen: trimmed, digest, primed: true });
+        store.set(watchSeenKey(source.id), trimmed.length);
+    });
+    store.set(watchReportKey(source.id), report);
+    return report;
+}
+/** Everything about one watch the settings page shows. */
+export function describeWatch(store, source, lang) {
+    const report = store.get(watchReportKey(source.id));
+    if (report === undefined)
+        return lang === 'zh' ? '还没看过' : 'not checked yet';
+    if (report.error !== undefined)
+        return report.error[lang];
+    return lang === 'zh'
+        ? `${shortDay(report.at)} 看过，${report.items} 条内容`
+        : `checked ${shortDay(report.at)}, ${report.items} entries`;
+}
+/** The words, for showing back to you. */
+export function describeKeywords(source, lang) {
+    if (source.keywords.length === 0)
+        return lang === 'zh' ? '有任何变化就告诉我' : 'tell me about any change';
+    return lang === 'zh' ? `提到 ${source.keywords.join('、')} 时告诉我` : `tell me when it mentions ${source.keywords.join(', ')}`;
+}
+/** Guard for the settings page: an address that cannot be a watch at all. */
+export function assertWatchable(source) {
+    if (!/^https?:\/\//.test(source.url))
+        throw new MishuError(bi('只支持 http 和 https 的网址', 'only http and https addresses work'));
+}