@sdxc/ip 2026.10.13 → 2026.11.10

package/README.md

@@ -60,6 +60,22 @@ 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" }
 ```
 
+## Command line
+
+```sh
+bunx @sdxc/ip classify 192.168.1.10
+```
+
+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: string): Result<IP, IP.Error>`

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.13",
+	"version": "2026.11.10",
 	"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/cli": "2026.11.10",
 		"@sdxc/result": "2026.10.13"
 	},
-	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"gitHead": "6191b60a13885b1d826884d574c4a393f9b8eeee",
 	"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"