@hwip/cli 0.0.1 → 0.1.1

package/dist/channel.d.ts

@@ -0,0 +1,67 @@
+import type { NotifyPayload } from './types.js';
+/**
+ * The part of a channel `GET /channels` returns that this CLI shows. The record
+ * also carries fields that are not for a terminal or a `--json` pipe (a
+ * webhook secret, the index tag), so the list is rebuilt from these and
+ * nothing else is passed along.
+ */
+export interface ChannelSummary {
+    channelId: string;
+    name: string;
+    description?: string;
+    isPublic: boolean;
+    subscriberCount: number;
+    ownerId: string;
+    /** Whether the account owns it, as the server says. Absent from a server that does not send it yet. */
+    isOwner?: boolean;
+    createdAt?: string;
+}
+/** The channels in a `GET /channels` answer; a row without an id or a name is dropped, not guessed. */
+export declare const parseChannels: (data: unknown) => ChannelSummary[];
+/**
+ * What `hwip channel list` prints. The server says per channel whether the
+ * account owns it (`isOwner`), and answers with the owned ones first. A server
+ * that does not send the field yet gives the rows no way to say so — an API key
+ * cannot learn its own user id — so such a row shows its owner and leaves the
+ * comparison to the person (the server refuses `notify --channel` for a channel
+ * the account does not own).
+ */
+export declare const channelLines: (channels: readonly ChannelSummary[]) => string[];
+export type ChannelRef = {
+    channelId: string;
+    name?: string;
+} | {
+    error: string;
+};
+/**
+ * Which channel `--channel <ref>` means. An id in the list wins; otherwise the
+ * name must match exactly one channel *the account owns* — a channel it only
+ * follows with the same name does not make the name ambiguous, and is never
+ * the target. Two owned channels with one name are refused rather than picked:
+ * a push to the wrong channel reaches strangers. An id the list does not hold is
+ * passed on as it is — the server decides whether it exists and is the account's.
+ *
+ * A server that does not say who owns what (`isOwner` absent on any row) leaves
+ * every name match a candidate, as before: ambiguity is then refused, and a
+ * channel the account does not own is refused by the server.
+ */
+export declare const resolveChannel: (channels: readonly ChannelSummary[], ref: string) => ChannelRef;
+export interface ChannelNotify {
+    ref: string;
+    payload: Omit<NotifyPayload, 'channelId'>;
+}
+/**
+ * The flags of `hwip notify --channel`, or what is wrong with them.
+ *
+ * A channel push is not the agent hook's push: the gate (`--auto`), the device
+ * and the session flags mean "this agent session", and none of them go to a
+ * channel — refusing them is better than dropping them silently, and the
+ * default title and body a hook gets from the branch name would publish a
+ * project name to subscribers.
+ */
+export declare const parseChannelNotify: (args: Readonly<Record<string, string | boolean>>) => ChannelNotify | {
+    error: string;
+};
+/** Printed to stderr on every channel push: whatever the account's end-to-end setting, this one is readable by the server. */
+export declare const PLAINTEXT_NOTE = "Channel pushes are sent as plain text, not sealed \u2014 the server can read this one even with end-to-end encryption on.";
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAINTEXT_NOTE = exports.parseChannelNotify = exports.resolveChannel = exports.channelLines = exports.parseChannels = void 0;
+const text = (value) => (typeof value === 'string' && value ? value : undefined);
+/** The channels in a `GET /channels` answer; a row without an id or a name is dropped, not guessed. */
+const parseChannels = (data) => {
+    if (!Array.isArray(data))
+        return [];
+    const channels = [];
+    for (const raw of data) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const row = raw;
+        const channelId = text(row.channelId);
+        const name = text(row.name);
+        if (!channelId || !name)
+            continue;
+        const description = text(row.description);
+        const createdAt = text(row.createdAt);
+        channels.push({
+            channelId,
+            name,
+            ...(description && { description }),
+            isPublic: row.isPublic === true,
+            subscriberCount: typeof row.subscriberCount === 'number' ? row.subscriberCount : 0,
+            ownerId: text(row.ownerId) ?? '',
+            ...(typeof row.isOwner === 'boolean' && { isOwner: row.isOwner }),
+            ...(createdAt && { createdAt }),
+        });
+    }
+    return channels;
+};
+exports.parseChannels = parseChannels;
+/**
+ * What `hwip channel list` prints. The server says per channel whether the
+ * account owns it (`isOwner`), and answers with the owned ones first. A server
+ * that does not send the field yet gives the rows no way to say so — an API key
+ * cannot learn its own user id — so such a row shows its owner and leaves the
+ * comparison to the person (the server refuses `notify --channel` for a channel
+ * the account does not own).
+ */
+const channelLines = (channels) => {
+    if (channels.length === 0)
+        return ['No channels.'];
+    const idWidth = Math.max(...channels.map((c) => c.channelId.length));
+    const nameWidth = Math.max(...channels.map((c) => c.name.length));
+    const lines = channels.map((c) => {
+        const subs = `${c.subscriberCount} ${c.subscriberCount === 1 ? 'subscriber' : 'subscribers'}`;
+        const role = c.isOwner === true ? 'yours' : c.isOwner === false ? 'following' : c.ownerId ? `owner ${c.ownerId.slice(0, 8)}` : 'owner unknown';
+        return `  ${c.channelId.padEnd(idWidth)}  ${c.name.padEnd(nameWidth)}  ${c.isPublic ? 'public ' : 'private'}  ${subs}  ${role}`;
+    });
+    lines.push('', 'Only an owner can send to a channel.');
+    return lines;
+};
+exports.channelLines = channelLines;
+/**
+ * Which channel `--channel <ref>` means. An id in the list wins; otherwise the
+ * name must match exactly one channel *the account owns* — a channel it only
+ * follows with the same name does not make the name ambiguous, and is never
+ * the target. Two owned channels with one name are refused rather than picked:
+ * a push to the wrong channel reaches strangers. An id the list does not hold is
+ * passed on as it is — the server decides whether it exists and is the account's.
+ *
+ * A server that does not say who owns what (`isOwner` absent on any row) leaves
+ * every name match a candidate, as before: ambiguity is then refused, and a
+ * channel the account does not own is refused by the server.
+ */
+const resolveChannel = (channels, ref) => {
+    const known = channels.every((c) => typeof c.isOwner === 'boolean');
+    const byId = channels.find((c) => c.channelId === ref);
+    if (byId) {
+        if (known && !byId.isOwner)
+            return { error: `you follow "${byId.name}" (${byId.channelId}) but do not own it — only the owner can send to a channel` };
+        return { channelId: byId.channelId, name: byId.name };
+    }
+    const named = channels.filter((c) => c.name === ref);
+    const byName = known ? named.filter((c) => c.isOwner) : named;
+    if (byName.length === 1)
+        return { channelId: byName[0].channelId, name: byName[0].name };
+    if (byName.length > 1) {
+        const ids = byName.map((c) => c.channelId).join(', ');
+        return { error: `${byName.length} channels are named "${ref}" (${ids}) — use the channelId` };
+    }
+    if (known && named.length > 0) {
+        return { error: `you follow "${ref}" (${named.map((c) => c.channelId).join(', ')}) but do not own a channel by that name — only the owner can send to a channel` };
+    }
+    if (/^ch_/.test(ref))
+        return { channelId: ref };
+    return { error: `no channel named "${ref}" — 'hwip channel list' shows the channels; use a channelId or an exact name` };
+};
+exports.resolveChannel = resolveChannel;
+const PRIORITIES = ['low', 'normal', 'high', 'urgent'];
+const TYPES = ['note', 'link', 'file', 'hook'];
+/**
+ * The flags of `hwip notify --channel`, or what is wrong with them.
+ *
+ * A channel push is not the agent hook's push: the gate (`--auto`), the device
+ * and the session flags mean "this agent session", and none of them go to a
+ * channel — refusing them is better than dropping them silently, and the
+ * default title and body a hook gets from the branch name would publish a
+ * project name to subscribers.
+ */
+const parseChannelNotify = (args) => {
+    const ref = args.channel;
+    if (typeof ref !== 'string' || !ref.trim())
+        return { error: '--channel needs a channelId or a channel name' };
+    for (const flag of ['auto', 'device', 'session']) {
+        if (args[flag] !== undefined)
+            return { error: `--${flag} is for agent sessions and cannot be combined with --channel` };
+    }
+    const title = typeof args.title === 'string' ? args.title : undefined;
+    const body = typeof args.body === 'string' ? args.body : undefined;
+    if (!title && !body)
+        return { error: 'a channel push needs --title or --body' };
+    const type = typeof args.type === 'string' ? args.type : 'hook';
+    if (!TYPES.includes(type))
+        return { error: `--type must be one of ${TYPES.join(', ')}` };
+    const priority = typeof args.priority === 'string' ? args.priority : undefined;
+    if (priority && !PRIORITIES.includes(priority)) {
+        return { error: `--priority must be one of ${PRIORITIES.join(', ')}` };
+    }
+    const url = typeof args.url === 'string' ? args.url : undefined;
+    return {
+        ref: ref.trim(),
+        payload: {
+            ...(title && { title }),
+            ...(body && { body }),
+            ...(url && { url }),
+            type: type,
+            ...(priority && { priority: priority }),
+        },
+    };
+};
+exports.parseChannelNotify = parseChannelNotify;
+/** Printed to stderr on every channel push: whatever the account's end-to-end setting, this one is readable by the server. */
+exports.PLAINTEXT_NOTE = 'Channel pushes are sent as plain text, not sealed — the server can read this one even with end-to-end encryption on.';

