@sdxc/ip 2026.10.6 → 2026.11.3

package/README.md

@@ -2,11 +2,11 @@
 
 IPv4 and IPv6 addresses and ranges as value objects that classify against the IANA special-purpose registries.
 
-An `IP` is one parsed, valid address. A function that takes one cannot be handed `"unknown"`, `"10.0.0"` or a hostname, and the address can say whether it is on the public internet, which network it sits in, and how it is spelled canonically. Nothing performs I/O, so it runs wherever an address arrives as text: a URL host, a DNS answer, a request header.
+An `IP` is one parsed, valid address: it knows whether it is on the public internet, which network it sits in, and how it is spelled canonically. Everything runs without I/O, wherever an address arrives as text: a URL host, a DNS answer, a request header.
 
 ## Installation
 
-```bash
+```sh
 npm add @sdxc/ip
 ```
 
@@ -14,22 +14,22 @@ Parsing answers a `Result` from [`@sdxc/result`](https://www.npmjs.com/package/@
 
 ## Usage
 
-### Parsing An Address
+### Parse an address
 
 ```typescript
 import { IP } from "@sdxc/ip";
 import { isFailure } from "@sdxc/result";
 
 let parsed = IP.parse("2001:DB8::0:1");
-if (isFailure(parsed)) return parsed; // IP.Error { code: "invalid-address" }
+if (isFailure(parsed)) return parsed.error.code; // "invalid-address"
 
 let ip = parsed.data;
 ip.version; // 6
 ip.toString(); // "2001:db8::1"
-ip.isPublic; // false: documentation range
+ip.equals(ip); // compare two addresses with equals, never ===
 ```
 
-### Refusing A URL That Points Inside The Network
+### Classify it
 
 ```typescript
 import { IP } from "@sdxc/ip";
@@ -40,115 +40,186 @@ function isPublicHost(url: URL): boolean {
 	return isSuccess(ip) && ip.data.isPublic;
 }
 
-isPublicHost(new URL("http://169.254.169.254/")); // false
-isPublicHost(new URL("http://[::ffff:10.0.0.1]/")); // false
+isPublicHost(new URL("http://169.254.169.254/")); // false: link-local
+isPublicHost(new URL("http://[::ffff:10.0.0.1]/")); // false: judged by the IPv4 inside
 isPublicHost(new URL("http://[::ffff:8.8.8.8]/")); // true
 ```
 
-### Testing A Range
+`classification` names what the address is for (`"private"`, `"loopback"`, `"documentation"`, …), and `isPublic` is `classification === "public"`.
+
+### Test a range
 
 ```typescript
