@homeflare/alchemy 0.15.0 → 0.19.1

package/src/netbox/client.ts

@@ -0,0 +1,146 @@
+/**
+ * One authenticated call to the NetBox REST API at `/api`.
+ *
+ * ⚠️ `Authorization: Token <value>`, NOT `Bearer`. NetBox is Django REST Framework using DRF's own
+ *   `TokenAuthentication`. MEASURED on this estate's own instance while it was up: `Bearer`
+ *   returns 401 and `Token` returns 200. ⛔ A wrong scheme and a wrong credential are
+ *   indistinguishable in the response, which is why this is written down rather than inferred.
+ *
+ * ⚠️ NETBOX DOES NOT WRAP A DETAIL RESPONSE THE WAY PVE DOES — a GET of one object returns the
+ *   object. A LIST, however, IS wrapped: `{count, next, previous, results: [...]}`. A caller that
+ *   treats a list like a detail sees `undefined` and calls a healthy object absent, which plans a
+ *   create over something that already exists.
+ *
+ * ⛔ THE TOKEN IS NEVER A PROP. It is read from `NETBOX_TOKEN` at call time only. Alchemy persists
+ *   attributes unencrypted; nothing stored here may be a credential.
+ */
+import * as Effect from 'effect/Effect';
+import * as HttpClient from 'effect/unstable/http/HttpClient';
+import * as HttpClientRequest from 'effect/unstable/http/HttpClientRequest';
+
+const PATH_PREFIX = '/api';
+
+/**
+ * The instance, from `NETBOX_URL`. Trailing slash stripped.
+ *
+ * ⛔ NO DEFAULT HOSTNAME AND NO DEFAULT PORT. A published package that fell back to a loopback
+ *   address would let a consumer who forgot the variable watch every call fail against a machine
+ *   that is not theirs, instead of being told which variable is missing.
+ * ⚠️ Read at CALL time, never at module scope — a value captured at import is pinned to whatever
+ *   the first isolate saw.
+ */
+export const apiBase = (): string => {
+  const raw = process.env['NETBOX_URL'];
+  if (raw === undefined || raw.trim() === '') {
+    throw new Error(
+      'NETBOX_URL is not set. Point it at your NetBox instance, e.g. https://netbox.example.com',
+    );
+  }
+  return raw.trim().replace(/\/$/, '');
+};
+
+export class NetboxError extends Error {
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    detail: string,
+  ) {
+    super(`NetBox ${method} ${path} -> ${String(status)}: ${detail}`);
+    this.name = 'NetboxError';
+  }
+}
+
+const token = (): Effect.Effect<string, NetboxError> =>
+  Effect.gen(function* () {
+    const raw = process.env['NETBOX_TOKEN'];
+    if (raw === undefined || raw.trim() === '') {
+      return yield* Effect.fail(
+        new NetboxError(
+          0,
+          'GET',
+          '',
+          'NETBOX_TOKEN is unset. Mint a scoped token and export it — never store it in Alchemy props.',
+        ),
+      );
+    }
+    return raw.trim();
+  });
+
+/** A NetBox list response. ⚠️ Paginated: `next` is a URL, not a cursor to guess at. */
+export interface NetboxList<T> {
+  readonly count: number;
+  readonly next: string | null;
+  readonly results: readonly T[];
+}
+
+export type NetboxRow = Record<string, unknown>;
+
+/** One JSON call. Returns the parsed body, or `undefined` when the response is empty (DELETE). */
+export const netbox = <T>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) =>
+  Effect.gen(function* () {
+    const credential = yield* token();
+    const url = `${apiBase()}${PATH_PREFIX}/${path.replace(/^\//, '')}`;
+    /**
+     * ★ THROUGH `HttpClient`, NOT THE GLOBAL `fetch` — the idiom Alchemy's own providers follow.
+     *   It buys a typed error channel, interruption when a plan is cancelled, the runtime's
+     *   tracing, and a client a test can replace without monkey-patching a global.
+     */
+    const client = yield* HttpClient.HttpClient;
+    /**
+     * ⛔ THE CONTENT TYPE GOES ON `bodyText`, NOT IN THE HEADER MAP. `bodyText(s)` with no second
+     *   argument sets `text/plain` and OVERWRITES a `Content-Type` set by `setHeaders`, because it
+     *   is piped afterwards. That shipped `@homeflare/alchemy/forgejo` unable to write at all —
+     *   every create and update in the package, broken identically, for as long as the only
+     *   credential on the shelf was read-only and so never reached a request body.
+     */
+    const request = HttpClientRequest.make(method)(url).pipe(
+      HttpClientRequest.setHeaders({
+        Accept: 'application/json',
+        Authorization: `Token ${credential}`,
+      }),
+      body === undefined
+        ? (self) => self
+        : HttpClientRequest.bodyText(JSON.stringify(body), 'application/json'),
+    );
+    const response = yield* client
+      .execute(request)
+      .pipe(Effect.mapError((cause) => new NetboxError(0, method, path, String(cause))));
+    // ⛔ Status first, body once — a NetBox error body is JSON but a reverse proxy's 502 is not.
+    //   ⚠️ AND A 502 IS THE EXPECTED SYMPTOM WHEN NETBOX IS DOWN BUT ITS FRONT DOOR IS UP, which
+    //   is the state the reference instance has been in since 2026-09-14. Folding it to "absent"
+    //   would plan a create for every object that already exists.
+    if (response.status < 200 || response.status >= 300) {
+      const detail = yield* response.text.pipe(Effect.orElseSucceed(() => ''));
+      return yield* Effect.fail(
+        new NetboxError(response.status, method, path, detail.slice(0, 300)),
+      );
+    }
+    // ⚠️ 204 AND AN EMPTY BODY ARE REAL: a DELETE answers no content, and parsing an empty body
+    //   throws. Read the text once and parse only when there is something to parse.
+    const text = yield* response.text.pipe(
+      Effect.mapError((cause) => new NetboxError(0, method, path, String(cause))),
+    );
+    return (text === '' ? undefined : JSON.parse(text)) as T;
+  });
+
+/**
+ * The single row a filtered list returns, or `undefined`.
+ *
+ * ⛔ MORE THAN ONE MATCH IS A DEFECT, NOT A REASON TO TAKE THE FIRST. A `locate` filter that is
+ *   not unique would let adopt bind to whichever row NetBox happened to order first, and the next
+ *   plan would bind to the other one and report drift that is not there.
+ */
+export const soleMatch = <T>(rows: readonly T[], describe: string): T | undefined => {
+  if (rows.length > 1) {
+    throw new Error(
+      `${describe} matched ${String(rows.length)} NetBox objects. An object's identity must be ` +
+        'unique; narrow it (the VRF, the site, the tenant) rather than taking the first row.',
+    );
+  }
+  return rows[0];
+};

