@adviser/ovn-fabric 0.1.1 → 0.1.3

package/README.md

@@ -17,33 +17,41 @@ a disposable, regeneratable artifact.
 
 **Via npx** (no local Deno install required — the official
 [`deno`](https://www.npmjs.com/package/deno) npm package is pulled in
-automatically as a dependency the first time you run this):
+automatically as a dependency the first time you run this; note the package
+is scoped, so it's `npx @adviser/ovn-fabric`, not `npx ovn-fabric`):
 
 ```sh
-npx ovn-fabric generate-ovn path/to/topology.ts > install.sh
+npx @adviser/ovn-fabric generate-ovn path/to/topology.ts > install.sh
 ```
 
-**Via Deno**, if you already have it:
+**Via Deno**, if you already have it (the CLI is the `/cli` export — the bare
+package name is the library, for use from your own `topology.ts`, see below):
 
 ```sh
-deno run -A jsr:@adviser/ovn-fabric generate-ovn path/to/topology.ts > install.sh
+deno run -A jsr:@adviser/ovn-fabric/cli generate-ovn path/to/topology.ts > install.sh
 ```
 
 **As a permanent global command**:
 
 ```sh
-deno install -g -A -n ovn-fabric jsr:@adviser/ovn-fabric
+deno install -g -A -n ovn-fabric jsr:@adviser/ovn-fabric/cli
 ```
 
 ## Quickstart
 
 Copy [`examples/minimal-topology.ts`](examples/minimal-topology.ts) as a
-starting point:
+starting point. Everything you need to declare a topology comes from the one
+package import — `defineNetwork`, every uplink/segment factory, and the
+public types (`Host`, `Uplink`, `Segment`, `ManualUplink`, ...) all live at
+the same `@adviser/ovn-fabric` / `jsr:@adviser/ovn-fabric` path:
 
 ```ts
-import { defineNetwork } from "jsr:@adviser/ovn-fabric/define";
-import { segmentPhysical, uplinkPhysical } from "jsr:@adviser/ovn-fabric/factories";
-import { ManualUplink } from "jsr:@adviser/ovn-fabric/types";
+import {
+  defineNetwork,
+  segmentPhysical,
+  uplinkPhysical,
+  ManualUplink,
+} from "jsr:@adviser/ovn-fabric";
 
 export const network = defineNetwork("minimal", (net) => {
   const host = net.localHost("this-host");
@@ -68,8 +76,8 @@ export const network = defineNetwork("minimal", (net) => {
 Then:
 
 ```sh
-npx ovn-fabric generate topology.ts       # sanity-check what it declares
-npx ovn-fabric generate-ovn topology.ts   # emit the install script(s)
+npx @adviser/ovn-fabric generate topology.ts       # sanity-check what it declares
+npx @adviser/ovn-fabric generate-ovn topology.ts   # emit the install script(s)
 ```
 
 `generate-ovn` prints one script per distinct `Host` your config declares.

package/bin/ovn-fabric.js

@@ -1,27 +1,44 @@
 #!/usr/bin/env node
 // bin/ovn-fabric.js — the npx/npm entry point.
 //
-// ovn-fabric itself is a Deno/TypeScript CLI (see src/cli.ts) — this
-// shim is the only piece of the npm distribution that runs under Node.
-// It does nothing but locate the `deno` executable (installed
-// automatically as this package's own npm dependency — see
+// ovn-fabric itself is a Deno/TypeScript CLI (see src/cli.ts, exported
+// as "./cli" from deno.json) — this shim is the only piece of the npm
+// distribution that runs under Node. It locates the `deno` executable
+// (installed automatically as this package's own npm dependency — see
 // https://www.npmjs.com/package/deno, the official, Deno-team-
-// maintained npm distribution of the Deno runtime itself) and hand off
-// to it with the bundled src/cli.ts as the entrypoint. `deno` handles
-// picking the right prebuilt binary for the current OS/arch on its own
-// (via its optionalDependencies + postinstall) — nothing here needs to
-// know or care what platform it's running on.
+// maintained npm distribution of the Deno runtime itself) and hands
+// off to it, running the CANONICAL, JSR-published module rather than a
+// bundled local copy.
+//
+// Why not just bundle src/ in this npm package and run it directly?
+// Because Deno refuses to type-strip .ts files that live inside any
+// node_modules directory (mirrors Node's own restriction on its native
+// TypeScript support) — once this package is npm-installed, its own
+// files necessarily live under node_modules/@adviser/ovn-fabric/, so
+// handing deno a local .ts path there fails with
+// ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. Delegating to the JSR
+// copy sidesteps that entirely (JSR-fetched modules are cached outside
+// node_modules) and, as a bonus, keeps exactly one published source of
+// truth instead of two copies that can drift out of sync.
+//
+// The JSR fetch is pinned to this exact installed npm version (see
+// package.json's own "version", kept in lockstep with deno.json by CI
+// — see scripts/patch-version.mjs) — this is a specific, already-
+// decided version the user just chose by installing this npm package,
+// not a "floating, could be anything" dependency, so bypassing Deno's
+// minimum-dependency-age check for THIS fetch only is a narrow,
+// justified override rather than a blanket safety bypass.
 "use strict";
 
-const path = require("path");
 const { spawnSync } = require("child_process");
+const pkg = require("../package.json");
 
 // deno/bin.cjs is itself a small Node launcher (see the `deno` npm
 // package) that locates/spawns the real deno binary and forwards
 // argv — resolved via require.resolve so this works regardless of how
 // npm/pnpm/yarn hoisted node_modules.
 const denoLauncher = require.resolve("deno/bin.cjs");
-const cliEntry = path.join(__dirname, "..", "src", "cli.ts");
+const moduleSpecifier = `jsr:@adviser/ovn-fabric@${pkg.version}/cli`;
 
 const result = spawnSync(
   process.execPath,
@@ -30,7 +47,8 @@ const result = spawnSync(
     "run",
     "--allow-read",
     "--allow-env",
-    cliEntry,
+    "--minimum-dependency-age=0",
+    moduleSpecifier,
     ...process.argv.slice(2),
   ],
   { stdio: "inherit" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adviser/ovn-fabric",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Declarative OVN/OVS topology generator — one config, one self-installing shell script per host.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -11,7 +11,6 @@
   },
   "files": [
     "bin",
-    "src",
     "README.md",
     "LICENSE"
   ],

package/src/addressing.ts

@@ -1,222 +0,0 @@
-// src/addressing.ts — the three fold rules, exactly once each, exposed
-// as NetId factories.
-//
-// Fold operation = string construction. Decimal identifiers are placed
-// directly into the address text, so the result stays human-readable
-// and visually corresponds to its IPv4 counterpart (fd00:10:80::128:1
-// reads as "segment 128", the same way 10.80.128.1 does). IPAddress.parse()
-// is called ONLY AFTER the string is fully built — it validates the
-// result and returns a real IPAddress for everything downstream
-// (containment checks, to_string(), comparisons). There is no integer
-// arithmetic on Crunchy here: that produces hex-folded results (segment
-// 128 -> "80") which breaks the human-readability property these rules
-// exist for.
-
-import { IPAddress } from "npm:ipaddress@0.2.6";
-import {
-  type NetId,
-  segmentId,
-  type SegmentId,
-  uplinkId,
-  type UplinkId,
-} from "./types.ts";
-
-function makeNetId(
-  ipv4Str: string,
-  ipv6Str: string,
-  rawId: number,
-  vlan: number | undefined,
-): NetId {
-  const ipv4 = IPAddress.parse(ipv4Str);
-  const ipv6 = IPAddress.parse(ipv6Str);
-  return {
-    ipv4,
-    ipv6,
-    id: () => rawId,
-    vlan: () => vlan,
-  };
-}
-
-// ── backbone: one shared /16, every identifier gets its own /28 block ──
-//
-// IPv4: 10.80.0.0/16, 4096 /28 blocks (same partition scheme as
-// transferNet's 10.99.0.0/16 — see that function's comment for the
-// general approach). block_base = identifier << 4. Within a block,
-// SEGMENTS use the low half (host offsets 1-7) and UPLINKS use the
-// high half (block_base | 0x8, host offsets 1-7 within that half) —
-// so a segment and an uplink that happen to share the same numeric
-// slot can never collide, both halves fit in the same /28 without
-// overlapping.
-//
-// IPv6 has no equivalent scarcity (128 bits is enormous) — it keeps
-// directly folding the real identifier into the network portion, with
-// a literal 0/8 marker group distinguishing segment vs uplink, so the
-// human-readability property (you can read an id straight out of the
-// address) is preserved on the v6 side even though v4 has to use the
-// less-readable shifted-block scheme to fit in 32 bits.
-//
-// No physical VLAN on either — the backbone is OVN-internal transit,
-// not wired to any single segment's or uplink's physical VLAN. vlan()
-// is always undefined.
-
-function backboneBlockAddress(blockBase: number, host: number): string {
-  if (host < 1 || host > 7) {
-    throw new RangeError(`backbone host out of range (1-7): ${host}`);
-  }
-  const third = (blockBase >> 8) & 0xff;
-  const fourth = (blockBase & 0xff) + host;
-  return `10.80.${third}.${fourth}`;
-}
-
-export function segmentBackboneNet(
-  segment: SegmentId | number,
-  host: number,
-): NetId {
-  const id = typeof segment === "number" ? segmentId(segment) : segment;
-  const blockBase = id << 4;
-  return makeNetId(
-    `${backboneBlockAddress(blockBase, host)}/16`,
-    `fd00:10:80::0:${id}:${host}/64`,
-    id,
-    undefined,
-  );
-}
-
-export function uplinkBackboneNet(
-  uplink: UplinkId | number,
-  slot: number,
-  host: number,
-): NetId {
-  // `slot` (not the real uplink id) drives the IPv4 block-shift, same
-  // as transferNet — uplink ids like 1280 are far too large to use
-  // directly in <<4 arithmetic (1280<<4 = 20480, producing a
-  // meaningless-looking but technically-valid address in the wrong
-  // place: 10.80.80.x). `slot` MUST be the same small sequential index
-  // (0,1,2,...) NetworkBuilder already assigns for the transfer link
-  // (see define.ts), so an uplink's backbone leg and transfer leg use
-  // consistent, small, collision-free numbering. The real uplink id is
-  // still used for the IPv6 fold, which has no such size constraint.
-  const id = typeof uplink === "number" ? uplinkId(uplink) : uplink;
-  if (slot < 0 || slot > 4095) {
-    throw new RangeError(`uplinkBackboneNet: slot out of range (0-4095): ${slot}`);
-  }
-  const blockBase = (slot << 4) | 0x8;
-  return makeNetId(
-    `${backboneBlockAddress(blockBase, host)}/16`,
-    `fd00:10:80::8:${id}:${host}/64`,
-    id,
-    undefined,
-  );
-}
-
-// ── client segments: one network PER SEGMENT, identifier folds into the
-//    NETWORK portion ──
-// fd00:192:168:<segment>::<host>/64  <->  192.168.<segment>.<host>/24
-//
-// vlan() returns the segment id itself when the segment's physical VLAN
-// tag matches its numeric id (true for every segment built so far —
-// segment 128 is VLAN 128, etc.). Pass an explicit vlan to override
-// (e.g. segment 128 is untagged on the wire, so its real VLAN concept
-// doesn't apply the same way — see untaggedOnWire on Segment).
-
-export function segmentNet(
-  segment: SegmentId | number,
-  host: number,
-  vlan?: number,
-): NetId {
-  const id = typeof segment === "number" ? segmentId(segment) : segment;
-  return makeNetId(
-    `192.168.${id}.${host}/24`,
-    `fd00:192:168:${id}::${host}/64`,
-    id,
-    vlan ?? id,
-  );
-}
-
-// ── transfer links: one network PER UPLINK, identifier folds into the
-//    NETWORK portion ──
-// fd00:10:99:<uplink>::<host>/124  <->  10.99.<third>.<fourth>/28
-//
-// IPv4: 10.99.0.0/16 holds exactly 4096 /28 blocks (16 addresses each).
-// `slot` (0-4095) selects which block — slot N is the Nth /28 in
-// sequence: slot 0 = 10.99.0.0/28, slot 1 = 10.99.0.16/28, ...,
-// slot 128 = 10.99.8.0/28, etc. `slot` is NOT the uplink's own id
-// (uplink ids like 1280/1281/1282 exceed 4095 and aren't sequential
-// from 0) — it's a small sequential index the caller assigns, one per
-// uplink, distinct from the uplink's real identity. See define.ts,
-// where NetworkBuilder assigns slots automatically in declaration
-// order so config/topology.ts never has to think about this at all.
-//
-// IPv6 still folds the uplink's real id (not slot) into the network
-// portion, since IPv6 has no equivalent address-space scarcity forcing
-// a slot scheme — fd00:10:99:1280::/124 is perfectly fine on its own.
-//
-// No physical VLAN on the OVN side of a transfer link — vlan() is
-// undefined here; the REAL uplink (see uplinkNet below) is what carries
-// the physical VLAN tag.
-
-export function transferNet(
-  uplink: UplinkId | number,
-  slot: number,
-  host: number,
-): NetId {
-  const id = typeof uplink === "number" ? uplinkId(uplink) : uplink;
-  if (slot < 0 || slot > 4095) {
-    throw new RangeError(`transfer slot out of range (0-4095): ${slot}`);
-  }
-  if (host < 1 || host > 14) {
-    throw new RangeError(`transfer host out of range (1-14): ${host}`);
-  }
-  const blockBase = slot * 16; // 0-65520, fits in 16 bits
-  const third = (blockBase >> 8) & 0xff;
-  const fourth = (blockBase & 0xff) + host;
-  return makeNetId(
-    `10.99.${third}.${fourth}/28`,
-    `fd00:10:99:${id}::${host}/124`,
-    id,
-    undefined,
-  );
-}
-
-// ── uplink's real-world physical identity ──────────────────────────
-// The uplink's own VLAN (e.g. 1280 for an uplink named isp-primary) — this is the ONE
-// place vlan() reflects a real physical tag tied 1:1 to the uplink
-// numeric id, since every uplink built so far uses vlanId === id.
-// No IPv4/IPv6 addressing of its own (the uplink's real address is
-// whatever the ISP hands out dynamically) — ipv4/ipv6 here are the
-// transfer link's OVN-side address, reused, so every NetId still
-// satisfies the same shape.
-
-export function uplinkNet(
-  uplink: UplinkId | number,
-  slot: number,
-): NetId {
-  const id = typeof uplink === "number" ? uplinkId(uplink) : uplink;
-  const transfer = transferNet(id, slot, 1);
-  return makeNetId(
-    transfer.ipv4.to_string(),
-    transfer.ipv6.to_string(),
-    id,
-    id,
-  );
-}
-
-// ── MAC address derivation ────────────────────────────────────────
-// Folds an IPv4 address's four octets directly into a MAC, prefixed
-// with 00:00 — the convention already used by hand throughout this
-// project (e.g. 192.168.128.2 -> 00:00:c0:a8:80:02, verified against a
-// live deployment). Locally-administered OUI space
-// (00:00:xx is not a real vendor block) is fine for this use — these
-// MACs only need to be unique within OVN's logical topology, never
-// routed on a real physical LAN segment.
-
-export function macFromV4(ipv4: IPAddress): string {
-  const octets = ipv4.to_s().split("/")[0].split(".").map((s) =>
-    Number.parseInt(s, 10)
-  );
-  if (octets.length !== 4 || octets.some((o) => Number.isNaN(o))) {
-    throw new Error(`macFromV4: not a valid IPv4 address: ${ipv4.to_s()}`);
-  }
-  const hex = octets.map((o) => o.toString(16).padStart(2, "0"));
-  return `00:00:${hex.join(":")}`;
-}

package/src/cli.ts

@@ -1,163 +0,0 @@
-// src/cli.ts — the CLI entry point.
-// Library code: defines the command surface. Does not know about any
-// concrete topology — the config module path is supplied at the
-// command line, imported dynamically. The config module must export a
-// NetworkDefinition (the return value of defineNetwork()), under any
-// export name — the loader looks for the first export matching that
-// shape rather than requiring a specific name, since defineNetwork
-// already collects allUplinks/allSegments and a second, separately
-// named re-export of the same data would just be duplication.
-
-import {
-  command,
-  positional,
-  run,
-  string,
-  subcommands,
-} from "npm:cmd-ts@0.13.0";
-
-import { generateOvnScripts } from "./generate-ovn.ts";
-import type { NetworkDefinition } from "./define.ts";
-import type { Host, InterfaceKind } from "./types.ts";
-
-function describeAccess(host: Host): string {
-  return host.access.method === "ssh"
-    ? `ssh ${host.access.user}@${host.address}`
-    : `local`;
-}
-
-function describeInterface(ifc: InterfaceKind): string {
-  switch (ifc.kind) {
-    case "vlan":
-      return `vlan ${ifc.vlanId} on ${ifc.vlanParent}` +
-        (ifc.ifaceName ? ` (as ${ifc.ifaceName})` : "");
-    case "physical":
-      return `physical ${ifc.name}`;
-    case "bridge-port":
-      return `bridge-port ${ifc.port} on ${ifc.bridge}`;
-    case "wireguard":
-      return `wireguard ${ifc.ifaceName} -> ${ifc.config.peer.endpoint}`;
-    case "dummy":
-      return `dummy (placeholder, no real interface)`;
-  }
-}
-
-function isNetworkDefinition(value: unknown): value is NetworkDefinition {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "name" in value &&
-    "allUplinks" in value &&
-    "allSegments" in value &&
-    Array.isArray((value as NetworkDefinition).allUplinks) &&
-    Array.isArray((value as NetworkDefinition).allSegments)
-  );
-}
-
-async function loadConfig(configPath: string): Promise<NetworkDefinition> {
-  const resolved = await Deno.realPath(configPath);
-  const mod = await import(`file://${resolved}`);
-
-  const found = Object.values(mod).find(isNetworkDefinition);
-  if (found === undefined) {
-    throw new Error(
-      `${configPath} does not export a NetworkDefinition ` +
-        `(the return value of defineNetwork(...))`,
-    );
-  }
-  return found;
-}
-
-const generate = command({
-  name: "generate",
-  description:
-    "Load a topology config and report what it declares.",
-  args: {
-    configPath: positional({
-      type: string,
-      displayName: "config-path",
-      description: "Path to a topology config module (e.g. config/topology.ts)",
-    }),
-  },
-  handler: async ({ configPath }) => {
-    const net = await loadConfig(configPath);
-
-    console.log(`Loaded network: ${net.name} (from ${configPath})`);
-    console.log(`  uplinks: ${net.allUplinks.length}`);
-    for (const u of net.allUplinks) {
-      const addrSummary = u.addresses
-        .map((a) => `${a.ipv4.to_string()} / ${a.ipv6.to_string()}`)
-        .join(", ");
-      console.log(
-        `    - ${u.name} (if=${describeInterface(u.if)}, ` +
-          `addresses=[${addrSummary}], host=${u.host.name} [${describeAccess(u.host)}])`,
-      );
-    }
-    console.log(`  segments: ${net.allSegments.length}`);
-    for (const s of net.allSegments) {
-      // undefined uplink = deliberately isolated, no egress yet (see
-      // Segment.uplink, types.ts) — not a missing-data bug.
-      const selectorKind = s.uplink?.constructor.name ?? "(none)";
-      const uplinkName = s.uplink?.resolve().name ?? "(isolated, no uplink)";
-      const addrSummary = s.addresses
-        .map((a) => `${a.ipv4.to_string()} / ${a.ipv6.to_string()}`)
-        .join(", ");
-      console.log(
-        `    - ${s.name} (if=${describeInterface(s.if)}, ` +
-          `addresses=[${addrSummary}], uplink=${uplinkName}, ` +
-          `selector=${selectorKind}, host=${s.host.name} [${describeAccess(s.host)}])`,
-      );
-    }
-  },
-});
-
-const generateOvn = command({
-  name: "generate-ovn",
-  description:
-    "Emit ONE self-installing shell script per host: copy it to the " +
-    "host and run it. Sets up OVS bridges/interfaces (no netplan), " +
-    "configures the full OVN topology, and installs itself as a " +
-    "boot-time systemd unit (see generate-ovn.ts header comment). " +
-    "Pure text output; does not execute anything itself.",
-  args: {
-    configPath: positional({
-      type: string,
-      displayName: "config-path",
-      description: "Path to a topology config module (e.g. config/topology.ts)",
-    }),
-  },
-  handler: async ({ configPath }) => {
-    const net = await loadConfig(configPath);
-    const scripts = generateOvnScripts(net);
-    // The separator must NEVER be the first line of the combined
-    // output: each per-host script is meant to be saved as-is and run
-    // directly (including by systemd's ExecStart, which execs the file
-    // itself rather than piping it through a shell) — a leading
-    // comment line before "#!/bin/sh" breaks that exec entirely
-    // (ENOEXEC), silently no-op'ing the whole setup. Confirmed live,
-    // 2026-07-06: the installed copy had this marker as line 1, so the
-    // boot-time systemd unit never ran a single command, and nothing
-    // it was meant to create (e.g. br-bd-4) ever existed. `sh
-    // script.sh` tolerates it fine (comments are skipped) — only
-    // direct exec doesn't — so this only ever shows up in the one path
-    // this generator is actually designed around. Only print the
-    // separator BETWEEN scripts (today, with one host declared, it
-    // never prints at all).
-    let first = true;
-    for (const [hostName, script] of scripts) {
-      if (!first) console.log(`# ===== host: ${hostName} =====`);
-      first = false;
-      console.log(script);
-    }
-  },
-});
-
-const app = subcommands({
-  name: "ovn-fabric",
-  description: "Declarative OVN/OVS topology generator CLI",
-  cmds: { generate, "generate-ovn": generateOvn },
-});
-
-if (import.meta.main) {
-  await run(app, Deno.args);
-}