@lowzj/news-skill 0.1.0

package/skills/news/scripts/query.js

@@ -0,0 +1,285 @@
+const PAGE_SIZE = 128;
+const DAY_MS = 86_400_000;
+function integer(value, fallback, maximum, name) {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < 1 || result > maximum) {
+        throw new Error(`${name} must be an integer between 1 and ${maximum}.`);
+    }
+    return result;
+}
+function parseDay(value, name = 'day') {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new Error(`${name} must be a valid date in YYYY-MM-DD format.`);
+    }
+    const time = Date.parse(`${value}T00:00:00.000Z`);
+    if (!Number.isFinite(time) || new Date(time).toISOString().slice(0, 10) !== value) {
+        throw new Error(`${name} must be a valid date in YYYY-MM-DD format.`);
+    }
+    return time;
+}
+function formatDay(time) {
+    const result = new Date(time).toISOString().slice(0, 10);
+    parseDay(result);
+    return result;
+}
+function range(from, to) {
+    const start = parseDay(from, 'from');
+    const end = parseDay(to, 'to');
+    const count = (end - start) / DAY_MS + 1;
+    if (count < 1 || count > 31) {
+        throw new Error('The date range must be ascending and contain at most 31 days.');
+    }
+    return Array.from({ length: count }, (_, index) => formatDay(end - index * DAY_MS));
+}
+function todayInTimezone(now, timezone) {
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat('en-US', {
+            timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit',
+        }).formatToParts(now);
+    }
+    catch {
+        throw new Error(`The NEWS service returned an invalid timezone: ${timezone}`);
+    }
+    const part = (kind) => parts.find(entry => entry.type === kind)?.value ?? '';
+    const result = `${part('year').padStart(4, '0')}-${part('month')}-${part('day')}`;
+    parseDay(result);
+    return result;
+}
+function normalizeText(value) {
+    return value.normalize('NFKC').toLowerCase();
+}
+function matchesText(item, query) {
+    return [item.title, item.summary, item.title_en, item.summary_en, item.source, ...item.tags]
+        .some(value => normalizeText(value).includes(query));
+}
+function normalizedUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return null;
+        url.hash = '';
+        for (const key of [...url.searchParams.keys()]) {
+            if (/^utm_/i.test(key) || /^(fbclid|gclid|msclkid)$/i.test(key))
+                url.searchParams.delete(key);
+        }
+        url.searchParams.sort();
+        return url.href;
+    }
+    catch {
+        // Missing or invalid URLs cannot identify duplicates of different IDs.
+        return null;
+    }
+}
+function timestamp(item) {
+    const published = item.published_at === null ? NaN : Date.parse(item.published_at);
+    if (Number.isFinite(published))
+        return published;
+    const seen = Date.parse(item.first_seen_at);
+    return Number.isFinite(seen) ? seen : 0;
+}
+function compareLatest(left, right) {
+    return timestamp(right) - timestamp(left)
+        || right.importance - left.importance
+        || left.id.localeCompare(right.id)
+        || left.url.localeCompare(right.url);
+}
+/** Scan the selected calendar days before ranking and applying the global limit. */
+export async function queryNews(api, options = {}, now = new Date()) {
+    const limit = integer(options.limit, 10, 100, 'limit');
+    const maxPages = integer(options.maxPages, 20, 200, 'maxPages');
+    const minImportance = integer(options.minImportance, 1, 5, 'minImportance');
+    const sort = options.sort ?? 'latest';
+    if (sort !== 'latest' && sort !== 'importance')
+        throw new Error('sort must be latest or importance.');
+    if (!Number.isFinite(now.getTime()))
+        throw new Error('now must be a valid date.');
+    if (options.topic !== undefined && !options.topic.trim())
+        throw new Error('topic must not be empty.');
+    const hasRange = options.from !== undefined || options.to !== undefined;
+    const selectors = Number(options.day !== undefined) + Number(options.days !== undefined) + Number(hasRange);
+    if (selectors > 1)
+        throw new Error('Use only one of day, days, or from/to.');
+    if (hasRange && (options.from === undefined || options.to === undefined)) {
+        throw new Error('from and to must be supplied together.');
+    }
+    const dayCount = options.days === undefined ? undefined : integer(options.days, 1, 31, 'days');
+    let selectedDays;
+    if (hasRange)
+        selectedDays = range(options.from, options.to);
+    else if (options.day !== undefined && options.day !== 'today' && options.day !== 'yesterday') {
+        parseDay(options.day);
+        selectedDays = [options.day];
+    }
+    const query = options.query?.trim() || null;
+    const needle = normalizeText(query ?? '');
+    const params = (day, topic = options.topic, after) => ({
+        ...(topic !== undefined ? { topic } : {}),
+        ...(day !== undefined ? { day } : {}),
+        limit: PAGE_SIZE,
+        ...(after !== undefined ? { after } : {}),
+    });
+    // For relative selectors this call discovers the service timezone. Its page is
+    // reused when it belongs to the requested days; otherwise it is metadata only.
+    const initial = await api.digest(params(selectedDays?.[0]));
+    if (selectedDays !== undefined && initial.day !== selectedDays[0]) {
+        throw new Error(`The NEWS service returned day ${initial.day ?? 'null'} while requesting ${selectedDays[0]}.`);
+    }
+    const today = todayInTimezone(now, initial.timezone);
+    if (selectedDays === undefined) {
+        if (dayCount !== undefined) {
+            selectedDays = Array.from({ length: dayCount }, (_, index) => formatDay(parseDay(today) - index * DAY_MS));
+        }
+        else if (options.day === 'today' || options.day === 'yesterday') {
+            selectedDays = [formatDay(parseDay(today) - (options.day === 'yesterday' ? DAY_MS : 0))];
+        }
+        else {
+            selectedDays = initial.day === null ? [] : [initial.day];
+            if (initial.day !== null)
+                parseDay(initial.day);
+        }
+    }
+    const selectedTopics = initial.topics.filter(topic => options.topic === undefined || topic.id === options.topic);
+    if (options.topic !== undefined && selectedTopics.length === 0) {
+        throw new Error(`The NEWS service did not return the requested topic: ${options.topic}`);
+    }
+    const topicIds = new Set(selectedTopics.map(topic => topic.id));
+    const sources = new Map();
+    const groups = new Set();
+    const byId = new Map();
+    const byUrl = new Map();
+    let pagesFetched = 0;
+    let complete = true;
+    function merge(target, incoming) {
+        const preferred = compareLatest(target.item, incoming.item) <= 0 ? target.item : incoming.item;
+        target.item = {
+            ...preferred,
+            importance: Math.max(target.item.importance, incoming.item.importance),
+            pinned: target.item.pinned || incoming.item.pinned,
+            tags: [...new Set([...target.item.tags, ...incoming.item.tags])],
+        };
+        for (const id of incoming.ids) {
+            target.ids.add(id);
+            byId.set(id, target);
+        }
+        for (const url of incoming.urls) {
+            target.urls.add(url);
+            byUrl.set(url, target);
+        }
+        for (const [id, name] of incoming.topics)
+            target.topics.set(id, name);
+        for (const day of incoming.days)
+            target.days.add(day);
+        target.matches ||= incoming.matches;
+        groups.delete(incoming);
+    }
+    function collect(topic, day) {
+        topicIds.add(topic.id);
+        sources.set(`${topic.id}\n${day}`, { topic_id: topic.id, day, updated_at: topic.updated_at });
+        for (const item of topic.items) {
+            const url = normalizedUrl(item.url);
+            const existingId = item.id ? byId.get(item.id) : undefined;
+            const existingUrl = url === null ? undefined : byUrl.get(url);
+            const incoming = {
+                item: { ...item, tags: [...item.tags] },
+                ids: new Set(item.id ? [item.id] : []),
+                urls: new Set(url === null ? [] : [url]),
+                topics: new Map([[topic.id, topic.name]]),
+                days: new Set([day]),
+                matches: !needle || matchesText(item, needle),
+            };
+            const existing = existingId ?? existingUrl;
+            if (existing === undefined) {
+                groups.add(incoming);
+                for (const id of incoming.ids)
+                    byId.set(id, incoming);
+                for (const key of incoming.urls)
+                    byUrl.set(key, incoming);
+            }
+            else {
+                if (existingId !== undefined && existingUrl !== undefined && existingId !== existingUrl) {
+                    merge(existingId, existingUrl);
+                }
+                merge(existing, incoming);
+            }
+        }
+    }
+    for (const day of selectedDays) {
+        if (pagesFetched >= maxPages) {
+            complete = false;
+            break;
+        }
+        const root = initial.day === day ? initial : await api.digest(params(day));
+        const queue = [];
+        const seen = new Map();
+        function consume(digest, onlyTopic) {
+            if (digest.day !== day) {
+                throw new Error(`The NEWS service returned day ${digest.day ?? 'null'} while requesting ${day}.`);
+            }
+            if (digest.timezone !== initial.timezone)
+                throw new Error('The NEWS service timezone changed during pagination. Retry the query.');
+            pagesFetched += 1;
+            const topics = digest.topics.filter(topic => (onlyTopic ?? options.topic) === undefined || topic.id === (onlyTopic ?? options.topic));
+            if (onlyTopic !== undefined && topics.length === 0) {
+                throw new Error(`The NEWS service omitted topic ${onlyTopic} during pagination.`);
+            }
+            for (const topic of topics) {
+                collect(topic, day);
+                if (topic.next !== null) {
+                    if (seen.get(topic.id)?.has(topic.next)) {
+                        throw new Error(`The NEWS service repeated a pagination cursor for topic ${topic.id} on ${day}.`);
+                    }
+                    queue.push({ topic: topic.id, cursor: topic.next });
+                }
+            }
+        }
+        consume(root);
+        while (queue.length > 0) {
+            if (pagesFetched >= maxPages) {
+                complete = false;
+                break;
+            }
+            const next = queue.shift();
+            const cursors = seen.get(next.topic) ?? new Set();
+            if (cursors.has(next.cursor)) {
+                throw new Error(`The NEWS service repeated a pagination cursor for topic ${next.topic} on ${day}.`);
+            }
+            cursors.add(next.cursor);
+            seen.set(next.topic, cursors);
+            consume(await api.digest(params(day, next.topic, next.cursor)), next.topic);
+        }
+        if (!complete)
+            break;
+    }
+    // An empty catalogue is still one fully consumed response for an unfiltered query.
+    if (selectors === 0 && initial.day === null)
+        pagesFetched = 1;
+    const matchedItems = [...groups]
+        .filter(group => group.matches && group.item.importance >= minImportance)
+        .map(group => ({
+        ...group.item,
+        topic_ids: [...group.topics.keys()].sort(),
+        topic_names: [...new Set(group.topics.values())].sort(),
+        days: [...group.days].sort().reverse(),
+    }));
+    matchedItems.sort((left, right) => (sort === 'importance' ? right.importance - left.importance : 0) || compareLatest(left, right));
+    const items = matchedItems.slice(0, limit);
+    return {
+        query,
+        retrieved_at: now.toISOString(),
+        timezone: initial.timezone,
+        sort,
+        returned: items.length,
+        matched: matchedItems.length,
+        items,
+        sources: [...sources.values()].sort((a, b) => b.day.localeCompare(a.day) || a.topic_id.localeCompare(b.topic_id)),
+        coverage: {
+            complete,
+            pages_fetched: pagesFetched,
+            max_pages: maxPages,
+            days: selectedDays,
+            topic_ids: [...topicIds].sort(),
+            reason: complete ? null : 'max_pages',
+        },
+    };
+}