package/src/netbox/constraint-guard.ts

@@ -0,0 +1,57 @@
+/**
+ * The generated tables, looked up by endpoint, and the refusal that stops a plan.
+ *
+ * ★ ONE FILE BETWEEN THE PROVIDERS AND THE GENERATED DATA, so `resource.ts` gains three lines
+ *   rather than an import of the generated module and a merge, and so a family that writes its
+ *   own handlers reaches the same check by the same name.
+ *
+ * ⛔ AN UNKNOWN KEY IS A DEFECT, NOT A REASON TO SKIP THE CHECK. Silently passing would put us
+ *   back where this started: a declaration nothing checked, and a plan that says so in no way at
+ *   all. The generator resolves every key in its source scan against the vendor document, so a
+ *   key that is absent here means the tables were not regenerated — which the message says.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  type EndpointConstraints,
+  type EndpointKey,
+  type NetboxBody,
+  refusal,
+  violations,
+} from './constraints.ts';
+import { NETBOX_CONSTRAINTS } from './generated/constraints/index.ts';
+
+export { NETBOX_CONSTRAINTS };
+
+export const constraintsFor = (key: EndpointKey): EndpointConstraints => {
+  const table = NETBOX_CONSTRAINTS[key];
+  if (table === undefined) {
+    throw new Error(
+      `no vendor constraint table for '${key}'. It is named in this package but not generated: ` +
+        'run `bun codegen/netbox.ts` (see codegen/README.md).',
+    );
+  }
+  return table;
+};
+
+/** Every vendor rule this body breaks. Pure — a test calls it with a literal body. */
+export const bodyViolations = (
+  key: EndpointKey,
+  body: NetboxBody,
+  presence: boolean,
+): readonly string[] => violations(constraintsFor(key), body, { presence });
+
+/**
+ * ⛔ `Effect.die`, NOT `Effect.fail`. A declaration the vendor would reject is a DEFECT in the
+ *   stack file, not a recoverable condition: there is no retry and no fallback that makes a
+ *   201-character description legal.
+ */
+export const guardBody = (
+  key: EndpointKey | undefined,
+  body: NetboxBody,
+  presence: boolean,
+): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    if (key === undefined) return Effect.void;
+    const found = bodyViolations(key, body, presence);
+    return found.length === 0 ? Effect.void : Effect.die(new Error(refusal(key, found)));
+  });

