arkiv-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harish Kotra
+
+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,513 @@
-# Temporary Holding Version
+# arkiv
 
-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.
+A terminal toolkit for the [Arkiv](https://arkiv.network) network. One binary that takes you from "I have a key" to "I can read and write entities" without reading the SDK source first.
+
+```
+  arkiv init [dir]              scaffold a runnable project
+  arkiv doctor                  check node, keys, balance, network and .env safety
+  arkiv query <expression>      run a query
+  arkiv entity <key>            read one entity in full
+  arkiv schema [name]           discover schemas, lint their names, or open one
+  arkiv create                  write one entity
+  arkiv watch <expression>      poll a query and print changes
+  arkiv cost                    size a write before you send it
+  arkiv limits                  protocol limits in one table
+```
+
+## Why this exists
+
+Arkiv ships a good SDK and good docs. What it does not ship is the loop every developer runs on day one: check the environment, get a key working, run one query, read one entity, write one entity, and see the write land. Today that loop is assembled by hand from docs pages and examples, and it fails in ways the SDK cannot explain. Wrong node version. A key with a stray newline. A rate-limited public RPC. A schema name that is legal but collides with someone else's.
+
+`arkiv` is that loop, in the terminal, with the failure modes named.
+
+## Install
+
+```bash
+npm install -g arkiv-cli     # or: npx arkiv-cli <command>
+```
+
+Node 22.10 or newer. That floor comes from the SDK, not from taste. Verified on Node 26.
+
+From source:
+
+```bash
+git clone https://github.com/harishkotra/arkiv-cli
+cd arkiv-cli
+npm install
+npm run build
+node dist/cli.js doctor
+```
+
+## Stack
+
+| Layer | Choice | Why |
+| --- | --- | --- |
+| Language | TypeScript 5.6, ES2022, NodeNext | Types catch the SDK's positional APIs at build time |
+| Runtime | Node 22.10+ | The SDK's floor |
+| Chain access | `@arkiv-network/sdk` | The same client everyone else uses, no private endpoints |
+| Transport and accounts | `viem` | Key validation, address derivation, `http()` transport |
+| CLI plumbing | Hand written | No framework. ~140 lines of parser buys strict flags and typed values |
+| Tests | `node:test` | Ships with Node, no test runner to configure |
+| Build | `tsc` | One step, no bundler |
+
+Runtime dependencies: two. That is deliberate. A CLI that pulls thirty packages to print a table is harder to audit than one you can read in an evening.
+
+## Credentials
+
+Two environment variables, read from `.env` in the current directory (or `--env <path>`, or the process environment):
+
+```bash
+ARKIV_ACCESS_KEY=...          # free at https://hub.arkiv.network/access-keys
+ARKIV_PRIVATE_KEY=0x...       # only needed for writes
+ARKIV_RPC_URL=...             # optional, overrides the network default
+```
+
+The CLI never generates a wallet, never derives an address for you to copy, never prints a key. `doctor` checks the format of both values without echoing them, and every value it validates registers with the output redactor, so a value that leaks into an error message comes back as `[REDACTED]`.
+
+Copy `.env.example` to `.env` to start. `.gitignore` already excludes `.env`; `doctor` fails loudly if it does not.
+
+## Quickstart
+
+```bash
+npx arkiv-cli init my-app
+cd my-app
+cp .env.example .env         # paste your key, keep the file out of git
+npx arkiv-cli doctor
+npm run dev
+```
+
+`init` writes a single-file runnable project (TypeScript, `tsx`, the SDK), and refuses to touch a directory that already has files unless you pass `--force`.
+
+## Commands
+
+### `arkiv doctor`
+
+The front door. Every check prints `ok`, `warn` or `fail` with a fix:
+
+- Node version against the SDK's floor (22.10)
+- `ARKIV_ACCESS_KEY` presence and shape
+- `ARKIV_PRIVATE_KEY` presence and shape (only for write work)
+- tGLM balance for the configured key
+- clock skew between your machine and the node's last block
+- reachability and chain id of the configured network
+- whether `.env` is git-ignored and whether its mode is world-readable
+
+Exit code is non-zero only when a check `fail`s, so it is safe in CI.
+
+```bash
+arkiv doctor
+arkiv doctor --json | jq '.checks[] | select(.status != "ok")'
+```
+
+### `arkiv query <expression>`
+
+![arkiv query](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/03-query.png)
+
+Runs a query with the SDK's own predicate language, no translation layer:
+
+```bash
+arkiv query "arkiv.schema = str('notes/v1')" --limit 5
+arkiv query "EXISTS(title) AND kind = str('note')" --sort updatedAt --type u64 --desc
+arkiv query "arkiv.schema = str('notes/v1')" --count
+arkiv query "..." --key              # keys only, cheap to pipe
+arkiv query "..." --select title,kind
+```
+
+`--schema <name>` is a shortcut that adds `arkiv.schema = str(name)` and refuses names that could break out of the string literal. An empty expression is a usage error rather than a full scan. `--limit` is capped at 100, which is the node's page size.
+
+### `arkiv entity <key>`
+
+![arkiv entity](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/04-entity.png)
+
+Reads one entity in full: owner, created and expiry timestamps, attribute schema, every attribute value, and an explorer link. The key is validated locally (`0x` plus 64 hex) before any network call, so a typo costs nothing and exits 2.
+
+Attribute values are chain data, which means arbitrary bytes. Every value is stripped of control sequences and non-printable characters before it reaches your terminal, and long values are truncated with a byte count.
+
+### `arkiv schema [name]`
+
+![arkiv schema](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/05-schema.png)
+
+There is no "list schemas" call on the node, so this pages through entities that carry `arkiv.schema`, samples them, and builds the picture from what is actually written:
+
+```bash
+arkiv schema                      # every schema seen in the sample, with owners and counts
+arkiv schema notes/v1             # fields, types, index flags, sample values for one schema
+arkiv schema --sample 1000        # sample deeper
+arkiv schema --atlas atlas.html   # write a standalone HTML page for the sample
+```
+
+A named schema is queried directly rather than filtered out of a sample, so it resolves even when it sits deep in the keyspace.
+
+The linter flags the naming problems that make a schema hard to find or unsafe to extend:
+
+- dots, slashes and hyphens mixed in one namespace
+- no version suffix, so the schema cannot evolve
+- names longer than the protocol's 32-byte attribute-name limit
+- the same schema name written by more than one owner (collision)
+- `str` attributes close to the 128-byte limit
+- entities at or near the 32-attribute limit
+
+### `arkiv create`
+
+![arkiv create dry run](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/07-create.png)
+
+Writes one entity. The schema is built at runtime from the flags, so there is no separate schema file to keep in sync:
+
+```bash
+arkiv create --schema notes/v1 \
+  --set title=str:Hello \
+  --set kind=str:note \
+  --set body=bytes:@./README.md \
+  --expires 30d \
+  --dry-run
+```
+
+Attribute syntax is `name=type:value`, where type is one of `str`, `u64`, `i32`, `u256`, `bool`, `bytes`, `addr`, `key`, `dec`. `bytes:@path` reads a file; `bytes:0x...` takes hex. `--expires` accepts `s`, `m`, `h`, `d`, `w`, `y` and is validated against the protocol's maximum lifetime.
+
+`--dry-run` prints the exact plan (attribute table, payload bytes, blocks until expiry, gas estimate) and stops before signing. Use it to check a write, and in tests.
+
+### `arkiv watch <expression>`
+
+![arkiv watch](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/08-watch.png)
+
+Polls a query and prints only what changed:
+
+```bash
+arkiv watch "arkiv.schema = str('notes/v1')" --interval 5
+arkiv watch "..." --once          # one snapshot, then exit
+```
+
+The watcher keeps a bounded, key-ordered window of matches and diffs it each tick. When the window saturates it says so, because a full window can hide new entities behind the ordering.
+
+### `arkiv cost`
+
+![arkiv cost](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/09-cost.png)
+
+Sizes a write before you pay for it:
+
+```bash
+arkiv cost --bytes 2048 --attributes 4 --expires 30d
+arkiv cost --file ./payload.json --attributes 6
+```
+
+Reports payload bytes, attribute overhead, blocks until expiry, the share of each protocol limit the write consumes, how many such writes fit in the limits, and the live gas price. It does not invent a GLM price: the network's pricing page is the source for that, and a CLI that guesses is worse than one that shows you the inputs.
+
+### `arkiv limits`
+
+![arkiv limits](https://raw.githubusercontent.com/harishkotra/arkiv-cli/main/docs/screenshots/10-limits.png)
+
+The protocol's hard limits in one table, sourced from the SDK's own exports with documented fallbacks, so the CLI cannot drift from the chain.
+
+## Configuration
+
+| Flag | Meaning |
+| --- | --- |
+| `--network <name>` | `rabdi` (default) or `localhost` |
+| `--rpc <url>` | override the RPC endpoint (http/https only) |
+| `--env <path>` | use a different env file |
+| `--json` | machine-readable output where supported |
+| `--no-colour` | plain text, also honoured via `NO_COLOR` |
+| `--verbose` | extra detail on failures |
+| `-h`, `--help` | help for a command |
+| `-v`, `--version` | version |
+
+Unknown flags are an error, not something to ignore. The argument parser rejects them, because a silently ignored `--limt 5` looks like a query that returned everything.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A["argv"] --> B["args.ts<br/>strict parser"]
+    B --> C["cli.ts<br/>dispatch + exit codes"]
+    C --> D["context.ts<br/>network, env file, client"]
+    D --> E["env.ts<br/>dotenv subset + secret registry"]
+    D --> F["arkiv.ts<br/>client and wallet factories"]
+    F --> G["@arkiv-network/sdk"]
+    F --> H["viem<br/>transport + accounts"]
+    C --> I["commands/query.ts"]
+    C --> J["commands/schema.ts"]
+    C --> K["commands/entity.ts"]
+    C --> L["commands/create.ts"]
+    C --> M["commands/watch.ts"]
+    C --> N["commands/cost.ts"]
+    C --> O["commands/doctor.ts"]
+    C --> P["commands/init.ts"]
+    I --> Q["values.ts<br/>types, sizes, printable text"]
+    J --> Q
+    L --> Q
+    I --> R["render.ts<br/>tables and entity blocks"]
+    J --> R
+    M --> R
+    C --> S["ui.ts<br/>colour, sanitize, redact"]
+    S --> T["stdout / --json"]
+```
+
+The same flow as text, for anyone reading this in a terminal:
+
+```
+argv
+ └─ args.ts ──► cli.ts ──► context.ts ──► arkiv.ts ──► SDK ──► RPC
+                  │            │
+                  │            └─ env.ts (dotenv, secret registry, URL guard)
+                  │
+                  ├─ commands/{init,doctor,query,entity,schema,create,watch,cost}
+                  │        ├─ values.ts (attribute types and sizing)
+                  │        └─ render.ts (tables, entity blocks)
+                  │
+                  └─ ui.ts (colour, sanitize, redact) ──► stdout
+```
+
+### Module map
+
+| Module | Lines | Responsibility |
+| --- | --- | --- |
+| `commands/schema.ts` | 499 | Sampling, schema map, linter, atlas renderer |
+| `cli.ts` | 396 | Flag declarations, dispatch, exit codes, help |
+| `commands/create.ts` | 299 | Attribute parsing, limit checks, dry run, signing |
+| `arkiv.ts` | 241 | Network table, client and wallet factories, notice capture |
+| `commands/init.ts` | 226 | Scaffold templates and safe writes |
+| `commands/doctor.ts` | 224 | Checks, fixes, JSON report |
+| `commands/cost.ts` | 188 | Lifetime parsing, byte math, limit comparison |
+| `ui.ts` | 176 | Colour, sanitize, redact, table primitives |
+| `commands/watch.ts` | 147 | Windowed polling and diffing |
+| `env.ts` | 146 | dotenv subset, mode checks, secret capture, URL guard |
+| `values.ts` | 141 | Attribute constructors, sizing, safe display |
+| `commands/query.ts` | 140 | Expression building, sort, paging |
+| `args.ts` | 139 | Strict argument parser |
+| `commands/entity.ts` | 109 | Key validation and single read |
+| `render.ts` | 96 | Entity rendering |
+| `context.ts` | 54 | Wiring: env, network, client |
+| `limits.ts` | 47 | Protocol constants in one place |
+
+About 3,400 lines including tests.
+
+## How a few parts work
+
+### Arguments are parsed strictly
+
+The parser knows every flag, its type and whether it repeats. Anything else is a usage error with the valid flags printed. That is why `--limit` cannot arrive as a string, and why repeated `--set` flags accumulate instead of overwriting:
+
+```ts
+const put = (key: string, value: FlagValue): void => {
+  const previous = flags[key];
+  if (spec.repeat) {
+    const list = Array.isArray(previous) ? previous : previous === undefined ? [] : [previous];
+    flags[key] = [...list, value];
+    return;
+  }
+  if (previous !== undefined) throw new UsageError(`--${key} was given more than once`);
+  flags[key] = value;
+};
+```
+
+### Query expressions are built with a guard, not concatenated blindly
+
+```ts
+export function buildExpression(options: QueryOptions): string {
+  const parts: string[] = [];
+  const raw = options.expression.trim();
+  if (raw) parts.push(`(${raw})`);
+  if (options.schema) {
+    if (!/^[A-Za-z0-9._/-]{1,64}$/.test(options.schema)) {
+      throw new UsageError("--schema contains characters that are not allowed in a schema name");
+    }
+    parts.push(`arkiv.schema = str('${options.schema}')`);
+  }
+  if (parts.length === 0) {
+    throw new UsageError(
+      'give a filter expression, for example: arkiv query "arkiv.schema = str(\'my-app-v1.post\')"',
+    );
+  }
+  const expression = parts.join(" AND ");
+  if (expression.length > 2000) throw new UsageError("expression is too long (2000 character limit)");
+  return expression;
+}
+```
+
+`--schema` is checked against a character whitelist because that value is interpolated into the predicate, not bound. The free-form expression is passed through as written, since writing predicates is the point of the command.
+
+### Redaction sits in front of stdout
+
+```ts
+export function redact(input: unknown): string {
+  let s = typeof input === "string" ? input : String(input ?? "");
+  for (const secret of secrets) {
+    if (secret) s = s.split(secret).join("[REDACTED]");
+  }
+  s = s
+    .split("\n")
+    .map((line) => (KEY_CONTEXT_RE.test(line) ? line.replace(KEY_RE, "0x[REDACTED]") : line))
+    .join("\n");
+  s = s.replace(ASSIGN_RE, (_m, p1: string) => `${p1}[REDACTED]`);
+  return s;
+}
+```
+
+Registered secrets are replaced everywhere. Key-shaped strings are only redacted on lines that talk about key material, because entity keys are also 64 hex characters and redacting those would break the tool. The first version got this wrong and printed `key 0x[REDACTED]` for a valid entity.
+
+Chain data takes a different path. `sanitize()` strips ANSI escapes and replaces control characters, so a hostile attribute value cannot move your cursor or repaint the screen.
+
+### Watching uses a window, not a cursor
+
+Arkiv's public RPC has no subscription stream, so the watcher reads a key-ordered window each tick and diffs it:
+
+```ts
+const next = new Map(current.map((entity) => [entity.$key, entity]));
+for (const [key, entity] of next) {
+  if (previous.has(key)) continue;
+  out(`${green("+")} ${grey(stamp(entity))} ${summarise(entity)}`);
+}
+for (const [key, entity] of previous) {
+  if (next.has(key)) continue;
+  out(`${red("-")} ${grey(stamp(entity))} ${summarise(entity)}`);
+}
+previous = next;
+```
+
+Ordering by key keeps the window stable between ticks. If the window fills, the CLI prints a saturation warning rather than silently dropping entities that fell outside the range.
+
+### SDK noise is captured, not printed
+
+The SDK writes a rate-limit notice through `console.warn`. Left alone it lands in the middle of a table and breaks `--json`:
+
+```ts
+function quietWarn(): () => void {
+  const originals = { log: console.log, warn: console.warn, info: console.info, debug: console.debug };
+  const capture = (...args: unknown[]) => {
+    const text = args.map(String).join(" ");
+    if (text.includes("heavily rate limited")) {
+      capturedNotice = text.trim();
+      return;
+    }
+    originals.log(...args);
+  };
+  console.log = capture;
+  console.info = capture;
+  console.debug = capture;
+  console.warn = capture;
+  // returns a restore function, called in a finally block
+}
+```
+
+The notice is replayed once at the end, after the results, so the information survives without corrupting the output.
+
+## Security model
+
+The threat model is a CLI that talks to a public network and prints data it did not author.
+
+- **Credentials cannot be printed.** `.env` values are parsed without shell expansion (a hostile `.env` cannot execute anything), validated, and registered with a central redactor on read. Every output path runs through `sanitize`/`redact`, so key-shaped strings and registered secrets become `[REDACTED]`.
+- **No key material on disk.** The CLI never writes a private key anywhere, never generates one, and never puts one in a URL.
+- **Chain data is untrusted.** Attribute values are arbitrary bytes and can contain ANSI escapes or terminal control sequences. All chain-sourced strings are stripped before display.
+- **RPC URLs are constrained.** Only `http`/`https` are accepted; anything else is refused before a client is built.
+- **No implicit writes.** Writes require an explicit `create`, and `--dry-run` gives you the plan first. Nothing else in the CLI mutates the chain.
+- **No destructive defaults.** `init` uses `wx` (fail if the file exists) and requires `--force` for a non-empty directory.
+- **Rate-limit notices are captured, not printed over your output.** The SDK's public-endpoint warning is intercepted on every console channel and surfaced once, at the end, so it cannot corrupt `--json`.
+
+Tests cover the parser, the dotenv reader, the redactor, the sanitizer, the query builder and the protocol-limit checks. 23 tests, run against the built output because that is what ships.
+
+## The Schema Atlas
+
+`schema --atlas out.html` writes a standalone page (no network calls, no scripts) listing every schema in the sample, its owners, attribute names and types. It is generated from live data, so it is a snapshot rather than a registry. `docs/schema-atlas.html` is one such snapshot of Rabdi, built from a 500 entity sample: 78 schemas.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsc -> dist/
+npm test            # build + node --test
+npm run typecheck   # no emit
+npm run dev -- ...  # run from source with tsx
+```
+
+Tests run against `dist/` on purpose. A green suite against source that fails after `tsc` is a class of bug worth excluding.
+
+Repo layout:
+
+```
+arkiv-cli/
+├─ src/
+│  ├─ cli.ts              command surface and flag declarations
+│  ├─ args.ts             strict argument parser
+│  ├─ env.ts              dotenv reading, mode checks, credential validation
+│  ├─ arkiv.ts            client construction, network table, quiet SDK warnings
+│  ├─ context.ts          wiring
+│  ├─ values.ts           attribute constructors, safe display, sizing
+│  ├─ render.ts           table and entity rendering
+│  ├─ ui.ts               colour, sanitize, redact
+│  ├─ limits.ts           protocol limits with fallbacks
+│  └─ commands/           one module per command
+├─ test/                  node:test suites against dist/
+├─ docs/
+│  ├─ schema-atlas.html   generated atlas
+│  ├─ screenshots/        real runs, 2x PNG
+│  └─ blog/               technical write-up
+└─ dist/                  build output, not committed
+```
+
+## Contributing
+
+Fork, branch, write a failing test, make it pass, open a PR. Keep the diff small and put the reasoning in the PR body.
+
+```bash
+gh repo fork harishkotra/arkiv-cli --clone
+cd arkiv-cli
+npm install
+npm test
+git checkout -b feat/your-thing
+```
+
+Two rules matter more than style:
+
+1. Nothing that touches a credential gets printed. Add a test if you touch output.
+2. New protocol limits go in `limits.ts`, never inline.
+
+A good PR shows the command working, includes the failure path, and says what you chose not to do.
+
+### Good first issues
+
+- `arkiv schema --diff a b`, printing field additions and removals between two schema names.
+- `--format csv` for `query` and `schema`, alongside the existing `--json`.
+- Shell completion generation for zsh, bash and fish.
+- `arkiv export --schema <name> --out dir/`, writing one JSON file per entity and resuming by key.
+- Colour handling: honour `NO_COLOR`, `FORCE_COLOR` and `isatty` in one place, with tests.
+
+### Larger ideas
+
+- `arkiv push <dir>`, reading a directory of JSON entities and writing them with a per-entity dry run and idempotency by key.
+- `arkiv replay`, recording a query window to disk and replaying it offline, so CI can test against a fixed view of the chain.
+- Schema drift in the atlas: show what changed in a namespace between two snapshots.
+- `arkiv bench`, measuring read latency and write confirmation time per network.
+- An MCP server exposing `query`, `schema` and `create --dry-run` to agents, reusing the validated core.
+- A scheduled GitHub Action running `doctor` plus `schema --lint`, opening an issue when a namespace starts colliding.
+
+### Conventions
+
+- ES modules, NodeNext resolution, strict TypeScript. `noUncheckedIndexedAccess` is off on purpose; the casts at the SDK boundary are explicit.
+- No new runtime dependency without a reason in the PR. Current runtime deps: `@arkiv-network/sdk`, `viem`.
+- Command functions take `Context` and an options object, return `Promise<void>`, and print. They do not throw strings.
+- Exit codes: `0` success, `1` runtime failure, `2` usage error.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `heavily rate limited` notice | Public endpoint | Set `ARKIV_ACCESS_KEY` in `.env` |
+| `doctor` clock check fails | Local clock drift | Turn on automatic time sync |
+| `entity` exits 2 | Malformed key | Keys are `0x` plus 64 hex characters |
+| `create` reports the attribute limit | Over 32 attributes | Drop fields or split the entity |
+| `create` reports a string limit | `str` over 128 bytes | Use `bytes` for long values |
+| `schema` misses a namespace | Sample did not reach it | Query it by name, or raise `--sample` |
+| `init` refuses to write | Directory is not empty | Pass `--force` or pick another path |
+
+## Protocol facts the CLI relies on
+
+- An entity carries at most 32 attributes, and a `str` attribute is at most 128 bytes. Long text belongs in the payload as `bytes`.
+- Queries cannot match every entity. A predicate or schema filter is required, which is why an empty expression is a usage error rather than a table dump.
+- `$createdAt` is not a sortable column.
+- The public Rabdi endpoint is rate limited and shared. An access key is the difference between a demo and a workflow.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Built By [Harish Kotra](https://harishkotra.me) · [Checkout my other builds](https://dailybuild.xyz)

package/dist/args.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A deliberately small argument parser.
+ *
+ * It rejects unknown flags instead of guessing, which turns a typo like
+ * `--limt 5` into a clear error rather than a confusing empty result.
+ */
+export type FlagType = "bool" | "string" | "number";
+export type FlagSpec = Record<string, FlagType>;
+export type FlagValue = string | number | boolean | Array<string | number>;
+export interface Parsed {
+    positionals: string[];
+    flags: Record<string, FlagValue>;
+}
+export declare class UsageError extends Error {
+}
+export declare function parseArgs(argv: string[], spec: FlagSpec, aliases?: Record<string, string>): Parsed;
+export declare function flagString(p: Parsed, name: string, fallback?: string): string;
+export declare function flagNumber(p: Parsed, name: string, fallback: number): number;
+export declare function flagBool(p: Parsed, name: string): boolean;

package/dist/args.js

@@ -0,0 +1,124 @@
+/**
+ * A deliberately small argument parser.
+ *
+ * It rejects unknown flags instead of guessing, which turns a typo like
+ * `--limt 5` into a clear error rather than a confusing empty result.
+ */
+export class UsageError extends Error {
+}
+const SHORT = {
+    h: "help",
+    v: "version",
+    n: "limit",
+    j: "json",
+    s: "schema",
+    q: "quiet",
+};
+export function parseArgs(argv, spec, aliases = {}) {
+    const flags = {};
+    const positionals = [];
+    /* repeating a flag accumulates, so --set a=1 --set b=2 keeps both */
+    const put = (name, value) => {
+        const previous = flags[name];
+        if (previous === undefined) {
+            flags[name] = value;
+        }
+        else if (Array.isArray(previous)) {
+            previous.push(value);
+        }
+        else {
+            flags[name] = [previous, value];
+        }
+    };
+    const allowed = new Set(Object.keys(spec));
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--") {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("--")) {
+            let name = token.slice(2);
+            let inline;
+            const eq = name.indexOf("=");
+            if (eq >= 0) {
+                inline = name.slice(eq + 1);
+                name = name.slice(0, eq);
+            }
+            let negated = false;
+            if (name.startsWith("no-")) {
+                negated = true;
+                name = name.slice(3);
+            }
+            name = aliases[name] ?? name;
+            if (!allowed.has(name)) {
+                throw new UsageError(`unknown option --${name}`);
+            }
+            const type = spec[name];
+            if (type === "bool") {
+                flags[name] = !negated;
+                continue;
+            }
+            if (negated)
+                throw new UsageError(`--no-${name} is not valid`);
+            let value = inline;
+            if (value === undefined) {
+                const next = argv[i + 1];
+                if (next === undefined || next.startsWith("-")) {
+                    throw new UsageError(`--${name} needs a value`);
+                }
+                value = next;
+                i += 1;
+            }
+            if (type === "number") {
+                const n = Number(value);
+                if (!Number.isFinite(n))
+                    throw new UsageError(`--${name} must be a number`);
+                put(name, n);
+            }
+            else {
+                put(name, value);
+            }
+            continue;
+        }
+        if (token.startsWith("-") && token.length > 1) {
+            const letters = token.slice(1);
+            for (let k = 0; k < letters.length; k += 1) {
+                const letter = letters[k];
+                const name = SHORT[letter] ?? aliases[letter] ?? letter;
+                if (!allowed.has(name))
+                    throw new UsageError(`unknown option -${letter}`);
+                if (spec[name] === "bool") {
+                    flags[name] = true;
+                }
+                else {
+                    const rest = letters.slice(k + 1);
+                    let value = rest;
+                    if (!value) {
+                        const next = argv[i + 1];
+                        if (next === undefined)
+                            throw new UsageError(`-${letter} needs a value`);
+                        value = next;
+                        i += 1;
+                    }
+                    put(name, spec[name] === "number" ? Number(value) : value);
+                    break;
+                }
+            }
+            continue;
+        }
+        positionals.push(token);
+    }
+    return { positionals, flags };
+}
+export function flagString(p, name, fallback = "") {
+    const v = p.flags[name];
+    return typeof v === "string" ? v : fallback;
+}
+export function flagNumber(p, name, fallback) {
+    const v = p.flags[name];
+    return typeof v === "number" ? v : fallback;
+}
+export function flagBool(p, name) {
+    return p.flags[name] === true;
+}