@kud/incidents-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erwann Mest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# incidents-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Which of the services you depend on are declaring trouble right now: vendor status pages in one terminal view.
+
+It reads each vendor's own status page, worst first, and tells you what they have **declared**. A green row is not proof your calls work; a page it cannot read is shown as `? unreadable` and counts as not green, never as fine.
+
+## Install
+
+```sh
+npm install -g @kud/incidents-cli
+```
+
+Node 22 or later.
+
+## Use
+
+| Command                    | What it does                                                             |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `incidents`                | Interactive view: live list, worst first, rows fill in as they answer    |
+| `incidents <service>`      | Interactive view opened on that service's detail                         |
+| `incidents list [service]` | One-shot static output: the overview, or one service's detail            |
+| `incidents services`       | One service per line: id, name, aliases (comma-separated), tab-separated |
+
+Keys in the interactive view: `↑↓` or `j k` move, `⏎` opens a service, `esc` or `⌫` goes back, `r` refreshes, `q` quits.
+
+Add `--json` to any form for JSON records. With no TTY on stdin or stdout, or `CI` set, every form falls back to the static output (or JSON), so pipes, `$(...)` and cron never hang.
+
+### Exit codes
+
+| Code | Meaning                                                     |
+| ---- | ----------------------------------------------------------- |
+| 0    | All clear (maintenance and manual-link rows count as clear) |
+| 1    | Something is degraded, or a page could not be read          |
+| 2    | Usage or configuration error                                |
+
+The interactive view exits 0 on quit.
+
+## Configuration
+
+`${XDG_CONFIG_HOME:-~/.config}/incidents/config.yml`, then every `config.d/*.yml` merged over it by service id, in lexical order. `INCIDENTS_CONFIG=<file>` replaces both.
+
+```yaml
+timeout: 4000 # milliseconds per request, default 4000
+services:
+  github: {} # take the built-in entry as it is
+  aws:
+    regions: [us-east-1, us-west-2] # override fields of a built-in entry
+  npm:
+    enabled: false # drop one
+  acme:
+    name: Acme # a full entry defines a new service
+    kind: statuspage
+    url: https://status.acme.example
+    aliases: [ac]
+```
+
+With no config file the defaults are `github`, `npm`, `cloudflare` and `claude`, and one muted line names the config path.
+
+`list`, `services` and `help` are reserved words and cannot be a service id or alias; loading fails with exit 2 and a message naming the file and the id. Any other configuration error also exits 2.
+
+### Built-in services
+
+`github`, `claude`, `openai`, `vercel`, `cloudflare`, `npm`, `docker`, `figma`, `linear`, `notion`, `gandi`, `todoist`, `bluesky`, `jira`, `confluence`, `bitbucket`, `sentry`, `harness`, `datadog`, `slack`, `aws`.
+
+### Kinds
+
+| Kind         | Reads                                                                                                    |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `statuspage` | Atlassian Statuspage v2: `<url>/api/v2/summary.json`, history from `<url>/history.rss`                   |
+| `rss`        | An incident feed only. Current state comes from how recent the last post is (`window`, hours, default 6) |
+| `slack`      | Slack's status API                                                                                       |
+| `aws`        | AWS Health's public event list; `regions` narrows it, global events always count                         |
+| `link`       | No machine-readable page: the row points at `url` and claims nothing                                     |
+
+Other fields: `aliases`, `note` (printed under the detail), `timeout` (per service, milliseconds).
+
+## JSON records
+
+`incidents list --json` prints an array, worst first. `incidents list <service> --json` prints one record, with its history loaded.
+
+```json
+{
+  "id": "github",
+  "name": "GitHub",
+  "url": "https://www.githubstatus.com",
+  "kind": "statuspage",
+  "fetched": "ok",
+  "indicator": "minor",
+  "description": "Partially Degraded Service",
+  "components": [{ "name": "API", "status": "degraded_performance" }],
+  "active": [
+    {
+      "title": "Elevated API errors",
+      "link": "https://stspg.io/abc",
+      "date": "2026-01-01T10:00:00Z",
+      "impact": "minor"
+    }
+  ],
+  "recent": [{ "title": "Earlier incident", "link": "https://…", "date": "…" }],
+  "historyLoaded": true,
+  "historyFailed": false,
+  "note": ""
+}
+```
+
+| Field           | Meaning                                                                                                   |
+| --------------- | --------------------------------------------------------------------------------------------------------- |
+| `fetched`       | `ok`, or `failed` when the page could not be read                                                         |
+| `indicator`     | `critical`, `major`, `unknown`, `minor`, `maintenance`, `none` or `link`, worst first in that order       |
+| `components`    | Components with their raw vendor status; `operational` ones are included                                  |
+| `active`        | Incidents open now                                                                                        |
+| `recent`        | Past incidents, newest first; empty until history is loaded                                               |
+| `historyLoaded` | `true` once history was requested for this record                                                         |
+| `historyFailed` | `true` when the history feed could not be read, so an empty `recent` is not a claim that nothing happened |
+
+`unknown` means the page could not be read. It sorts above every healthy row and fails the exit code.
+
+## Environment
+
+| Variable           | Effect                                             |
+| ------------------ | -------------------------------------------------- |
+| `INCIDENTS_CONFIG` | A single config file, replacing the default lookup |
+| `NO_COLOR`         | Plain output                                       |
+| `CI`               | Forces the static output                           |
+
+Requests identify themselves as `incidents-cli/<version>`.
+
+## Development
+
+```sh
+npm install
+npm run dev -- --mock
+npm test
+```
+
+`--mock` swaps every data source for fixtures; `--screen <name>` opens straight on a screen (`--screen list` prints the names).
+
+## Licence
+
+MIT

