astreus-cli 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## 0.4.0 — unreleased
+
+- Renamed: the package is now `astreus-cli` (`npm install -g astreus-cli`) and the
+  command is `astreus`. It replaces `prometheus-terminal` and its `prom`
+  command; every subcommand and flag is unchanged.
+- `ASTREUS_API_KEY`, `ASTREUS_BASE_URL` and `ASTREUS_CONFIG_DIR` replace the
+  `PROMETHEUS_*` variables, which are still read when the new ones are unset.
+- The config file moves to `~/.config/astreus/config.json`; a key saved by
+  `prometheus-terminal` in `~/.config/prometheus` keeps working until the next
+  `astreus login` or `astreus logout` writes the new file.
+- Default API origin is `https://astreus.ai`.
+- New: `astreus transcript-search <words>` (full-text search over every
+  transcript; `--summary` for counts by quarter and company) and
+  `astreus mentioned-by <id>` (where other companies name this one).
+- New: `astreus government <iso> [view]`, `astreus executive-orders <iso>`,
+  `astreus officials <iso>` (`--changes`, `--schedule`), `astreus awards <id>`
+  (federal awards) and `astreus regulation <id>`.
+- `astreus commodities --fundamentals` (EIA-style supply series),
+  `astreus narratives --facets`, and `astreus debt --instrument <uuid>` now
+  works without a company id.
+
+## 0.3.0 — unreleased
+
+(0.2.0 was never published; its changes ship here.)
+
+- `prom coverage`: what Prometheus holds, market by market — companies, history
+  start, completeness and the share of reporting periods held per data type —
+  from the public `GET /api/v1/landing/coverage`. No key needed.
+- `prom as-filed`: the statement exactly as the company filed it — every
+  caption it ever printed, one column per period, across the whole history
+  (`-s is|ci|bs|bsp|cf|eq|all`, `-q` / `--semiannual`, `--ytd` for the
+  cumulative year-to-date column as printed, `--vintage original|latest`,
+  `--documents` for the filings the grid was read from). Distinct from
+  `prom financials --as-reported`, which is one filing's XBRL tree.
+- `prom note-tables`, `prom note-table`, `prom note-series`: the tables inside
+  the notes to the financial statements — a company's families and one
+  family's gated tables (`--held` shows what a quality gate held, and why),
+  one table cell by cell with its gate verdicts and the filing behind it, and
+  one family as a time series across filings with every point cited (`*` read
+  from a later filing's comparative column, `~` restated by a later filing).
+- Fixed: `-q` reaches the command it belongs to. The global quiet flag was
+  `-q, --quiet`, and commander resolved it before the subcommand saw it, so
+  `prom financials NVDA -q` silently returned annual periods and
+  `prom news -q …` dropped the search. Quiet is `--quiet` only; `-q` is
+  `--quarterly` on `financials`, `fact-source`, `as-filed` and `note-series`,
+  and `--search` on `news`.
+- `prom fact-source --basis` names its values as the API does: `individual`
+  (default, the discrete period) and `as_reported` (the cumulative
+  year-to-date column) — a period basis, not a vintage. `restated` is still
+  accepted as an alias of the default.
+- All 95 public operations are accounted for: 89 reachable from a command, six
+  UI-only helpers (sparklines, tab presence, transcript audio, the intelligence
+  presence dot, the browser news stream) intentionally without one.
+- `prom mcp`: serve the Prometheus MCP tool set over stdio — the same 18
+  read-only tools as the hosted https://www.prometheus.services/api/mcp
+  endpoint (shared definition module), authenticated with the CLI's usual key
+  resolution. Connect: `claude mcp add prometheus --env
+  PROMETHEUS_API_KEY=pk_live_... -- prom mcp`. New tools since 0.1.0:
+  `get_news` (the attributed intraday news tape) and `get_coverage` (the live
+  coverage inventory — agents answer "do you cover X?" from it, not memory).
+- `prom news`: the intraday news tape — market-wide with ticker, topic, source
+  and importance filters, one company's tape (`-c`), full-text search, `--top`
+  storylines, and `--follow` polling.
+- `prom monthly-revenue`: monthly revenue filings for Taiwan-listed companies.
+- Identifiers: platform keys for non-SEC issuers (`XSAU000001`, `XDFM000002`,
+  …) are accepted wherever a ticker or CIK is; a bare ticker resolves to the
+  SEC registrant.
+- The MCP SDK, zod and the shared tool package are inlined at build time — no
+  new runtime dependencies in the published package.
+
+## 0.1.0 — 2026-08-24
+
+First release.
+
+- Every public API operation reachable from a command (77 operations; the two
+  sparkline helpers are UI-only and intentionally omitted).
+- `login` / `logout` / `auth status` / `me` with a hidden prompt, stdin mode for CI,
+  validation against `GET /api/v1/me` before saving, 0600 config file.
+- Citation footer on every financial figure; `fact-source` prints the filing, XBRL
+  facts and revisions behind a cell.
+- Transcript date and 8-K item auto-resolution.
+- `--json` verbatim payloads, stdout/stderr discipline, stable exit codes 0–7,
+  single retry on short `Retry-After`, low-quota warning.
+- Descriptor mini-DSL for `correlate` and `chart`.
+- Build-time spec-hash guard; `prom --version` prints the contract hash.
+- Shell completion for bash, zsh and fish.

package/README.md

@@ -0,0 +1,80 @@
+# astreus
+
+`astreus` — [Astreus](https://astreus.ai) from the terminal. Astreus is
+the financial data terminal that turns the world's financial disclosure — filings, results
+announcements, investor decks, earnings calls, 8-Ks and central-bank text across the US,
+the Gulf, Japan, Taiwan, Korea and Europe — into structured, traceable data: standardized
+statements, segments and KPIs, note tables, transcripts, guidance scorecards, events, news,
+ownership, macro, markets and the causal claim graph, with the source filing printed under
+every number.
+
+```bash
+npm install -g astreus-cli
+astreus coverage                  # what is covered, market by market — no key needed
+astreus login                     # hidden prompt; key validated before it is saved
+astreus financials NVDA           # standardized income statement, cited
+astreus fact-source NVDA std:revenue 2025-01-26
+astreus transcript NVDA | less    # latest earnings call
+astreus --json company NVDA | jq  # the raw API payload, verbatim
+```
+
+Node 18+. Two runtime dependencies (`commander`, `picocolors`), no native modules.
+
+## What it does well
+
+- **Citations by default.** Any command that prints a financial figure ends with a
+  `source:` line — accession, period, basis — and `astreus fact-source` is one keystroke
+  away for any cell.
+- **Fills in what the raw API makes you look up.** `astreus transcript NVDA` resolves the
+  transcript id and its required date from the index; `astreus event NVDA <accession>`
+  resolves the 8-K item code.
+- **Built for scripts and agents.** `--json` is exactly one JSON document on stdout;
+  stderr carries everything else; exit codes are stable (`astreus help exit-codes`); text
+  endpoints stream so they pipe.
+- **Never drifts from the API.** The build embeds the SHA-256 of the OpenAPI contract and
+  fails if the spec changed; `astreus --version` prints the hash.
+- **Nulls are never zeros.** `—` means "not reported for that period".
+
+## Commands
+
+`astreus --help` lists them all. Groups:
+
+| Group | Commands |
+| --- | --- |
+| Auth & meta | `login`, `logout`, `auth status`, `me`, `health`, `stats`, `coverage`, `docs`, `llms`, `completion` |
+| Companies | `search`, `company`, `companies`, `prices`, `segments`, `regions`, `dividends`, `calendar`, `capital-structure`, `management`, `compute`, `logo` |
+| Financials | `financials`, `as-filed`, `fact-source`, `monthly-revenue` |
+| Filings & 8-K | `filings`, `filing`, `sections`, `section`, `note-tables`, `note-table`, `note-series`, `events`, `event`, `wire`, `observations` |
+| Calls & guidance | `transcripts`, `transcript`, `guidance`, `earnings`, `presentations`, `deck-page` |
+| Ownership & people | `ownership`, `people`, `person` |
+| Macro | `countries`, `macro`, `policy` |
+| Markets | `indices`, `commodities` |
+| Intelligence | `narratives`, `pulse`, `intel`, `graph`, `edge`, `simulate` |
+| Analytics | `catalog`, `correlate`, `chart` |
+| Scorecards | `scorecards events\|event\|executives`, `scorecard`, `signals` |
+| Transcript search | `transcript-search` (full text over every call, `--summary`), `mentioned-by` (where other companies name this one) |
+| Government | `government`, `executive-orders`, `officials` (`--changes`, `--schedule`), `awards`, `regulation` |
+| News | `news` — the attributed intraday tape, one company's tape (`-c`), search, `--top`, `--follow` |
+| MCP | `mcp` — serve the 18 Astreus MCP tools over stdio (`claude mcp add astreus --env ASTREUS_API_KEY=pk_live_... -- astreus mcp`) |
+
+## Configuration
+
+Key: `--api-key` → `ASTREUS_API_KEY` → `~/.config/astreus/config.json` (0600).
+Origin: `--base-url` → `ASTREUS_BASE_URL` → config file → `https://astreus.ai`.
+`NO_COLOR` is honoured; `ASTREUS_CONFIG_DIR` relocates the config file.
+
+## Exit codes
+
+`0` ok · `1` unexpected · `2` usage · `3` auth (401) · `4` payment (402) · `5` not found (404)
+· `6` rate limited / quota (429) · `7` server (5xx).
+
+## Development
+
+```bash
+npm run build      # gen types from ../web/public/openapi.json → tsup → spec-hash guard
+npm test           # node:test — transport, config, formatting, descriptor DSL, and every
+                   # command replayed against the OpenAPI examples
+ASTREUS_API_KEY=… ASTREUS_BASE_URL=http://localhost:3000 npm run test:e2e
+```
+
+Docs: <https://doc.astreus.ai/cli>. Licence: MIT.