package/src/netbox/constraints.test.ts

@@ -0,0 +1,114 @@
+/**
+ * The constraint reader over a JSON body — and the four ways a naive one gets it wrong.
+ *
+ * ★ EVERY RULE EXERCISED HERE COMES FROM THE GENERATED TABLE, not a literal invented in this
+ *   file, wherever a real endpoint states it. A test that made up its own `maxLength` would pass
+ *   forever while the committed table said something else.
+ */
+import { describe, expect, test } from 'bun:test';
+import { bodyViolations, constraintsFor } from './constraint-guard.ts';
+import { violations } from './constraints.ts';
+
+const CREATE = 'netbox:POST /api/ipam/prefixes/';
+const UPDATE = 'netbox:PATCH /api/ipam/prefixes/{id}/';
+
+describe('the generated table is the one being read', () => {
+  test('the prefix create table carries NetBox 4.7.0 own rules', () => {
+    const table = constraintsFor(CREATE);
+    expect(table['prefix']?.required).toBe(true);
+    expect(table['description']?.maxLength).toBe(200);
+    expect(table['status']?.enum).toEqual(['container', 'active', 'reserved', 'deprecated']);
+  });
+
+  /** ⛔ An unknown key is a defect: the tables were not regenerated, and silence would hide it. */
+  test('an endpoint nobody generated throws rather than passing everything', () => {
+    expect(() => constraintsFor('netbox:POST /api/dcim/devices/')).toThrow(
+      /no vendor constraint table/,
+    );
+  });
+});
+
+describe('what it refuses', () => {
+  test('a description one character over the vendor limit', () => {
+    const found = bodyViolations(
+      CREATE,
+      { description: 'x'.repeat(201), prefix: '10.0.0.0/24' },
+      true,
+    );
+    expect(found).toEqual(['description: at most 200 characters']);
+  });
+
+  test('exactly the limit is accepted', () => {
+    expect(
+      bodyViolations(CREATE, { description: 'x'.repeat(200), prefix: '10.0.0.0/24' }, true),
+    ).toEqual([]);
+  });
+
+  /**
+   * ⚠️ `[...value].length`, NOT `value.length`. An emoji is two UTF-16 code units and ONE
+   *   character; Django counts characters. Counting code units would refuse a description NetBox
+   *   accepts — rejecting a legal value at plan time being the failure worse than the 400.
+   */
+  test('a 200-character description made of astral characters is accepted', () => {
+    const found = bodyViolations(
+      CREATE,
+      { description: '🌐'.repeat(200), prefix: '10.0.0.0/24' },
+      true,
+    );
+    expect(found).toEqual([]);
+  });
+
+  test('a status outside the vendor enum', () => {
+    const found = bodyViolations(CREATE, { prefix: '10.0.0.0/24', status: 'retired' }, true);
+    expect(found).toEqual(['status: must be one of container, active, reserved, deprecated']);
+  });
+});
+
+describe('presence is a create-only rule', () => {
+  /** ⛔ A PATCH is deliberately partial; requiring presence would refuse every ordinary edit. */
+  test('a missing required property is refused on create and allowed on update', () => {
+    expect(bodyViolations(CREATE, { status: 'active' }, true)).toEqual(['prefix: required']);
+    expect(bodyViolations(UPDATE, { status: 'active' }, false)).toEqual([]);
+  });
+
+  /**
+   * ⚠️ `null` IS A VALUE, NOT AN ABSENCE. NetBox clears a nullable foreign key with an explicit
+   *   null, so a presence check that used `value === undefined` would call it missing.
+   */
+  test('an explicit null satisfies presence and trips no string rule', () => {
+    expect(bodyViolations(CREATE, { prefix: null }, true)).toEqual([]);
+  });
+});
+
+describe('a JSON body is not a form, and that changes the checks', () => {
+  /**
+   * ⛔ THE REASON THIS READER IS NOT THE PROXMOX ONE. `Number(false)` is 0, so a body that
+   *   coerced its values would pass a boolean straight through a `minimum: 0` and report nothing.
+   */
+  test('a boolean is never coerced into a numeric bound', () => {
+    const table = { count: { minimum: 1, type: 'integer' } } as const;
+    expect(violations(table, { count: false })).toEqual([]);
+    expect(violations(table, { count: 0 })).toEqual(['count: at least 1']);
+  });
+
+  test('an empty string is not treated as zero', () => {
+    const table = { count: { minimum: 0, type: 'integer' } } as const;
+    expect(violations(table, { count: '' })).toEqual([]);
+  });
+
+  /** ⚠️ An array is a repeated value — tags and every many-to-many — so each element is checked. */
+  test('every element of an array faces the same rule', () => {
+    const table = { names: { maxLength: 3, type: 'string' } } as const;
+    expect(violations(table, { names: ['ok', 'toolong', 'alsotoolong'] })).toEqual([
+      'names: at most 3 characters',
+      'names: at most 3 characters',
+    ]);
+  });
+
+  /** ⚠️ The table carries the CONSTRAINED properties, not every property. */
+  test('a key the table does not mention is not an error', () => {
+    expect(bodyViolations(CREATE, { prefix: '10.0.0.0/24', vrf: 4, whatever: 'x' }, true)).toEqual(
+      [],
+    );
+  });
+});