package/skills/news/scripts/skills.js

@@ -0,0 +1,247 @@
+import { createHash } from 'node:crypto';
+import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const AGENTS = ['codex', 'claude', 'opencode', 'pi'];
+const SOURCE = fileURLToPath(new URL('../', import.meta.url));
+const MARKER = '.news-skill-install.json';
+const OWNER = 'news-skill';
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+async function statOrUndefined(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+function contains(parent, child) {
+    const rest = relative(parent, child);
+    return rest === '' || (rest !== '..' && !rest.startsWith(`..${sep}`) && !isAbsolute(rest));
+}
+// Resolve even a not-yet-created path through its closest existing ancestor.
+async function canonicalPath(path) {
+    const stat = await statOrUndefined(path);
+    if (stat)
+        return realpath(path);
+    const parent = dirname(path);
+    if (parent === path)
+        throw new Error(`Cannot resolve installation path: ${path}`);
+    return join(await canonicalPath(parent), basename(path));
+}
+async function snapshot(root) {
+    const rootStat = await lstat(root);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new Error(`Skill path must be a directory, not a symlink: ${root}`);
+    }
+    const entries = [];
+    async function visit(directory, prefix) {
+        for (const name of (await readdir(directory)).sort()) {
+            if (prefix === '' && name === MARKER)
+                continue;
+            const path = join(directory, name);
+            const local = prefix ? `${prefix}/${name}` : name;
+            const stat = await lstat(path);
+            if (stat.isSymbolicLink())
+                throw new Error(`Skill contains a symlink: ${path}`);
+            if (stat.isDirectory()) {
+                entries.push({ path: local, kind: 'directory' });
+                await visit(path, local);
+            }
+            else if (stat.isFile()) {
+                entries.push({ path: local, kind: 'file', data: await readFile(path), mode: stat.mode & 0o777 });
+            }
+            else {
+                throw new Error(`Skill contains an unsupported file: ${path}`);
+            }
+        }
+    }
+    await visit(root, '');
+    return entries;
+}
+function fingerprint(entries) {
+    const hash = createHash('sha256');
+    for (const entry of entries) {
+        hash.update(JSON.stringify([entry.path, entry.kind]));
+        if (entry.kind === 'file') {
+            hash.update(JSON.stringify([entry.data.length, entry.mode & 0o111]));
+            hash.update(entry.data);
+        }
+    }
+    return hash.digest('hex');
+}
+async function assertOwned(path) {
+    const marker = join(path, MARKER);
+    const stat = await statOrUndefined(marker);
+    if (stat?.isFile() && !stat.isSymbolicLink()) {
+        try {
+            const value = JSON.parse(await readFile(marker, 'utf8'));
+            if (typeof value === 'object' && value !== null && 'owner' in value && value.owner === OWNER && 'schema' in value && value.schema === 1)
+                return;
+        }
+        catch {
+            // An invalid marker does not establish ownership.
+        }
+    }
+    throw new Error(`Refusing to replace an existing unowned skill at ${path}. Move it aside before installing NEWS.`);
+}
+function destination(agent, scope, cwd, home, env) {
+    if (scope === 'project') {
+        const dirs = { codex: '.agents', claude: '.claude', opencode: '.opencode', pi: '.pi' };
+        return join(cwd, dirs[agent], 'skills', 'news');
+    }
+    switch (agent) {
+        case 'codex': return join(home, '.agents', 'skills', 'news');
+        case 'claude': return join(home, '.claude', 'skills', 'news');
+        case 'opencode': return resolve(cwd, env.XDG_CONFIG_HOME || join(home, '.config'), 'opencode', 'skills', 'news');
+        case 'pi': return resolve(cwd, env.PI_CODING_AGENT_DIR || join(home, '.pi', 'agent'), 'skills', 'news');
+    }
+}
+async function ensureParents(path, created) {
+    const stat = await statOrUndefined(path);
+    if (stat) {
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error(`Installation parent is not a directory: ${path}`);
+        return;
+    }
+    await ensureParents(dirname(path), created);
+    try {
+        await mkdir(path);
+        created.push(path);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+        const current = await lstat(path);
+        if (!current.isDirectory() || current.isSymbolicLink())
+            throw new Error(`Installation parent changed: ${path}`);
+    }
+}
+async function writeSnapshot(root, entries) {
+    await mkdir(root);
+    for (const entry of entries) {
+        const path = join(root, entry.path);
+        if (entry.kind === 'directory')
+            await mkdir(path);
+        else {
+            await writeFile(path, entry.data, { flag: 'wx', mode: entry.mode });
+            await chmod(path, entry.mode);
+        }
+    }
+    await writeFile(join(root, MARKER), `${JSON.stringify({ owner: OWNER, schema: 1 }, null, 2)}\n`, { flag: 'wx' });
+}
+export async function readSkill(source = SOURCE) {
+    return readFile(join(source, 'SKILL.md'), 'utf8');
+}
+export async function installSkills(options) {
+    if (options.agent !== 'all' && !AGENTS.includes(options.agent)) {
+        throw new Error('Choose an agent with --agent codex, claude, opencode, pi, or all.');
+    }
+    const scope = options.scope ?? 'user';
+    if (scope !== 'user' && scope !== 'project')
+        throw new Error('Skill scope must be user or project.');
+    const agents = options.agent === 'all' ? AGENTS : [options.agent];
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const home = resolve(options.home ?? homedir());
+    const env = options.env ?? process.env;
+    const source = resolve(options.source ?? SOURCE);
+    const sourceEntries = await snapshot(source);
+    if (!sourceEntries.some(entry => entry.path === 'SKILL.md' && entry.kind === 'file')) {
+        throw new Error(`Bundled skill is missing SKILL.md: ${source}`);
+    }
+    const sourceReal = await realpath(source);
+    const sourceHash = fingerprint(sourceEntries);
+    const plans = [];
+    // Validate every destination before creating any directories or staging files.
+    for (const agent of agents) {
+        const path = destination(agent, scope, cwd, home, env);
+        const stat = await statOrUndefined(path);
+        if (stat?.isSymbolicLink())
+            throw new Error(`Refusing to install over a symlink: ${path}`);
+        const canonical = await canonicalPath(path);
+        if (contains(source, path) || contains(path, source) || contains(sourceReal, canonical) || contains(canonical, sourceReal)) {
+            throw new Error(`Skill source and installation destination overlap: ${path}`);
+        }
+        if (plans.some(plan => contains(plan.canonicalPath, canonical) || contains(canonical, plan.canonicalPath))) {
+            throw new Error(`Selected agent installation paths overlap: ${path}`);
+        }
+        const plan = { agent, scope, path, canonicalPath: canonical, status: 'installed' };
+        if (stat) {
+            if (!stat.isDirectory())
+                throw new Error(`Installation destination is not a directory: ${path}`);
+            await assertOwned(path);
+            plan.originalHash = fingerprint(await snapshot(path));
+            if (plan.originalHash === sourceHash)
+                plan.status = 'unchanged';
+            else {
+                if (!options.force)
+                    throw new Error(`NEWS skill already exists with different contents at ${path}. Use --force to replace this NEWS installation.`);
+                plan.status = 'updated';
+            }
+        }
+        plans.push(plan);
+    }
+    const created = [];
+    const pending = plans.filter(plan => plan.status !== 'unchanged');
+    try {
+        for (const plan of pending) {
+            // Work at the resolved location so a symlinked home/config directory is supported.
+            await ensureParents(dirname(plan.canonicalPath), created);
+            plan.staging = await mkdtemp(join(dirname(plan.canonicalPath), '.news-skill-install-'));
+            await writeSnapshot(join(plan.staging, 'new'), sourceEntries);
+        }
+        for (const plan of pending) {
+            if (await canonicalPath(plan.path) !== plan.canonicalPath)
+                throw new Error(`Installation path changed during installation: ${plan.path}`);
+            const stat = await statOrUndefined(plan.path);
+            if (stat?.isSymbolicLink())
+                throw new Error(`Installation path became a symlink: ${plan.path}`);
+            if (plan.originalHash !== undefined) {
+                await assertOwned(plan.path);
+                if (fingerprint(await snapshot(plan.path)) !== plan.originalHash)
+                    throw new Error(`NEWS skill changed during installation: ${plan.path}`);
+                await rename(plan.canonicalPath, join(plan.staging, 'backup'));
+                plan.movedOld = true;
+            }
+            else if (stat) {
+                throw new Error(`Installation destination appeared during installation: ${plan.path}`);
+            }
+            await rename(join(plan.staging, 'new'), plan.canonicalPath);
+            plan.installed = true;
+        }
+    }
+    catch (error) {
+        const recovery = [];
+        for (const plan of [...pending].reverse()) {
+            try {
+                if (plan.installed)
+                    await rm(plan.canonicalPath, { recursive: true, force: true });
+                if (plan.movedOld)
+                    await rename(join(plan.staging, 'backup'), plan.canonicalPath);
+                if (plan.staging)
+                    await rm(plan.staging, { recursive: true, force: true });
+            }
+            catch {
+                if (plan.staging)
+                    recovery.push(plan.staging);
+            }
+        }
+        for (const path of [...created].reverse()) {
+            try {
+                await rmdir(path);
+            }
+            catch { /* Keep directories if another process has populated them. */ }
+        }
+        if (recovery.length)
+            throw new Error(`Skill installation failed; previous files are preserved for recovery at ${recovery.join(', ')}.`, { cause: error });
+        throw error;
+    }
+    for (const plan of pending)
+        await rm(plan.staging, { recursive: true, force: true });
+    return { installations: plans.map(({ agent, scope, path, status }) => ({ agent, scope, path, status })) };
+}

package/skills/news/scripts/types.js

@@ -0,0 +1 @@
+export {};