siftctl 0.1.0

package/dist/api.js

@@ -0,0 +1,63 @@
+import { baseUrl } from './config.js';
+export class ApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+async function request(path, opts = {}) {
+    const headers = {};
+    if (opts.token)
+        headers['X-Sync-Key'] = opts.token;
+    if (opts.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    return fetch(baseUrl() + path, {
+        method: opts.method ?? 'GET',
+        headers,
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+}
+export async function capabilities() {
+    const res = await request('/sync/capabilities');
+    if (!res.ok)
+        throw new ApiError(`Capabilities failed: ${res.status}`, res.status);
+    return (await res.json());
+}
+export async function redeemToken(code) {
+    const res = await request('/sync/tokens/redeem', {
+        method: 'POST',
+        body: { code },
+    });
+    if (res.status === 404)
+        throw new ApiError('Code not found or expired', 404);
+    if (res.status === 429)
+        throw new ApiError('Rate limited — try again in a minute', 429);
+    if (!res.ok)
+        throw new ApiError(`Redeem failed: ${res.status}`, res.status);
+    const body = (await res.json());
+    return body.token;
+}
+export async function pull(token, since = 0) {
+    const res = await request(`/sync/pull?since=${encodeURIComponent(String(since))}`, { token });
+    if (res.status === 401)
+        throw new ApiError('Unauthorized — token revoked or invalid; run `siftctl pair` again', 401);
+    if (res.status === 429)
+        throw new ApiError('Rate limited — wait a moment and retry', 429);
+    if (!res.ok)
+        throw new ApiError(`Pull failed: ${res.status}`, res.status);
+    return (await res.json());
+}
+export async function push(token, body) {
+    const res = await request('/sync/push', { method: 'POST', token, body });
+    if (res.status === 401)
+        throw new ApiError('Unauthorized — token revoked or invalid; run `siftctl pair` again', 401);
+    if (res.status === 429)
+        throw new ApiError('Rate limited — wait a moment and retry', 429);
+    if (res.status === 400) {
+        const errBody = (await res.json().catch(() => null));
+        throw new ApiError(errBody?.error ?? 'Bad request', 400);
+    }
+    if (!res.ok)
+        throw new ApiError(`Push failed: ${res.status}`, res.status);
+}

package/dist/cli.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { baseUrl, readToken, writeToken } from './config.js';
+import { ApiError, capabilities, pull, push, redeemToken } from './api.js';
+import { tokenFingerprint } from './fingerprint.js';
+import { fetchItems } from './items.js';
+const USAGE = `siftctl — control your Sift subscriptions
+
+Usage:
+  siftctl pair <code>               Redeem an agent pairing code from Sift Settings
+  siftctl status [--json]           Show API status, base URL, and token fingerprint
+  siftctl feeds [--json]            List subscribed feeds
+  siftctl feed add <url>            Subscribe to a feed
+  siftctl feed remove <url> --yes   Unsubscribe from a feed
+  siftctl items <url> [--limit N]   Show recent items from a feed (default 20)
+  siftctl mark read <itemId>        Mark an item read
+  siftctl help                      Show this help
+
+Environment:
+  SIFTCTL_TOKEN   Agent token (overrides the config file)
+  SIFTCTL_URL     Sift base URL (default ${baseUrl()})
+  SIFTCTL_HOME    Config directory (default ~/.config)
+
+Exit codes: 0 success, 1 runtime/API error, 2 usage error.`;
+class UsageError extends Error {
+}
+function isFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return false;
+    args.splice(idx, 1);
+    return true;
+}
+function requireToken() {
+    const token = readToken();
+    if (!token) {
+        throw new Error('Not paired. Pair an agent from Sift Settings, then run: siftctl pair <code>');
+    }
+    return token;
+}
+function out(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function liveRows(rows) {
+    return rows.filter((r) => r.deleted !== 1 && r.feed_url);
+}
+async function cmdPair(code) {
+    if (!code)
+        throw new UsageError('pair requires a code: siftctl pair <code>');
+    const token = await redeemToken(code.trim());
+    writeToken(token);
+    console.log(`Paired. Token fingerprint: ${await tokenFingerprint(token)}`);
+}
+async function cmdStatus(json) {
+    const cap = await capabilities();
+    const token = readToken();
+    if (json) {
+        out({ sync: cap.sync, url: baseUrl(), paired: token !== null, fingerprint: token ? await tokenFingerprint(token) : null });
+        return;
+    }
+    console.log(`Sync: ${cap.sync ? 'available' : 'unavailable'}`);
+    console.log(`URL: ${baseUrl()}`);
+    if (token) {
+        console.log(`Paired: yes (fingerprint ${await tokenFingerprint(token)})`);
+    }
+    else {
+        console.log('Paired: no — run `siftctl pair <code>`');
+    }
+}
+async function cmdFeeds(json) {
+    const token = requireToken();
+    const payload = await pull(token);
+    const seen = new Set();
+    const feeds = liveRows(payload.feeds)
+        .filter((f) => {
+        if (!f.feed_url || seen.has(f.feed_url))
+            return false;
+        seen.add(f.feed_url);
+        return true;
+    });
+    if (json) {
+        out(feeds.map((f) => ({ feedId: f.feed_id, url: f.feed_url, title: f.title, folder: parseJsonArray(f.folder), tags: parseJsonArray(f.tags) })));
+        return;
+    }
+    for (const f of feeds) {
+        console.log(`${f.title ?? '(untitled)'}\t${f.feed_url}`);
+    }
+}
+function parseJsonArray(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveFeedId(token, url) {
+    const payload = await pull(token);
+    const row = liveRows(payload.feeds).find((f) => f.feed_url === url);
+    return row?.feed_id ?? url;
+}
+async function cmdFeedAdd(url) {
+    if (!url)
+        throw new UsageError('feed add requires a URL: siftctl feed add <url>');
+    const token = requireToken();
+    const feedId = await resolveFeedId(token, url);
+    await push(token, { feeds: [{ feedId, feedUrl: url, deleted: 0 }] });
+    console.log(`Subscribed: ${url}`);
+}
+async function cmdFeedRemove(url, yes) {
+    if (!url)
+        throw new UsageError('feed remove requires a URL: siftctl feed remove <url> --yes');
+    if (!yes)
+        throw new UsageError('feed remove is destructive — pass --yes to confirm: siftctl feed remove <url> --yes');
+    const token = requireToken();
+    const feedId = await resolveFeedId(token, url);
+    await push(token, { feeds: [{ feedId, feedUrl: url, deleted: 1 }] });
+    console.log(`Unsubscribed: ${url}`);
+}
+async function cmdItems(url, limit, json) {
+    if (!url)
+        throw new UsageError('items requires a URL: siftctl items <url>');
+    const items = await fetchItems(url, limit);
+    if (json) {
+        out(items);
+        return;
+    }
+    for (const item of items) {
+        console.log(`- ${item.title}`);
+        if (item.link)
+            console.log(`  ${item.link}`);
+        console.log(`  id: ${item.itemId}`);
+    }
+}
+async function cmdMarkRead(itemId) {
+    if (!itemId)
+        throw new UsageError('mark read requires an item id: siftctl mark read <itemId>');
+    const lastSep = itemId.lastIndexOf('::');
+    if (lastSep === -1)
+        throw new UsageError('item id must contain "::" (feedId::guid)');
+    let feedId;
+    try {
+        feedId = decodeURIComponent(itemId.slice(0, lastSep));
+    }
+    catch {
+        throw new UsageError('item id has an invalid feed prefix');
+    }
+    const token = requireToken();
+    await push(token, { flags: [{ itemId, feedId, read: 1 }] });
+    console.log('Marked read.');
+}
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case 'pair':
+            await cmdPair(rest[0]);
+            return 0;
+        case 'status':
+            await cmdStatus(isFlag(rest, '--json'));
+            return 0;
+        case 'feeds': {
+            const json = isFlag(rest, '--json');
+            if (rest.length > 0)
+                throw new UsageError('feeds takes no arguments');
+            await cmdFeeds(json);
+            return 0;
+        }
+        case 'feed': {
+            const sub = rest[0];
+            if (sub === 'add') {
+                await cmdFeedAdd(rest[1]);
+                return 0;
+            }
+            if (sub === 'remove') {
+                const yes = isFlag(rest, '--yes');
+                await cmdFeedRemove(rest[1], yes);
+                return 0;
+            }
+            throw new UsageError('feed requires a subcommand: add or remove');
+        }
+        case 'items': {
+            const json = isFlag(rest, '--json');
+            let limit = 20;
+            const limitIdx = rest.indexOf('--limit');
+            if (limitIdx !== -1) {
+                const raw = rest[limitIdx + 1];
+                limit = Number(raw);
+                if (!Number.isInteger(limit) || limit < 1)
+                    throw new UsageError('--limit must be a positive integer');
+                rest.splice(limitIdx, 2);
+            }
+            await cmdItems(rest[0], limit, json);
+            return 0;
+        }
+        case 'mark':
+            if (rest[0] !== 'read')
+                throw new UsageError('mark requires: mark read <itemId>');
+            await cmdMarkRead(rest[1]);
+            return 0;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            console.log(USAGE);
+            return 0;
+        default:
+            throw new UsageError(`Unknown command: ${cmd}\n\n${USAGE}`);
+    }
+}
+export async function runCli(argv) {
+    try {
+        return await main(argv);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            console.error(`Usage: ${err.message}`);
+            return 2;
+        }
+        if (err instanceof ApiError) {
+            console.error(`Error: ${err.message}`);
+            return 1;
+        }
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    runCli(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/config.js

@@ -0,0 +1,30 @@
+import { homedir } from 'node:os';
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import path from 'node:path';
+export const DEFAULT_URL = 'https://sift.davegarvey.workers.dev';
+export function baseUrl() {
+    return (process.env.SIFTCTL_URL ?? DEFAULT_URL).replace(/\/+$/, '');
+}
+export function tokenPath() {
+    const home = process.env.SIFTCTL_HOME ?? path.join(homedir(), '.config');
+    return path.join(home, 'siftctl', 'token');
+}
+/** Token precedence: SIFTCTL_TOKEN env, then the config file. */
+export function readToken() {
+    const env = process.env.SIFTCTL_TOKEN;
+    if (env)
+        return env;
+    try {
+        const value = readFileSync(tokenPath(), 'utf8').trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeToken(token) {
+    const p = tokenPath();
+    mkdirSync(path.dirname(p), { recursive: true, mode: 0o700 });
+    writeFileSync(p, token + '\n', { mode: 0o600 });
+    chmodSync(p, 0o600);
+}

package/dist/fingerprint.js

@@ -0,0 +1,16 @@
+/** Crockford base32 alphabet (0-9 and A-Z minus I, L, O, U). */
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * Display fingerprint for a credential: SHA-256, first 20 bits rendered as
+ * 4 uppercase Crockford characters — identical to the Sift server's scheme,
+ * so `siftctl status` shows the same string as the Settings agents list.
+ */
+export async function tokenFingerprint(token) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token));
+    const bytes = new Uint8Array(digest);
+    const value = ((bytes[0] << 16) | (bytes[1] << 8) | bytes[2]) & 0xFFFFF;
+    return (CROCKFORD[(value >> 15) & 31] +
+        CROCKFORD[(value >> 10) & 31] +
+        CROCKFORD[(value >> 5) & 31] +
+        CROCKFORD[value & 31]);
+}

package/dist/items.js

@@ -0,0 +1,78 @@
+import { extractFromXml } from '@extractus/feed-extractor';
+/**
+ * Fetch and parse a feed, mirroring the Sift browser's item identity rules
+ * (src/feeds/parse.ts) so item IDs produced here match the flags the
+ * browser writes: guid ?? id, else `${link}|${published}`, else link.
+ */
+export async function fetchItems(feedUrl, limit) {
+    let res;
+    try {
+        res = await fetch(feedUrl, {
+            headers: { 'User-Agent': 'siftctl/0.1' },
+            redirect: 'follow',
+        });
+    }
+    catch {
+        throw new Error(`Failed to fetch feed: ${feedUrl}`);
+    }
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} fetching feed: ${feedUrl}`);
+    const xml = await res.text();
+    let data;
+    try {
+        data = extractFromXml(xml, {
+            descriptionMaxLen: 0,
+            getExtraEntryFields: (raw) => {
+                const entry = raw;
+                const rawGuid = entry['guid'] ?? entry['id'];
+                const link = typeof entry['link'] === 'string' ? entry['link'] : undefined;
+                const published = entry['pubDate'] ?? entry['published'] ?? entry['updated'];
+                let stableGuid;
+                if (typeof rawGuid === 'string' && rawGuid.length > 0) {
+                    stableGuid = rawGuid;
+                }
+                else if (link && typeof published === 'string') {
+                    stableGuid = `${link}|${published}`;
+                }
+                else if (link) {
+                    stableGuid = link;
+                }
+                const result = {};
+                if (stableGuid)
+                    result['_guid'] = stableGuid;
+                return result;
+            },
+        });
+    }
+    catch {
+        throw new Error(`Failed to parse feed XML: ${feedUrl}`);
+    }
+    if (!data)
+        throw new Error(`Failed to parse feed XML: ${feedUrl}`);
+    return (data['entries'] ?? [])
+        .map((entry) => mapEntry(entry, feedUrl))
+        .filter((i) => i !== null)
+        .slice(0, limit);
+}
+function mapEntry(entry, feedUrl) {
+    const extra = entry;
+    const guid = extra['_guid'] ?? entry.id ?? entry.link ?? '';
+    if (!guid)
+        return null;
+    const publishedAt = parseDate(entry.published);
+    const excerpt = (entry.description ?? '').slice(0, 500);
+    return {
+        title: entry.title ?? '(untitled)',
+        link: entry.link,
+        publishedAt,
+        excerpt,
+        guid,
+        itemId: `${encodeURIComponent(feedUrl)}::${guid}`,
+    };
+}
+function parseDate(value) {
+    if (!value)
+        return Date.now();
+    const t = Date.parse(value);
+    return Number.isNaN(t) ? Date.now() : t;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "siftctl",
+  "version": "0.1.0",
+  "description": "Control your Sift RSS subscriptions from the command line or an AI agent",
+  "type": "module",
+  "bin": {
+    "siftctl": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@extractus/feed-extractor": "^7.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}