-let office = IP.Range.parse("203.0.113.0/24");
-if (isSuccess(office)) office.data.contains(ip); // false across versions
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
+
+let range = IP.Range.parse("203.0.113.0/24");
+let ip = IP.parse("203.0.113.7");
+if (isSuccess(range) && isSuccess(ip)) range.data.contains(ip.data); // true
 
 IP.Range.parse("10.0.0.1/8"); // failure: IP.Error { code: "host-bits-set" }
 ```
 
-### Keying A Rate Limit On The Client's Network
+## Command line
 
-An IPv6 client is normally assigned a whole `/64`, so a key on the full address counts each address it rotates through separately.
+```sh
+bunx @sdxc/ip classify 192.168.1.10
+```
 
-```typescript
-ip.network({ v4: 32, v6: 64 }).toString(); // "2001:db8:1:2::/64" or "203.0.113.7/32"
+With [`@sdxc/kit`](https://www.npmjs.com/package/@sdxc/kit) installed, `sdxc pkg ip …` runs the same command line, using the version your project installs.
+
+`classify` prints the address's version, canonical form, classification, whether it is public, and the IPv4 an IPv4-mapped, NAT64 or 6to4 address carries. With no address, or `-`, it reads stdin; `--json` prints the same as an object.
+
+```sh
+bunx @sdxc/ip contains 10.0.0.0/8 10.1.2.3
 ```
 
+`contains` exits 0 when the range holds the address and 1 when it does not. Both commands exit 2 for text that is not an address or a range. `bunx @sdxc/ip --help` lists every flag.
+
 ## API
 
-### `IP.parse(text): Result<IP, IP.Error>`
+### `IP.parse(text: string): Result<IP, IP.Error>`
 
-Parses an IPv4 or IPv6 address. Brackets around IPv6 are accepted (`[::1]`), the way a URL host spells it. IPv4 must be canonical dotted decimal: `URL` already normalizes octal, hex and bare-integer hosts, and refusing them here keeps any other input from naming a different address than it appears to. Zone identifiers (`fe80::1%eth0`) are refused.
+Parses an IPv4 or IPv6 address, accepting brackets around IPv6 (`[::1]`) the way a URL host spells it. IPv4 must be canonical dotted decimal, and zone identifiers (`fe80::1%eth0`) fail, so every accepted text names exactly the address it appears to.
 
 ### `IP`
 
-Immutable, and only obtainable from `IP.parse`.
+An immutable address, obtainable only from `IP.parse`.
 
-- `version` — `4` or `6`.
-- `classification` — what the IANA special-purpose registries say the address is for: `"public"`, `"unspecified"`, `"loopback"`, `"private"`, `"shared"`, `"link-local"`, `"documentation"`, `"benchmarking"`, `"multicast"`, `"reserved"`, `"unique-local"`, `"teredo"` or `"discard"`. IPv6 outside `2000::/3` and not otherwise assigned is `"reserved"`.
-- `isPublic` — `classification === "public"`.
-- `embeddedIPv4` — the IPv4 address inside an IPv4-mapped (`::ffff:0:0/96`), NAT64 (`64:ff9b::/96`) or 6to4 (`2002::/16`) address, or `null`. `classification` and `isPublic` judge those addresses by the IPv4 inside, so `::ffff:10.0.0.1` is `"private"`.
-- `network({ v4, v6 })` — the `IP.Range` the address sits in at the prefix length for its version. A length outside the version's width is clamped into it.
-- `equals(other)` — same version and same address. `===` compares object identity, so compare two `IP`s with this.
-- `toString()` — canonical text: dotted decimal, or [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952) IPv6 (lowercase, longest zero run compressed, IPv4-mapped ending in a dotted quad), without brackets. Every spelling of one address prints one string, so it is the key for a `Map`, a rate limit, a log field or a database column.
-- `toJSON()` — the same string, so `JSON.stringify({ ip })` writes `{"ip":"2001:db8::1"}`.
+- `version`: `4` or `6`.
+- `classification`: what the IANA special-purpose registries say the address is for, one of `"public"`, `"unspecified"`, `"loopback"`, `"private"`, `"shared"`, `"link-local"`, `"documentation"`, `"benchmarking"`, `"multicast"`, `"reserved"`, `"unique-local"`, `"teredo"` or `"discard"`. IPv6 outside `2000::/3` and not otherwise assigned is `"reserved"`.
+- `isPublic`: `classification === "public"`.
+- `embeddedIPv4`: the IPv4 address inside an IPv4-mapped (`::ffff:0:0/96`), NAT64 (`64:ff9b::/96`) or 6to4 (`2002::/16`) address, or `null`. `classification` judges those addresses by the IPv4 inside.
+- `network({ v4, v6 })`: the `IP.Range` the address sits in at the prefix length for its version, clamped to the version's width.
+- `equals(other)`: same version and same address.
+- `toString()`: canonical text, dotted decimal or [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952) IPv6 without brackets. Every spelling of one address prints one string.
+- `toJSON()`: the same string, so `JSON.stringify({ ip })` writes `{"ip":"2001:db8::1"}`.
 
-A structured clone (Durable Object storage, `postMessage`) drops the methods. Store `toString()` and parse it back on read.
+A structured clone (`postMessage`, Durable Object storage) drops the methods, so store `toString()` and parse it back.
 
-### `IP.Range.parse(text): Result<IP.Range, IP.Error>`
+### `IP.Range.parse(text: string): Result<IP.Range, IP.Error>`
 
-Parses `network/prefix` text. A network address with bits set past the prefix fails with `host-bits-set`; anything else malformed fails with `invalid-range`.
+Parses `network/prefix` text. An address with bits set past the prefix fails with `host-bits-set`; other malformed text fails with `invalid-range`.
 
 ### `IP.Range`
 
-Immutable, and only obtainable from `IP.Range.parse` or `ip.network`.
+An immutable network, obtainable only from `IP.Range.parse` or `ip.network()`.
 
-- `network` — the first address, as an `IP`.
-- `prefix` — the prefix length.
-- `version` — `4` or `6`.
-- `contains(ip)` — whether the address shares the range's leading bits. An address of the other version is never a member.
-- `equals(other)`, `toString()`, `toJSON()` — as on `IP`; the text is `network/prefix`, such as `2001:db8::/32`.
+- `network`: the first address, as an `IP`.
+- `prefix`: the prefix length.
+- `version`: `4` or `6`.
+- `contains(ip)`: whether the address shares the range's leading bits; an address of the other version is never a member.
+- `equals(other)`, `toString()`, `toJSON()`: as on `IP`, with the text written `network/prefix`, such as `2001:db8::/32`.
 
 ### `IP.Error`
 
-The failure both parsers answer, never thrown. `code` is `"invalid-address"`, `"invalid-range"` or `"host-bits-set"`, and `input` is the rejected text. It is a class, so `error instanceof IP.Error` narrows.
+The failure both parsers answer inside a `Result`. `code` is `"invalid-address"`, `"invalid-range"` or `"host-bits-set"`, `input` is the rejected text, and `error instanceof IP.Error` narrows it.
 
 ### Types
 
 `IP.Range`, `IP.Error`, `IP.ErrorCode`, `IP.Classification` and `IP.Prefixes` (`{ v4: number; v6: number }`) are types under the same `IP` name.
 
+## Pattern: Refusing A Name That Resolves Inside The Network
+
+Checking the URL host stops `http://127.0.0.1`; classifying every DNS answer before fetching also stops a public name whose record points at an internal address.
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
+
+function allPublic(answers: string[]): boolean {
+	return (
+		answers.length > 0 &&
+		answers.every((answer) => {
+			let ip = IP.parse(answer);
+			return isSuccess(ip) && ip.data.isPublic;
+		})
+	);
+}
+
+allPublic(["93.184.215.14"]); // true
+allPublic(["93.184.215.14", "10.0.0.5"]); // false
+```
+
 ## Pattern: An Allowlist Of Networks
 
+Parse the ranges once and test each request's address against them.
+
 ```typescript
 import { IP } from "@sdxc/ip";
 import { isSuccess } from "@sdxc/result";
 
-const OFFICE_RANGES = ["203.0.113.0/24", "2001:db8:42::/48"];
+let allowed = ["203.0.113.0/24", "2001:db8:42::/48"].flatMap((text) => {
+	let range = IP.Range.parse(text);
+	return isSuccess(range) ? [range.data] : [];
+});
 
-function isOffice(ip: IP): boolean {
-	return OFFICE_RANGES.some((text) => {
-		let range = IP.Range.parse(text);
-		return isSuccess(range) && range.data.contains(ip);
-	});
+function isAllowed(text: string): boolean {
+	let ip = IP.parse(text);
+	return isSuccess(ip) && allowed.some((range) => range.contains(ip.data));
 }
+
+isAllowed("203.0.113.9"); // true
+isAllowed("2001:db8:42:7::1"); // true
+isAllowed("198.51.100.1"); // false
 ```
 
-## Pattern: Checking Every Address A Name Resolves To
+## Pattern: Keying A Rate Limit On The Client's Network
 
-A literal check only stops `http://127.0.0.1`. A public name whose `A` record points at an internal address is caught by classifying every answer before fetching:
+An IPv6 client is usually assigned a whole `/64`, so keying on the full address counts each address it rotates through separately. Key on the network instead, and the canonical text keeps every spelling of one client on one key.
 
 ```typescript
 import { IP } from "@sdxc/ip";
-import { isSuccess } from "@sdxc/result";
+import { isFailure } from "@sdxc/result";
 
-function allPublic(answers: string[]): boolean {
-	return (
-		answers.length > 0 &&
-		answers.every((answer) => {
-			let ip = IP.parse(answer);
-			return isSuccess(ip) && ip.data.isPublic;
-		})
-	);
+function rateLimitKey(text: string): string | null {
+	let ip = IP.parse(text);
+	if (isFailure(ip)) return null;
+	return ip.data.network({ v4: 32, v6: 64 }).toString();
 }
+
+rateLimitKey("2001:DB8:1:2::abcd"); // "2001:db8:1:2::/64"
+rateLimitKey("2001:db8:1:2:ffff::1"); // "2001:db8:1:2::/64"
+rateLimitKey("203.0.113.7"); // "203.0.113.7/32"
 ```
 
-## Pattern: A Function That Only Accepts A Checked Address
+## Pattern: Reporting Why Input Was Refused
+
+`IP.Error` carries a code to map to your own wording and the text that arrived.
 
 ```typescript
-import type { IP } from "@sdxc/ip";
+import { IP } from "@sdxc/ip";
+import { isFailure } from "@sdxc/result";
+
+let messages: Record<IP.ErrorCode, string> = {
+	"invalid-address": "Enter an IPv4 or IPv6 address",
+	"invalid-range": "Enter a range such as 10.0.0.0/8",
+	"host-bits-set": "Use the network's first address, such as 10.0.0.0/8",
+};
+
+function validateRange(text: string): string | null {
+	let range = IP.Range.parse(text.trim());
+	return isFailure(range) ? messages[range.error.code] : null;
+}
+
+validateRange("10.0.0.1/8"); // "Use the network's first address, such as 10.0.0.0/8"
+```
+
+## Pattern: Functions That Only Accept A Checked Address
+
+Taking `IP` instead of `string` moves validation to the edge, and `toString()` stores the canonical form.
+
+```typescript
+import { IP } from "@sdxc/ip";
+import { isSuccess } from "@sdxc/result";
 
 function recordProbe(target: IP, at: number) {
-	return { target: target.toString(), at };
+	return { target: target.toString(), version: target.version, at };
 }
 
+let target = IP.parse("[2001:db8::0:1]");
+if (isSuccess(target)) recordProbe(target.data, Date.now()); // { target: "2001:db8::1", ... }
+
 recordProbe("10.0.0.1", Date.now()); // type error: a string is not an IP
 ```
 

package/dist/cli-classify.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `sdxc-ip classify` handler: parses the address and prints its version, canonical text,
+ * IANA special-purpose classification and any IPv4 it carries, as aligned lines or as JSON.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Classifies the address; `--json` prints `{ address, version, classification, public,
+ * embeddedIPv4 }`, with `embeddedIPv4` null outside the IPv4-mapped, NAT64 and 6to4 prefixes.
+ * Text that is not an address exits 2.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly address: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-classify.js

@@ -0,0 +1,43 @@
+/**
+ * The `sdxc-ip classify` handler: parses the address and prints its version, canonical text,
+ * IANA special-purpose classification and any IPv4 it carries, as aligned lines or as JSON.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { IP_COMMANDS } from "./cli-contract.js";
+import { readAddress } from "./cli-input.js";
+/**
+ * Classifies the address; `--json` prints `{ address, version, classification, public,
+ * embeddedIPv4 }`, with `embeddedIPv4` null outside the IPv4-mapped, NAT64 and 6to4 prefixes.
+ * Text that is not an address exits 2.
+ */
+export default createCommand(IP_COMMANDS.classify, async (ctx) => {
+    let parsed = await readAddress(ctx.arguments.address, ctx.stdin);
+    if (isFailure(parsed))
+        return parsed;
+    let ip = parsed.data;
+    let report = {
+        address: ip.toString(),
+        version: ip.version,
+        classification: ip.classification,
+        public: ip.isPublic,
+        embeddedIPv4: ip.embeddedIPv4?.toString() ?? null,
+    };
+    if (ctx.flags.json) {
+        ctx.stdout(`${JSON.stringify(report, null, 2)}\n`);
+        return success();
+    }
+    let lines = [
+        `address         ${report.address}`,
+        `version         ${report.version}`,
+        `classification  ${report.classification}`,
+        `public          ${report.public ? "yes" : "no"}`,
+    ];
+    if (report.embeddedIPv4 !== null)
+        lines.push(`embedded IPv4   ${report.embeddedIPv4}`);
+    ctx.stdout(`${lines.join("\n")}\n`);
+    return success();
+});

package/dist/cli-contains.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `sdxc-ip contains` handler: parses a range and an address and answers membership in the
+ * exit code, so a shell script can branch on it; stdout says the same for a person or as JSON.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Exits 0 when the range holds the address and 1 when it does not; an address of the other
+ * version is always outside. A malformed range, one with host bits set, or text that is not an
+ * address exits 2. `--json` prints `{ range, address, contains }` with both in canonical text.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly range: import("@sdxc/cli").Argument<string>;
+    readonly address: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-contains.js

@@ -0,0 +1,38 @@
+/**
+ * The `sdxc-ip contains` handler: parses a range and an address and answers membership in the
+ * exit code, so a shell script can branch on it; stdout says the same for a person or as JSON.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, exit, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { IP_COMMANDS } from "./cli-contract.js";
+import { readAddress } from "./cli-input.js";
+import { IP } from "./ip.js";
+/**
+ * Exits 0 when the range holds the address and 1 when it does not; an address of the other
+ * version is always outside. A malformed range, one with host bits set, or text that is not an
+ * address exits 2. `--json` prints `{ range, address, contains }` with both in canonical text.
+ */
+export default createCommand(IP_COMMANDS.contains, async (ctx) => {
+    let range = IP.Range.parse(ctx.arguments.range);
+    if (isFailure(range)) {
+        let reason = range.error.code === "host-bits-set"
+            ? `${JSON.stringify(ctx.arguments.range)} has bits set past its prefix; write the network's first address`
+            : `Not an IP range: ${JSON.stringify(ctx.arguments.range)}`;
+        return exit(2, reason);
+    }
+    let address = await readAddress(ctx.arguments.address, ctx.stdin);
+    if (isFailure(address))
+        return address;
+    let contains = range.data.contains(address.data);
+    if (ctx.flags.json) {
+        let report = { range: range.data.toString(), address: address.data.toString(), contains };
+        ctx.stdout(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        ctx.stdout(`${address.data.toString()} is ${contains ? "inside" : "outside"} ${range.data.toString()}\n`);
+    }
+    return contains ? success() : exit(1);
+});

package/dist/cli-contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `sdxc-ip` command line as a contract: `classify` names what an address is for, and
+ * `contains` tests whether a range holds an address. Help, usage errors and each handler's
+ * typed `ctx.arguments` and `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every command `sdxc-ip` takes. */
+export declare const IP_COMMANDS: import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-ip — IPv4 and IPv6 addresses against the IANA special-purpose registries";
+    readonly classify: import("@sdxc/cli").Command<{
+        readonly address: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly contains: import("@sdxc/cli").Command<{
+        readonly range: import("@sdxc/cli").Argument<string>;
+        readonly address: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;

package/dist/cli-contract.js

@@ -0,0 +1,56 @@
+/**
+ * The `sdxc-ip` command line as a contract: `classify` names what an address is for, and
+ * `contains` tests whether a range holds an address. Help, usage errors and each handler's
+ * typed `ctx.arguments` and `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { argument, command, commands, flag } from "@sdxc/cli";
+/**
+ * Accepts any text, so the package needs no schema library; each handler parses the text
+ * itself and answers its own exit 2 naming the rejected value.
+ */
+const TEXT = {
+    "~standard": {
+        version: 1,
+        vendor: "@sdxc/ip",
+        types: { input: undefined, output: "" },
+        validate(value) {
+            if (typeof value === "string")
+                return { value };
+            return { issues: [{ message: `expects text; got ${JSON.stringify(value)}` }] };
+        },
+    },
+};
+/** The `--json` flag every report-printing command takes. */
+function json() {
+    return flag.boolean("json", { description: "Print the result as JSON" });
+}
+/** Every command `sdxc-ip` takes. */
+export const IP_COMMANDS = commands({
+    description: "sdxc-ip — IPv4 and IPv6 addresses against the IANA special-purpose registries",
+    classify: command({
+        description: "Print an address's version, canonical form and IANA special-purpose classification",
+        arguments: {
+            address: argument(TEXT, {
+                default: "-",
+                description: "The address, or - to read it from stdin",
+            }),
+        },
+        flags: { json: json() },
+        examples: ["classify 192.168.1.10", "classify ::ffff:10.0.0.1 --json", "classify - < ip.txt"],
+    }),
+    contains: command({
+        description: "Exit 0 when the range holds the address and 1 when it does not",
+        arguments: {
+            range: argument(TEXT, { description: "The range as network/prefix" }),
+            address: argument(TEXT, {
+                default: "-",
+                description: "The address, or - to read it from stdin",
+            }),
+        },
+        flags: { json: json() },
+        examples: ["contains 10.0.0.0/8 10.1.2.3", "contains 2001:db8::/32 2001:db8::1 --json"],
+    }),
+});

package/dist/cli-input.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What every `sdxc-ip` command shares: reading the address from its argument or stdin and
+ * parsing it, so both commands refuse the same input with the same exit 2 and message.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ExitError, HandlerContext } from "@sdxc/cli";
+import type { Result } from "@sdxc/result";
+import type { IP_COMMANDS } from "./cli-contract.js";
+import { IP } from "./ip.js";
+/** The stdin every command reads a `-` address from. */
+type Stdin = HandlerContext<typeof IP_COMMANDS.classify>["stdin"];
+/**
+ * The address an argument names: the text as typed, or stdin's text trimmed for `-`. A
+ * terminal on stdin exits 2, so a command never waits on a person typing.
+ *
+ * @param value - The argument as typed
+ * @param stdin - The run's stdin, read when `value` is `-`
+ * @returns The parsed address, or an exit 2 naming the rejected text
+ */
+export declare function readAddress(value: string, stdin: Stdin): Promise<Result<IP, ExitError>>;
+export {};

package/dist/cli-input.js

@@ -0,0 +1,30 @@
+/**
+ * What every `sdxc-ip` command shares: reading the address from its argument or stdin and
+ * parsing it, so both commands refuse the same input with the same exit 2 and message.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { exit } from "@sdxc/cli";
+import { isFailure, success } from "@sdxc/result";
+import { IP } from "./ip.js";
+/**
+ * The address an argument names: the text as typed, or stdin's text trimmed for `-`. A
+ * terminal on stdin exits 2, so a command never waits on a person typing.
+ *
+ * @param value - The argument as typed
+ * @param stdin - The run's stdin, read when `value` is `-`
+ * @returns The parsed address, or an exit 2 naming the rejected text
+ */
+export async function readAddress(value, stdin) {
+    let text = value;
+    if (text === "-") {
+        if (stdin.isTTY)
+            return exit(2, "No address: pass one, or pipe it on stdin");
+        text = (await stdin.text()).trim();
+    }
+    let parsed = IP.parse(text);
+    if (isFailure(parsed))
+        return exit(2, `Not an IP address: ${JSON.stringify(text)}`);
+    return success(parsed.data);
+}

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-ip` command-line program: the contract in `cli-contract.ts` with each command mapped
+ * onto its handler, which loads only when that command runs. Exit codes: 0 done, 1 the address
+ * is outside the range, 2 usage or text that is not an address or a range.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The `sdxc-ip` program, run by the bin entry below and by tests through `invoke()`. */
+export declare const cli: import("@sdxc/cli").CLI<import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-ip — IPv4 and IPv6 addresses against the IANA special-purpose registries";
+    readonly classify: import("@sdxc/cli").Command<{
+        readonly address: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+    readonly contains: import("@sdxc/cli").Command<{
+        readonly range: import("@sdxc/cli").Argument<string>;
+        readonly address: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>, []>;

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-ip` command-line program: the contract in `cli-contract.ts` with each command mapped
+ * onto its handler, which loads only when that command runs. Exit codes: 0 done, 1 the address
+ * is outside the range, 2 usage or text that is not an address or a range.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCLI, lazy } from "@sdxc/cli";
+import { IP_COMMANDS } from "./cli-contract.js";
+/** The `sdxc-ip` program, run by the bin entry below and by tests through `invoke()`. */
+export const cli = createCLI({ name: "sdxc-ip", commands: IP_COMMANDS });
+cli.map(IP_COMMANDS.classify, lazy(() => import("./cli-classify.js")));
+cli.map(IP_COMMANDS.contains, lazy(() => import("./cli-contains.js")));
+if (import.meta.main) {
+    process.exit(await cli.run(process.argv.slice(2)));
+}

package/package.json

@@ -1,16 +1,20 @@
 {
 	"name": "@sdxc/ip",
-	"version": "2026.10.6",
+	"version": "2026.11.3",
 	"description": "IPv4 and IPv6 addresses and ranges as value objects that classify against the IANA special-purpose registries",
 	"license": "MIT",
+	"bin": {
+		"sdxc-ip": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js"
 	},
 	"dependencies": {
-		"@sdxc/result": "2026.10.6"
+		"@sdxc/cli": "2026.11.3",
+		"@sdxc/result": "2026.10.13"
 	},
-	"gitHead": "b1067eb20fc47ec51ff8c4de47d07dc3f9c00466",
+	"gitHead": "d1dd4030f8df68b8a170940a3f790ea8654d3676",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -19,7 +23,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/ip"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/ip",
+	"homepage": "https://sdxc.dev/api/ip",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"