package/src/netbox/constraints.ts

@@ -0,0 +1,152 @@
+/**
+ * NetBox's own rules, checked here, before the request is built.
+ *
+ * 🔴 THE INCIDENT THIS PATTERN EXISTS FOR, 2026-09-22 (Proxmox, not NetBox). `homeflare-proxmox`'s
+ *   first `deploy:pbs` adopted ten objects and then failed its one create:
+ *   `comment: value may only be 128 characters long`. Half a deploy in, on the server, from a
+ *   limit the vendor publishes in its own schema and the generated type did not carry. Plan was
+ *   green, `bun run check` was green, the adopt verifier was green. ★ NetBox gets the same
+ *   treatment BEFORE its first write rather than after it.
+ *
+ * ★ SO THE TABLE IS GENERATED AND THIS FILE IS THE READER. `generated/constraints/*` is emitted
+ *   from NetBox's own OpenAPI document by `bun codegen/netbox.ts`; nothing here is hand-typed,
+ *   because a hand-typed limit is tribal knowledge that does not run.
+ *
+ * ⛔ A SEPARATE READER FROM `../proxmox/constraints.ts`, AND IT IS NOT DUPLICATION. That one
+ *   checks a `PveForm` — every value already a string, because PVE takes form encoding. A NetBox
+ *   body is JSON: a number stays a number, a boolean stays a boolean, a foreign key is an
+ *   integer, and `String(value)` on any of them would make `minimum: 0` pass for `false` and
+ *   `maxLength` meaningless. Sharing one reader would mean stringifying at the door, which is
+ *   exactly the mangling the Proxmox version's own ⛔ warns about.
+ *
+ * ⚠️ WHAT IT DELIBERATELY DOES NOT ENFORCE, so nobody reads a green plan as more than it is:
+ *   - a `format` NAME (`uri`, `email`, `date-time`): a validator DRF implements server-side.
+ *     Recorded, never checked.
+ *   - a pattern the generator could not carry faithfully (codegen/py-pattern.ts). Recorded
+ *     verbatim as `patternSource`, never checked.
+ *   - UNIQUENESS, VRF containment, custom-field validators, and every other rule that lives in
+ *     Django rather than in the schema. Those still arrive as a server-side 400.
+ *   Each is a fact in the table rather than a guess, which is the rule this follows: if the
+ *   vendor did not state it, it is not enforced and the table says so.
+ */
+
+export interface ParamConstraint {
+  readonly type?: string;
+  /** From the schema's `required` array. ⚠️ Checked on CREATE only — see `violations`. */
+  readonly required?: boolean;
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly enum?: readonly string[];
+  /** A JavaScript-safe translation. Absent when Python's dialect could not be carried over. */
+  readonly pattern?: string;
+  /** The vendor's own spelling, always — what a violation message quotes, and the audit trail. */
+  readonly patternSource?: string;
+  /** DRF's server-side validator name. Recorded so a reader knows what is NOT checked here. */
+  readonly format?: string;
+  readonly default?: string;
+}
+
+export type EndpointConstraints = Readonly<Record<string, ParamConstraint>>;
+
+/** `netbox:POST /api/ipam/prefixes/` — exactly how the generated tables key an endpoint. */
+export type EndpointKey = string;
+
+/** A NetBox request body: JSON, with the types the schema declares. */
+export type NetboxBody = Record<string, unknown>;
+
+export interface ViolationOptions {
+  /**
+   * Check that every schema-required property is present.
+   *
+   * ⛔ CREATE ONLY. A NetBox update is a PATCH and is deliberately PARTIAL — it carries the fields
+   *   that changed and nothing else — so requiring presence there would refuse every ordinary
+   *   edit.
+   */
+  readonly presence?: boolean;
+}
+
+/**
+ * ⚠️ `[...value].length`, NOT `value.length`. Django counts characters (Python `len` on a `str`
+ *   counts code points); JavaScript counts UTF-16 code units, so an emoji in a description counts
+ *   twice and a 200-character limit would refuse a description NetBox accepts. Rejecting a legal
+ *   value at plan time is the one failure mode worse than the server 400 this replaces.
+ */
+const lengthOf = (value: string): number => [...value].length;
+
+const checkString = (name: string, value: string, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (rule.maxLength !== undefined && lengthOf(value) > rule.maxLength) {
+    out.push(`${name}: at most ${String(rule.maxLength)} characters`);
+  }
+  if (rule.minLength !== undefined && lengthOf(value) < rule.minLength) {
+    out.push(`${name}: at least ${String(rule.minLength)} characters`);
+  }
+  if (rule.enum !== undefined && !rule.enum.includes(value)) {
+    out.push(`${name}: must be one of ${rule.enum.join(', ')}`);
+  }
+  if (rule.pattern !== undefined && !new RegExp(rule.pattern).test(value)) {
+    out.push(`${name}: must match ${rule.patternSource ?? rule.pattern}`);
+  }
+  return out;
+};
+
+/**
+ * ⛔ BOUNDS ARE CHECKED ONLY ON A REAL NUMBER, NEVER ON A COERCED ONE. `Number(false)` is 0 and
+ *   `Number('')` is 0, so coercing would silently pass a boolean and an empty string through a
+ *   `minimum: 0`. A NetBox body carries real numbers; anything else is a type error upstream.
+ */
+const checkNumber = (name: string, value: number, rule: ParamConstraint): string[] => {
+  const out: string[] = [];
+  if (!Number.isFinite(value)) return out;
+  if (rule.minimum !== undefined && value < rule.minimum) {
+    out.push(`${name}: at least ${String(rule.minimum)}`);
+  }
+  if (rule.maximum !== undefined && value > rule.maximum) {
+    out.push(`${name}: at most ${String(rule.maximum)}`);
+  }
+  return out;
+};
+
+const checkValue = (name: string, value: unknown, rule: ParamConstraint): readonly string[] => {
+  if (typeof value === 'string') return checkString(name, value, rule);
+  if (typeof value === 'number') return checkNumber(name, value, rule);
+  return [];
+};
+
+/**
+ * Every vendor rule this body breaks, in the order the properties are declared. Pure: no network,
+ * no clock, no environment — so `diff` can call it and a test can call it with a literal.
+ *
+ * ⚠️ A KEY THE TABLE DOES NOT MENTION IS NOT AN ERROR. The table carries the constrained
+ *   properties, not every property, and a body may legitimately send an unconstrained one.
+ * ⚠️ `null` IS A VALUE, NOT AN ABSENCE. NetBox uses explicit `null` to CLEAR a nullable foreign
+ *   key, so it must not trip the presence check — and no string or number rule applies to it.
+ */
+export const violations = (
+  table: EndpointConstraints,
+  body: NetboxBody,
+  options: ViolationOptions = {},
+): readonly string[] => {
+  const out: string[] = [];
+  for (const [name, rule] of Object.entries(table)) {
+    if (!Object.hasOwn(body, name)) {
+      if (options.presence === true && rule.required === true) out.push(`${name}: required`);
+      continue;
+    }
+    const value = body[name];
+    // ⚠️ AN ARRAY IS A REPEATED VALUE (tags, and every many-to-many), so every element faces the
+    //   same rule rather than the array being skipped as "not a scalar".
+    for (const item of Array.isArray(value) ? value : [value]) {
+      out.push(...checkValue(name, item, rule));
+    }
+  }
+  return out;
+};
+
+/** The message a plan dies with. ⛔ Names the endpoint, because the rule belongs to the vendor. */
+export const refusal = (endpoint: EndpointKey, found: readonly string[]): string =>
+  `${endpoint} would be rejected by the vendor:\n  - ${found.join('\n  - ')}\n` +
+  "These are NetBox's own limits, read from its published OpenAPI document " +
+  '(packages/alchemy/src/netbox/generated/constraints). Fix the declaration.';