package/dist/bin/incidents.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { list, open, run, services } from "../src/cli.js";
+const resolveVersion = () => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            return JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+        }
+        catch {
+            dir = dirname(dir);
+        }
+    }
+    return "0.0.0";
+};
+const version = resolveVersion();
+const program = new Command();
+program
+    .name("incidents")
+    .description("Which of the services you depend on are declaring trouble right now")
+    .version(version)
+    .option("--json", "print JSON records, never the interactive view", false)
+    .option("--mock", "use built-in fixtures instead of live status pages", false)
+    .option("--screen <name>", "open directly on a screen (`list` prints them)")
+    .argument("[service]", "open the interactive view on one service")
+    .showHelpAfterError()
+    .action((word, flags) => run(() => open(word, flags, version)));
+program
+    .command("list")
+    .argument("[service]", "one service's detail instead of the overview")
+    .description("print the status once and exit: 0 all clear, 1 degraded or unreadable")
+    .action((word, _flags, command) => run(() => list(word, command.optsWithGlobals(), version)));
+program
+    .command("services")
+    .description("print configured service ids and aliases, one per line")
+    .action((_flags, command) => run(() => services(command.optsWithGlobals(), version)));
+await program.parseAsync();

package/dist/src/cli.js

@@ -0,0 +1,106 @@
+import { loadConfig, defaultsNote } from "./config.js";
+import { ConfigError, exitCode, resolveService, worstFirst, } from "./core/index.js";
+import { canBeInteractive } from "./mode.js";
+import { renderDetail, renderOverview } from "./render.js";
+import { liveSource, mockSource } from "./source.js";
+export const SCREENS = ["overview", "detail"];
+const makeContext = (flags, version) => {
+    const source = flags.mock
+        ? mockSource()
+        : (() => {
+            const config = loadConfig();
+            return liveSource(config, version, defaultsNote(config));
+        })();
+    return {
+        source,
+        registry: Object.fromEntries(source.services.map((s) => [s.id, s])),
+    };
+};
+const write = (text) => {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+};
+const fail = (message) => {
+    process.stderr.write(`incidents: ${message}\n`);
+    return 2;
+};
+const pretty = () => {
+    const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+    return { color, links: color };
+};
+const unknownService = (word, registry) => fail(`no service '${word}'. Known: ${Object.keys(registry).sort().join(", ")}`);
+const classic = async (word, flags, { source, registry }) => {
+    if (word !== undefined) {
+        const service = resolveService(registry, word);
+        if (!service)
+            return unknownService(word, registry);
+        const record = await source.readDetail(service, {});
+        write(flags.json
+            ? JSON.stringify(record, null, 2)
+            : renderDetail(record, { ...pretty(), note: source.note }));
+        return exitCode([record]);
+    }
+    if (source.services.length === 0) {
+        write("No services configured.");
+        return 0;
+    }
+    const records = worstFirst(await source.readAll({}));
+    write(flags.json
+        ? JSON.stringify(records, null, 2)
+        : renderOverview(records, { ...pretty(), note: source.note }));
+    return exitCode(records);
+};
+const interactive = async (word, flags, { source, registry }) => {
+    const target = word !== undefined ? resolveService(registry, word) : undefined;
+    if (word !== undefined && !target)
+        return unknownService(word, registry);
+    const initialDetail = target?.id ??
+        (flags.screen === "detail" ? source.services[0]?.id : undefined);
+    const { render } = await import("ink");
+    const { createElement } = await import("react");
+    const { App } = await import("./ui/app.js");
+    const app = render(createElement(App, { source, initialDetail }));
+    await app.waitUntilExit();
+    return 0;
+};
+export const open = async (word, flags, version) => {
+    if (flags.screen === "list") {
+        write(SCREENS.join("\n"));
+        return 0;
+    }
+    if (flags.screen !== undefined && !SCREENS.includes(flags.screen))
+        return fail(`no screen '${flags.screen}'. Known: ${SCREENS.join(", ")}`);
+    const context = makeContext(flags, version);
+    const tty = canBeInteractive({
+        stdinTTY: Boolean(process.stdin.isTTY),
+        stdoutTTY: Boolean(process.stdout.isTTY),
+        env: process.env,
+        json: Boolean(flags.json),
+    });
+    return tty
+        ? interactive(word, flags, context)
+        : classic(word ??
+            (flags.screen === "detail"
+                ? context.source.services[0]?.id
+                : undefined), flags, context);
+};
+export const list = async (word, flags, version) => classic(word, flags, makeContext(flags, version));
+export const services = (flags, version) => {
+    const { source } = makeContext(flags, version);
+    write(source.services
+        .map((s) => [s.id, s.name, s.aliases.join(",")].join("\t"))
+        .join("\n"));
+    return 0;
+};
+export const run = async (action) => {
+    try {
+        process.exitCode = await action();
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            process.exitCode = fail(error.message);
+        else {
+            process.stderr.write(`incidents: ${error.message}\n`);
+            process.exitCode = 1;
+        }
+    }
+};