package/dist/check-update.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How to update. A global install is what `hwip` on PATH runs — `npx @hwip/cli
+ * install` only re-ran setup from a fresh download and left it as it was —
+ * and the daemon keeps the old build until it restarts.
+ */
+export declare const UPDATE_HINT = "npm i -g @hwip/cli \u2014 the next `hwip cc` restarts the listener on it (or run: hwip listener --restart)";
+/** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
+export declare const isNewer: (latest: string, current: string) => boolean;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+export declare const installedMcpServerVersion: () => string | null;
+/**
+ * One line for `hwip cc` when a newer CLI is out, or undefined. Asks npm at
+ * most once a day, briefly, and remembers the answer; an offline day keeps
+ * the last known version rather than asking again on every launch.
+ */
+export declare const cachedUpdateNotice: (deps?: {
+    now?: () => number;
+    latest?: () => Promise<string | null>;
+    file?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<string | undefined>;
+export declare const handleCheckUpdate: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=check-update.d.ts.map

package/dist/check-update.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleCheckUpdate = exports.cachedUpdateNotice = exports.installedMcpServerVersion = exports.isNewer = exports.UPDATE_HINT = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const private_files_js_1 = require("./private-files.js");
+const config_js_1 = require("./config.js");
+const args_js_1 = require("./args.js");
+// Compares installed versions against the npm registry. Pure read-only —
+// never installs anything; just tells the user if a newer release exists.
+const PACKAGES = ['@hwip/cli', '@hwip/mcp-server'];
+/**
+ * How to update. A global install is what `hwip` on PATH runs — `npx @hwip/cli
+ * install` only re-ran setup from a fresh download and left it as it was —
+ * and the daemon keeps the old build until it restarts.
+ */
+exports.UPDATE_HINT = 'npm i -g @hwip/cli — the next `hwip cc` restarts the listener on it (or run: hwip listener --restart)';
+/** Fetch the `latest` dist-tag version for a package from the npm registry. */
+const fetchLatest = async (pkg, timeoutMs = 10_000) => {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const json = await res.json();
+        return json.version ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
+const isNewer = (latest, current) => {
+    const norm = (v) => v.replace(/^v/, '').split('-')[0].split('.').map((n) => parseInt(n, 10) || 0);
+    const [a, b] = [norm(latest), norm(current)];
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+};
+exports.isNewer = isNewer;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+const installedMcpServerVersion = () => {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)(require.resolve('@hwip/mcp-server/package.json'), 'utf-8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.installedMcpServerVersion = installedMcpServerVersion;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const updateCacheFile = () => (0, path_1.join)((0, os_1.homedir)(), '.hwip', 'update-check.json');
+const readUpdateCache = (file) => {
+    try {
+        const data = JSON.parse((0, fs_1.readFileSync)(file, 'utf-8'));
+        return typeof data.checkedAt === 'number' ? { checkedAt: data.checkedAt, latest: data.latest ?? null } : null;
+    }
+    catch {
+        return null;
+    }
+};
+const writeUpdateCache = (file, cache) => {
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, path_1.dirname)(file));
+        (0, fs_1.writeFileSync)(file, JSON.stringify(cache) + '\n');
+        (0, private_files_js_1.handBackToSudoUser)(file);
+    }
+    catch { /* a notice is not worth failing over */ }
+};
+/**
+ * One line for `hwip cc` when a newer CLI is out, or undefined. Asks npm at
+ * most once a day, briefly, and remembers the answer; an offline day keeps
+ * the last known version rather than asking again on every launch.
+ */
+const cachedUpdateNotice = async (deps = {}) => {
+    const now = (deps.now ?? Date.now)();
+    const file = deps.file ?? updateCacheFile();
+    // CI and anyone who opts out never reach the registry from `hwip cc`.
+    const env = deps.env ?? process.env;
+    if (env.CI || env.HWIP_NO_UPDATE_CHECK)
+        return undefined;
+    let cache = readUpdateCache(file);
+    // A checkedAt in the future (clock skew, a hand-edited file) counts as stale.
+    if (!cache || now - cache.checkedAt >= DAY_MS || cache.checkedAt > now) {
+        const latest = await (deps.latest ?? (() => fetchLatest('@hwip/cli', 1_500)))();
+        cache = { checkedAt: now, latest: latest ?? cache?.latest ?? null };
+        writeUpdateCache(file, cache);
+    }
+    if (!cache.latest || !(0, exports.isNewer)(cache.latest, config_js_1.VERSION))
+        return undefined;
+    return `hwip: v${cache.latest} is out (this is v${config_js_1.VERSION}). Update: ${exports.UPDATE_HINT}`;
+};
+exports.cachedUpdateNotice = cachedUpdateNotice;
+const handleCheckUpdate = async (args) => {
+    const isJson = (0, args_js_1.flagOn)(args, 'json');
+    // Both installed versions are knowable: the CLI's from its own
+    // package.json, and mcp-server's because `hwip mcp` runs it in-process,
+    // which makes it a dependency rather than an npx download of unknown age.
+    // Two unrelated registry round-trips — awaiting them one after the other
+    // doubled the command's wall time for nothing.
+    const latestVersions = await Promise.all(PACKAGES.map((pkg) => fetchLatest(pkg)));
+    // A fresh answer is as good as the daily one `hwip cc` would fetch.
+    if (latestVersions[0])
+        writeUpdateCache(updateCacheFile(), { checkedAt: Date.now(), latest: latestVersions[0] });
+    const results = PACKAGES.map((pkg, i) => {
+        const latest = latestVersions[i];
+        const current = pkg === '@hwip/cli' ? config_js_1.VERSION : (0, exports.installedMcpServerVersion)();
+        return { pkg, current, latest, outdated: !!(latest && current && (0, exports.isNewer)(latest, current)) };
+    });
+    if (isJson) {
+        console.log(JSON.stringify({ results }, null, 2));
+        return 0;
+    }
+    console.log('\n  Hwip — update check\n');
+    let anyOutdated = false;
+    for (const r of results) {
+        if (!r.latest) {
+            console.log(`    ?  ${r.pkg}: could not reach npm registry`);
+            continue;
+        }
+        if (r.current === null) {
+            console.log(`    •  ${r.pkg}: latest is v${r.latest}`);
+        }
+        else if (r.outdated) {
+            anyOutdated = true;
+            console.log(`    ⬆  ${r.pkg}: v${r.current} → v${r.latest} (update available)`);
+        }
+        else {
+            console.log(`    ✓  ${r.pkg}: v${r.current} (up to date)`);
+        }
+    }
+    if (anyOutdated) {
+        console.log(`\n  Update with: ${exports.UPDATE_HINT}\n`);
+    }
+    else {
+        console.log('');
+    }
+    return 0;
+};
+exports.handleCheckUpdate = handleCheckUpdate;

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map