package/src/netbox/generated/constraints/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Every generated NetBox constraint table, merged — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/netbox.ts
+ *
+ * ⚠️ EVERY KEY IS PREFIXED `netbox:` FOR THE SAME REASON THE PROXMOX TABLES ARE PREFIXED. One
+ *   estate runs several vendors and the reader is shared; an unprefixed `POST /api/…` would be
+ *   one vendor away from colliding.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+import { NETBOX_IPAM_CONSTRAINTS } from './netbox-ipam.ts';
+
+export const NETBOX_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  ...NETBOX_IPAM_CONSTRAINTS,
+};
+
+/**
+ * sha256 of the merged table, truncated.
+ *
+ * ★ A DIGEST OF THE DATA, NOT OF THE FILE TEXT, so reformatting is not a stale generation while
+ *   changing a 200 to a 201 by hand is. `tests/netbox-manifest.test.ts` recomputes it.
+ */
+export const NETBOX_CONSTRAINTS_DIGEST = '1de1cebe7491d94f';

package/src/netbox/generated/constraints/netbox-ipam.ts

@@ -0,0 +1,32 @@
+/**
+ * Generated NetBox REST API (OpenAPI 3.0.3) request-body constraints for `/api/ipam` — DO NOT EDIT BY HAND.
+ *
+ * Run: bun codegen/netbox.ts
+ * Manifest entry: `netbox-openapi` — NetBox REST API (OpenAPI 3.0.3) 4.7.0
+ *   sha256 be7f971179b1d6ba, vendor repository, pinned to the release tag
+ *   contrib/openapi.json in netbox-community/netbox, at tag v4.7.0
+ *
+ * 2 of this product's 949 POST/PUT/PATCH/DELETE endpoints are tabled across all
+ * areas: the ones this package writes to, named in its own source. Every other vendor write
+ * endpoint is UNTABLED and therefore unchecked at plan time.
+ *
+ * ⚠️ A `patternSource` with no `pattern` beside it could NOT be carried into a JavaScript
+ *   RegExp faithfully — Python's `\w` is Unicode and JavaScript's is ASCII
+ *   (codegen/py-pattern.ts). It is recorded and NOT enforced.
+ * ⚠️ A FOREIGN KEY CARRIES ONLY ITS TYPE. `tenant`, `vlan`, `role` and friends are
+ *   `integer|object` in the schema, and the related object's own rules do not govern them.
+ */
+import type { EndpointConstraints } from '../../constraints.ts';
+
+export const NETBOX_IPAM_CONSTRAINTS: Readonly<Record<string, EndpointConstraints>> = {
+  "netbox:PATCH /api/ipam/prefixes/{id}/": {
+    "description": {"maxLength":200,"type":"string"},
+    "prefix": {"minLength":1,"type":"string"},
+    "status": {"enum":["container","active","reserved","deprecated"],"type":"string"},
+  },
+  "netbox:POST /api/ipam/prefixes/": {
+    "description": {"maxLength":200,"type":"string"},
+    "prefix": {"minLength":1,"required":true,"type":"string"},
+    "status": {"enum":["container","active","reserved","deprecated"],"type":"string"},
+  },
+};