package/dist/src/config.js

@@ -0,0 +1,75 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { load } from "js-yaml";
+import { ConfigError, DEFAULT_IDS, RESERVED_WORDS, DEFAULT_TIMEOUT_MS, mergeServices, selectServices, } from "./core/index.js";
+const configHome = (env) => join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "incidents");
+const readFile = (path) => {
+    try {
+        const parsed = load(readFileSync(path, "utf8"));
+        if (parsed === undefined || parsed === null)
+            return {};
+        if (typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("expected a mapping at the top level");
+        return parsed;
+    }
+    catch (error) {
+        throw new ConfigError(`${path}: ${error.message}`);
+    }
+};
+const rejectReserved = (path, services) => {
+    for (const [id, fields] of Object.entries(services)) {
+        const aliases = Array.isArray(fields?.aliases) ? fields.aliases : [];
+        const word = [id, ...aliases]
+            .map(String)
+            .find((w) => RESERVED_WORDS.includes(w.toLowerCase()));
+        if (word)
+            throw new ConfigError(`${path}: service '${id}' uses the reserved word '${word}'`);
+    }
+};
+const filesFor = (env) => {
+    if (env.INCIDENTS_CONFIG) {
+        if (!existsSync(env.INCIDENTS_CONFIG))
+            throw new ConfigError(`INCIDENTS_CONFIG: no file at ${env.INCIDENTS_CONFIG}`);
+        return [env.INCIDENTS_CONFIG];
+    }
+    const dir = configHome(env);
+    const main = join(dir, "config.yml");
+    const dropIns = join(dir, "config.d");
+    return [
+        ...(existsSync(main) ? [main] : []),
+        ...(existsSync(dropIns)
+            ? readdirSync(dropIns)
+                .filter((f) => f.endsWith(".yml"))
+                .sort()
+                .map((f) => join(dropIns, f))
+            : []),
+    ];
+};
+export const defaultConfigPath = (env = process.env) => env.INCIDENTS_CONFIG || join(configHome(env), "config.yml");
+export const loadConfig = (env = process.env) => {
+    const files = filesFor(env);
+    if (files.length === 0)
+        return {
+            services: selectServices(Object.fromEntries(DEFAULT_IDS.map((id) => [id, {}]))),
+            timeout: DEFAULT_TIMEOUT_MS,
+            source: "default",
+            path: defaultConfigPath(env),
+        };
+    const parsed = files.map(readFile);
+    parsed.forEach((file, i) => rejectReserved(files[i], file.services ?? {}));
+    const selected = parsed.reduce((acc, file) => mergeServices(acc, file.services ?? {}), {});
+    const timeout = parsed
+        .map((f) => f.timeout)
+        .filter((t) => typeof t === "number")
+        .at(-1) ?? DEFAULT_TIMEOUT_MS;
+    return {
+        services: selectServices(selected, undefined, files.join(", ")),
+        timeout,
+        source: "file",
+        path: files[0],
+    };
+};
+export const defaultsNote = (config) => config.source === "default"
+    ? `No config at ${config.path.replace(homedir(), "~")}: showing ${DEFAULT_IDS.join(", ")}.`
+    : null;

package/dist/src/core/adapters.js

@@ -0,0 +1,58 @@
+import { decodeUtf16, fromAws, fromFeed, fromSlack, fromStatuspageSummary, newestFirst, parseRss, } from "./parse.js";
+export const DEFAULT_TIMEOUT_MS = 4000;
+const fetchWith = async (url, service, opts) => {
+    const timeout = AbortSignal.timeout(service.timeout ?? opts.timeout ?? DEFAULT_TIMEOUT_MS);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+    const res = await (opts.fetch ?? fetch)(url, {
+        signal,
+        headers: opts.userAgent ? { "user-agent": opts.userAgent } : {},
+    });
+    if (!res.ok)
+        throw new Error(`${res.status} from ${url}`);
+    return res;
+};
+const json = async (url, service, opts) => (await fetchWith(url, service, opts)).json();
+const text = async (url, service, opts) => (await fetchWith(url, service, opts)).text();
+const readHistory = async (url, service, opts) => {
+    try {
+        return {
+            recent: newestFirst(parseRss(await text(url, service, opts))),
+            historyFailed: false,
+        };
+    }
+    catch (error) {
+        if (opts.signal?.aborted)
+            throw error;
+        return { recent: [], historyFailed: true };
+    }
+};
+export const ADAPTERS = {
+    statuspage: async (service, opts) => {
+        const base = (service.url ?? "").replace(/\/$/, "");
+        const [summary, history] = await Promise.all([
+            json(`${base}/api/v2/summary.json`, service, opts),
+            opts.detail
+                ? readHistory(`${base}/history.rss`, service, opts)
+                : { recent: [], historyFailed: false },
+        ]);
+        return { ...fromStatuspageSummary(summary), ...history };
+    },
+    rss: async (service, opts) => {
+        const items = newestFirst(parseRss(await text(service.feed ?? "", service, opts)));
+        return {
+            ...fromFeed(items, { windowHours: service.window ?? 6 }),
+            recent: items,
+        };
+    },
+    slack: async (service, opts) => fromSlack(await json("https://slack-status.com/api/v2.0.0/current", service, opts)),
+    aws: async (service, opts) => {
+        const res = await fetchWith("https://health.aws.amazon.com/public/currentevents", service, opts);
+        return fromAws(JSON.parse(decodeUtf16(await res.arrayBuffer())), {
+            regions: service.regions,
+        });
+    },
+    link: async () => ({
+        indicator: "link",
+        description: "No machine-readable status",
+    }),
+};

package/dist/src/core/age.js

@@ -0,0 +1,33 @@
+export const age = (ms) => {
+    const hours = Math.floor(ms / 3_600_000);
+    if (hours < 1)
+        return `${Math.max(1, Math.floor(ms / 60_000))}m`;
+    if (hours < 48)
+        return hours < 10 && ms % 3_600_000 >= 60_000
+            ? `${hours}h ${Math.floor((ms % 3_600_000) / 60_000)}m`
+            : `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+};
+export const ageOf = (raw, now = Date.now()) => {
+    const ms = now - new Date(raw).getTime();
+    return raw && !Number.isNaN(ms) ? age(Math.max(0, ms)) : "";
+};
+export const formatWhen = (raw) => {
+    const date = new Date(raw);
+    return Number.isNaN(date.getTime())
+        ? raw
+        : date.toLocaleString(undefined, {
+            day: "numeric",
+            month: "short",
+            hour: "2-digit",
+            minute: "2-digit",
+        });
+};
+export const whenLabel = (raw, now = Date.now()) => {
+    const label = ageOf(raw, now);
+    if (!label)
+        return raw ? formatWhen(raw) : "";
+    return label.endsWith("d") && parseInt(label, 10) >= 7
+        ? formatWhen(raw)
+        : `${label} ago`;
+};

package/dist/src/core/catalogue.js

@@ -0,0 +1,102 @@
+export const CATALOGUE = {
+    github: {
+        name: "GitHub",
+        kind: "statuspage",
+        url: "https://www.githubstatus.com",
+        aliases: ["gh"],
+        note: "A green board is not a promise your calls succeed: scattered 5xx errors never reach an incident.",
+    },
+    claude: {
+        name: "Claude",
+        kind: "statuspage",
+        url: "https://status.claude.com",
+        aliases: ["anthropic"],
+    },
+    openai: {
+        name: "OpenAI",
+        kind: "statuspage",
+        url: "https://status.openai.com",
+    },
+    vercel: {
+        name: "Vercel",
+        kind: "statuspage",
+        url: "https://www.vercel-status.com",
+    },
+    cloudflare: {
+        name: "Cloudflare",
+        kind: "statuspage",
+        url: "https://www.cloudflarestatus.com",
+        aliases: ["cf"],
+    },
+    npm: { name: "npm", kind: "statuspage", url: "https://status.npmjs.org" },
+    docker: {
+        name: "Docker",
+        kind: "statuspage",
+        url: "https://www.dockerstatus.com",
+    },
+    figma: { name: "Figma", kind: "statuspage", url: "https://status.figma.com" },
+    linear: {
+        name: "Linear",
+        kind: "statuspage",
+        url: "https://linearstatus.com",
+    },
+    notion: {
+        name: "Notion",
+        kind: "statuspage",
+        url: "https://www.notion-status.com",
+    },
+    gandi: { name: "Gandi", kind: "statuspage", url: "https://status.gandi.net" },
+    todoist: {
+        name: "Todoist",
+        kind: "rss",
+        url: "https://status.todoist.net",
+        feed: "https://status.todoist.net/history.rss",
+    },
+    bluesky: {
+        name: "Bluesky",
+        kind: "rss",
+        url: "https://status.bsky.app",
+        feed: "https://status.bsky.app/history.rss",
+        aliases: ["bsky"],
+    },
+    jira: {
+        name: "Jira",
+        kind: "statuspage",
+        url: "https://jira-software.status.atlassian.com",
+    },
+    confluence: {
+        name: "Confluence",
+        kind: "statuspage",
+        url: "https://confluence.status.atlassian.com",
+    },
+    bitbucket: {
+        name: "Bitbucket",
+        kind: "statuspage",
+        url: "https://bitbucket.status.atlassian.com",
+    },
+    sentry: {
+        name: "Sentry",
+        kind: "statuspage",
+        url: "https://status.sentry.io",
+    },
+    harness: {
+        name: "Harness",
+        kind: "statuspage",
+        url: "https://status.harness.io",
+    },
+    datadog: {
+        name: "Datadog",
+        kind: "rss",
+        url: "https://status.datadoghq.com",
+        feed: "https://status.datadoghq.com/history.rss",
+        aliases: ["dd"],
+    },
+    slack: { name: "Slack", kind: "slack", url: "https://slack-status.com" },
+    aws: {
+        name: "AWS",
+        kind: "aws",
+        url: "https://health.aws.amazon.com/health/status",
+        note: "Every region counts unless `regions` narrows it; global events always do.",
+    },
+};
+export const DEFAULT_IDS = ["github", "npm", "cloudflare", "claude"];

package/dist/src/core/index.js

@@ -0,0 +1,8 @@
+export * from "./adapters.js";
+export * from "./age.js";
+export * from "./catalogue.js";
+export * from "./parse.js";
+export * from "./read.js";
+export * from "./registry.js";
+export * from "./severity.js";
+export * from "./types.js";