qotm 1.0.7 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 WessCoby
+Copyright (c) 2026 WessCoby
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,50 +1,156 @@
-# Quote of the Moment
-Display a random tech or programming quote to the console.
+# qotm
 
-## Overview
-`qotm` is my version of `fortune` but outputs tech or programming quotes. And like `fortune`, `qotm` is better with `cowsay` and/or `lolcat`. So it is best to have either or both of them installed.
-![qotm command preview](./images/preview.png)
+One considered programming quote in your terminal, from a community that
+verifies and curates them at [qotm.dev](https://qotm.dev).
 
-## Installation
 ```sh
-# Installing qotm
-> npm install -g qotm
+npm i -g qotm
+qotm
+```
+
+Requires Node.js 22.16 or later (or 24+). No account and no network on the default
+path: quotes come from a local copy of the curated dataset, which ships with
+the package.
 
-# Installing cowsay and lolcat:
-# Via apt 
-> sudo apt-get install cowsay lolcat
+## Reading quotes
 
-# Via npm
-> npm install -g cowsay lolcatjs
+```sh
+qotm                          # a quote, avoiding the last 50 shown
+qotm --topic debugging        # from one topic
+qotm --author dijkstra        # by one author
+qotm --favorites              # from your favorites
+qotm --personal               # from your private quotes
+qotm --source                 # with where it is from
+qotm last                     # the previous quote again
 ```
-### Usage
+
+## Favorites and private quotes
+
+These work signed out and offline, kept on this machine:
+
 ```sh
-# Get a random quote [ text only ]
-> qotm
+qotm save                     # favorite the last quote ("saved to favorites")
+qotm save q_8f2k1c            # or one by id
+qotm unsave                   # take the last quote (or <id>) out again
+qotm favorites                # list them (--json for a list of objects)
+qotm add "Name things twice." --author Ada   # keep a private quote
+qotm --personal               # a quote from your private quotes
+```
 
-# Colorize text with lolcat (or lolcatjs, if you installed via npm)
-> qotm | lolcat
+Saving a quote twice changes nothing. Signed in, favorites are shared with
+your account: a save or unsave goes up straight away, or, offline, waits for
+the next `qotm sync`, which also brings down the favorites you added on
+qotm.dev.
 
-# Text with cowsay
-> qotm | cowsay
+## Updating the quotes
 
-# Combined
-> qotm | cowsay | lolcat
+```sh
+qotm sync                     # fetch the latest dataset release
 ```
-You can also add the command to your shell's `*rc` file (.bashrc, .zshrc, etc. or whatever file the shell loads on startup) so it outputs a quote everytime you open a new shell.
 
-### Updates
-This Repo will be frequently updated with new quotes. Simply run `npm i -g qotm` to get the latest updates. Expect an update notifier to be added in future updates so as to prompt you when new updates are ready.
+`qotm sync` checks the download against the release manifest (size and
+sha256) and replaces your copy in one step: an interrupted or mismatched
+download leaves your quotes as they were. It asks with the version it holds,
+so an up-to-date copy costs one small request.
 
-## Contributing
-There are thousands of tech and programming quotes out there. You have your favorites right? Add them to the `contributing.json` file using the specified format and submit a pull request to the `qotm-cli` branch. I'll be happy to pull them in and make them available in subsequent updates. You can also help in any other way you can, be it code refactoring, typo fixes, etc. <br>
-*NB*: I may need to verify the quote and it's author. Please do check as well before adding quotes. 
+## Your account
 
 ```sh
-> qotm 
+qotm login                    # sign in: approve the printed code at qotm.dev/device
+qotm logout                   # sign out and revoke this terminal
+```
 
-Vision without execution is daydreaming
+Signing in lists this terminal under Settings › Terminals on qotm.dev.
+Signing out keeps your local quotes, favorites and dataset.
 
--- Bill Gates
+## Submitting
 
+```sh
+qotm submit "Premature optimization is the root of all evil." \
+  --author "Donald E. Knuth" --source "Structured Programming with go to Statements" \
+  --year 1974 --topic programming          # a canonical quote: a verifier checks the source
+qotm submit --original "Ship the smallest thing that teaches you something." \
+  --topic software-engineering --rights    # your own words
+qotm submit p_ab12cd34 --topic learning --rights   # one of your private quotes, as your original
+qotm submit --check "Make it work, make it right, make it fast."   # does qotm have it already?
+```
+
+Submitting needs `qotm login`. Every missing or invalid field is listed at
+once; the match against quotes already on qotm is shown before sending.
+Signed in, `qotm add` also keeps the quote in your account's private quotes.
+
+## More
+
+```sh
+qotm open                     # the last quote's page on qotm.dev ("opening q/1t7c4e in your browser")
+qotm search complexity        # search your dataset, offline (--web: on qotm.dev; --json)
+qotm status                   # dataset version, last sync, account, counts (--json)
+qotm config                   # settings: api, site, color, style, history (get / set / unset; --json)
+qotm doctor                   # check Node, folders, the dataset's sha256 and the API (--json)
 ```
+
+`qotm doctor` exits 1 and names the problem when a check fails.
+`QOTM_API_URL` and `QOTM_SITE_URL` override the api and site settings for
+one run.
+
+### How a quote looks
+
+On a terminal, a quote is drawn in one of four styles: box-drawing and block
+characters, no extra tools.
+
+```sh
+qotm config set style pull    # the default: clay quote marks beside the words
+qotm config set style bubble  # a speech bubble with the qotm "q" (cowsay's heir)
+qotm config set style card    # a centred card, its id and status in the edge
+qotm config set style slab    # a lighter panel with a clay edge (best in colour)
+qotm --style card             # one style, this once
+```
+
+The shape fits the quote: lines wrap at 60 columns at most, never past the
+terminal, and are balanced so no word sits alone on the last line. Narrower
+than 40 columns, the quote prints without a shape.
+
+Output is coloured on a terminal and plain when piped (the words and the
+credit, for scripts and for `qotm | cowsay`). `--plain` forces that plain
+text. `NO_COLOR` and `TERM=dumb` drop the colour but keep the shape.
+
+### `--json`
+
+`qotm --json` and `qotm last --json` print one object:
+
+```json
+{
+	"id": "q_8f2k1c",
+	"text": "Simplicity is prerequisite for reliability.",
+	"type": "canonical",
+	"author": { "name": "Edsger W. Dijkstra", "slug": "dijkstra" },
+	"contributor": "kofi",
+	"work": "EWD 498",
+	"year": 1975,
+	"source": "EWD 498: How do we tell truths that might hurt?",
+	"sourceUrl": "https://www.cs.utexas.edu/~EWD/transcriptions/EWD04xx/EWD498.html",
+	"topics": ["simplicity"],
+	"url": "https://qotm.dev/q/8f2k1c",
+	"dataset": "v2026.09.1"
+}
+```
+
+- `type`: `canonical` (attributed to an author), `original` (a member's own
+  words; `author` is null and `contributor` is the member's handle, or null
+  for a former member) or `personal` (one of your private quotes: `url` and
+  `dataset` are null).
+- `work`, `year`, `source`, `sourceUrl` are null when not on record.
+
+## Where qotm keeps things
+
+|                             | Linux                 | macOS                                | Windows                    |
+| --------------------------- | --------------------- | ------------------------------------ | -------------------------- |
+| settings, session           | `~/.config/qotm`      | `~/Library/Preferences/qotm`         | `%APPDATA%\qotm\Config`    |
+| dataset, favorites, history | `~/.local/share/qotm` | `~/Library/Application Support/qotm` | `%LOCALAPPDATA%\qotm\Data` |
+
+`XDG_CONFIG_HOME` and `XDG_DATA_HOME` are honoured; `QOTM_HOME` puts both
+under one folder.
+
+## License
+
+MIT

package/data/snapshot.json

@@ -0,0 +1,9 @@
+{
+	"version": "v2026.10.1",
+	"schemaVersion": 1,
+	"builtAt": "2026-10-14T00:03:11.444Z",
+	"publishedAt": "2026-10-14T00:03:49.836Z",
+	"quotes": 500,
+	"size": 352256,
+	"sha256": "aa01263935e9b42a5ebcda9b8b0bc0b69815514410180174a18e507e17ceed88"
+}