package/src/netbox/index.ts

@@ -0,0 +1,34 @@
+/**
+ * NetBox providers for Alchemy.
+ *
+ * ⛔ THIS BARREL IS THE PUBLIC API, AND IT IS DELIBERATELY SMALLER THAN THE DIRECTORY. These are
+ *   the symbols a real stack consumes; the rest of the files are internals a provider needs but a
+ *   consumer should not depend on. An `export *` here would publish every helper as API and make
+ *   the next refactor a breaking change.
+ * ★ The constraint reader IS exported, because a consumer writing its own family needs the same
+ *   guard — and because a table nobody can reach is a table nobody uses.
+ */
+export { NetboxError, apiBase } from './client.ts';
+export {
+  NETBOX_CONSTRAINTS,
+  bodyViolations,
+  constraintsFor,
+  guardBody,
+} from './constraint-guard.ts';
+export {
+  type EndpointConstraints,
+  type EndpointKey,
+  type NetboxBody,
+  type ParamConstraint,
+  refusal,
+  violations,
+} from './constraints.ts';
+export { NETBOX_CONSTRAINTS_DIGEST } from './generated/constraints/index.ts';
+export {
+  NetboxPrefix,
+  NetboxPrefixProvider,
+  type PrefixAttributes,
+  type PrefixProps,
+  type PrefixStatus,
+} from './prefix.ts';
+export { type NetboxRequirements, type NetboxSpec, netboxHandlers } from './resource.ts';