@loomcli/validators 0.0.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Butler
+
+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/dist/bounds.d.ts

@@ -0,0 +1,27 @@
+/** Inclusive bounds on a numeric factory, either or both absent. */
+interface Bounds {
+    min: number | undefined;
+    max: number | undefined;
+}
+/** What a numeric factory requires of each bound, stated for its fault messages. */
+interface BoundRule {
+    factory: string;
+    accepts: (value: number) => boolean;
+    requirement: string;
+    correction: string;
+}
+/** Reads a numeric factory's `min` and `max`, and faults on a bad bound or `min` above `max`. */
+declare function readBounds(options: unknown, rule: BoundRule): Bounds;
+declare function withinBounds(value: number, { max, min }: Bounds): boolean;
+/** The number a numeric token outputs, with `-0` read as `0`. */
+declare function withoutNegativeZero(value: number): number;
+/** The one sentence for a numeric configuration, each bound printed as JavaScript prints it. */
+declare function boundsSentence(noun: string, { max, min }: Bounds): string;
+/** The published schema for a numeric type, with each declared bound. */
+declare function boundsSchema(type: 'integer' | 'number', { max, min }: Bounds): {
+    type: "integer" | "number";
+    minimum?: number;
+    maximum?: number;
+};
+export { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero };
+export type { Bounds };

package/dist/bounds.js

@@ -0,0 +1,50 @@
+import { fault, readOptions } from './faults.js';
+const zero = 0;
+function boundOf(rule, name, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !rule.accepts(value)) {
+        throw fault(`${rule.factory}() ${name} is not ${rule.requirement}. ${rule.correction}`);
+    }
+    return value;
+}
+/** Reads a numeric factory's `min` and `max`, and faults on a bad bound or `min` above `max`. */
+function readBounds(options, rule) {
+    const declared = readOptions(rule.factory, options);
+    const min = boundOf(rule, 'min', declared.min);
+    const max = boundOf(rule, 'max', declared.max);
+    if (min !== undefined && max !== undefined && min > max) {
+        throw fault(`${rule.factory}() min ${String(min)} is above max ${String(max)}. Supply a min at or below max.`);
+    }
+    return { max, min };
+}
+function withinBounds(value, { max, min }) {
+    return (min === undefined || value >= min) && (max === undefined || value <= max);
+}
+/** The number a numeric token outputs, with `-0` read as `0`. */
+function withoutNegativeZero(value) {
+    return value === zero ? zero : value;
+}
+/** The one sentence for a numeric configuration, each bound printed as JavaScript prints it. */
+function boundsSentence(noun, { max, min }) {
+    if (min !== undefined && max !== undefined) {
+        return `Expected ${noun} from ${String(min)} through ${String(max)}.`;
+    }
+    if (min !== undefined) {
+        return `Expected ${noun} of at least ${String(min)}.`;
+    }
+    if (max !== undefined) {
+        return `Expected ${noun} of at most ${String(max)}.`;
+    }
+    return `Expected ${noun}.`;
+}
+/** The published schema for a numeric type, with each declared bound. */
+function boundsSchema(type, { max, min }) {
+    return {
+        type,
+        ...(min === undefined ? {} : { minimum: min }),
+        ...(max === undefined ? {} : { maximum: max }),
+    };
+}
+export { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero };

package/dist/create.d.ts

@@ -0,0 +1,20 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1, ValidationContext } from '@loomcli/core';
+/** What `parse` returns: `{ value }` for an accepted token or `{ issues }` for a rejected one. */
+type ParseResult<Output> = StandardSchemaV1.Result<Output>;
+/** A validator that publishes its input schema, as every catalog factory returns. */
+type Validator<Output> = StandardSchemaV1<string, Output> & StandardJSONSchemaV1<string, Output>;
+/** The author's definition of one validator. */
+interface ValidatorDefinition<Output> {
+    parse: (raw: string, context: ValidationContext) => ParseResult<Output> | Promise<ParseResult<Output>>;
+    inputSchema?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Builds a frozen Standard Schema value from the author's parse function.
+ * With an input schema it also publishes that schema through Standard JSON Schema.
+ */
+declare function createValidator<Output>(definition: ValidatorDefinition<Output> & {
+    inputSchema: Readonly<Record<string, unknown>>;
+}): Validator<Output>;
+declare function createValidator<Output>(definition: ValidatorDefinition<Output>): StandardSchemaV1<string, Output>;
+export { createValidator };
+export type { ParseResult, Validator, ValidatorDefinition };

package/dist/create.js

@@ -0,0 +1,92 @@
+import { DeclarationError, validationContext } from '@loomcli/core';
+import { copyRecord, isPlainObject } from './data.js';
+import { fault } from './faults.js';
+const vendor = '@loomcli/validators';
+const target = 'draft-2020-12';
+const dialect = 'https://json-schema.org/draft/2020-12/schema';
+function unavailable() {
+    throw new DeclarationError('This validator reads the validation context, which only exists during a Loom run.');
+}
+/**
+ * The context `parse` receives when core did not make the call.
+ * Every field throws at the read, so only a validator that reads the context fails.
+ */
+const outsideRun = Object.freeze({
+    get command() {
+        return unavailable();
+    },
+    get host() {
+        return unavailable();
+    },
+    get input() {
+        return unavailable();
+    },
+    get passthrough() {
+        return unavailable();
+    },
+    get phase() {
+        return unavailable();
+    },
+    get supplied() {
+        return unavailable();
+    },
+});
+/** The converter that publishes a frozen input schema for draft 2020-12 and nothing else. */
+function converter(schema) {
+    return Object.freeze({
+        input: (options) => {
+            if (options.target !== target) {
+                throw new Error(`This validator publishes JSON Schema for ${target} only, not ${options.target}.`);
+            }
+            return { $schema: dialect, ...copyRecord(schema, false) };
+        },
+        output: () => {
+            throw new Error('This validator publishes no output schema.');
+        },
+    });
+}
+/**
+ * Checks a definition that bypassed the types, and returns its input schema copied and frozen, or
+ * undefined when it declares none.
+ */
+function checkDefinition(definition) {
+    if (!isPlainObject(definition)) {
+        throw fault('createValidator() definition is not a plain object. Supply an object with a parse function.');
+    }
+    if (typeof definition.parse !== 'function') {
+        throw fault('createValidator() parse is not a function. Supply a function that validates one raw string.');
+    }
+    return declaredSchema(definition.inputSchema);
+}
+/** The declared input schema, checked, copied, and frozen, or undefined when none is declared. */
+function declaredSchema(inputSchema) {
+    if (inputSchema === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(inputSchema)) {
+        throw fault('createValidator() inputSchema is not a plain object. Supply the JSON Schema as a plain object.');
+    }
+    if (Object.hasOwn(inputSchema, '$schema')) {
+        throw fault('createValidator() inputSchema declares its own $schema. Leave out $schema, which the validator publishes itself.');
+    }
+    return copyRecord(inputSchema, true);
+}
+function createValidator(definition) {
+    const schema = checkDefinition(definition);
+    const { parse } = definition;
+    const props = {
+        validate: (value, options) => {
+            if (typeof value !== 'string') {
+                throw new TypeError(`A validator reads one raw string, and received a value of type ${typeof value}.`);
+            }
+            return parse(value, validationContext(options) ?? outsideRun);
+        },
+        vendor,
+        version: 1,
+    };
+    if (schema === undefined) {
+        return Object.freeze({ '~standard': Object.freeze(props) });
+    }
+    return Object.freeze({ '~standard': Object.freeze({ ...props, jsonSchema: converter(schema) }) });
+}
+export { createValidator };

package/dist/data.d.ts

@@ -0,0 +1,8 @@
+/** Whether a value is a plain object: an object literal or one made with a null prototype. */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * A deep copy of plain JSON-like data, so neither the author nor a reader can change the original.
+ * Arrays and plain objects are copied, frozen when asked, and every other value is kept as it is.
+ */
+declare function copyRecord(record: Readonly<Record<string, unknown>>, freeze: boolean): Record<string, unknown>;
+export { copyRecord, isPlainObject };

package/dist/data.js

@@ -0,0 +1,25 @@
+/** Whether a value is a plain object: an object literal or one made with a null prototype. */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function copyValue(value, freeze) {
+    if (Array.isArray(value)) {
+        const items = value;
+        const copy = items.map((item) => copyValue(item, freeze));
+        return freeze ? Object.freeze(copy) : copy;
+    }
+    return isPlainObject(value) ? copyRecord(value, freeze) : value;
+}
+/**
+ * A deep copy of plain JSON-like data, so neither the author nor a reader can change the original.
+ * Arrays and plain objects are copied, frozen when asked, and every other value is kept as it is.
+ */
+function copyRecord(record, freeze) {
+    const copy = Object.fromEntries(Object.entries(record).map(([key, value]) => [key, copyValue(value, freeze)]));
+    return freeze ? Object.freeze(copy) : copy;
+}
+export { copyRecord, isPlainObject };

package/dist/date.d.ts

@@ -0,0 +1,4 @@
+import type { Validator } from './create.js';
+/** A calendar date as `YYYY-MM-DD`, kept as the token because a date has no time or zone. */
+declare function date(): Validator<string>;
+export { date };

package/dist/date.js

@@ -0,0 +1,30 @@
+import { createValidator } from './create.js';
+import { reject } from './issues.js';
+const layout = /^(?<year>[0-9]{4})-(?<month>[0-9]{2})-(?<day>[0-9]{2})$/u;
+/**
+ * Five 400-year Gregorian cycles.
+ * The calendar repeats every cycle, so a shifted year keeps its leap days, and the shift moves
+ * years below 100 out of the range `Date.UTC` maps to the 1900s.
+ */
+const cycleShift = 2000;
+/** The number of the first month, which `Date.UTC` counts from zero. */
+const january = 1;
+/** Whether the parts name a real day of the proleptic Gregorian calendar. */
+function isRealDay(year, month, day) {
+    const monthIndex = month - january;
+    const probe = new Date(Date.UTC(year + cycleShift, monthIndex, day));
+    return probe.getUTCMonth() === monthIndex && probe.getUTCDate() === day;
+}
+/** A calendar date as `YYYY-MM-DD`, kept as the token because a date has no time or zone. */
+function date() {
+    return createValidator({
+        inputSchema: { type: 'string', format: 'date' },
+        parse: (raw) => {
+            const parts = layout.exec(raw)?.groups;
+            const real = parts !== undefined &&
+                isRealDay(Number(parts.year), Number(parts.month), Number(parts.day));
+            return real ? { value: raw } : reject('Expected a date as YYYY-MM-DD, such as 2026-09-25.');
+        },
+    });
+}
+export { date };

package/dist/faults.d.ts

@@ -0,0 +1,14 @@
+import { DeclarationError } from '@loomcli/core';
+/**
+ * A factory argument that can never work.
+ * The message names the factory and the argument, states the problem, then the correction.
+ */
+declare function fault(message: string): DeclarationError;
+/** A declared value as a fault message quotes it: a string in quotes, a primitive as printed. */
+declare function quote(value: unknown): string;
+/**
+ * A factory's options read as unknown values, because a JavaScript caller can pass anything.
+ * Omitted options read as an empty record.
+ */
+declare function readOptions(factory: string, options: unknown): Readonly<Record<string, unknown>>;
+export { fault, quote, readOptions };

package/dist/faults.js

@@ -0,0 +1,37 @@
+import { DeclarationError } from '@loomcli/core';
+import { isPlainObject } from './data.js';
+/**
+ * A factory argument that can never work.
+ * The message names the factory and the argument, states the problem, then the correction.
+ */
+function fault(message) {
+    return new DeclarationError(message);
+}
+/** A declared value as a fault message quotes it: a string in quotes, a primitive as printed. */
+function quote(value) {
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint' ||
+        value === null ||
+        value === undefined) {
+        return String(value);
+    }
+    return `a value of type ${typeof value}`;
+}
+/**
+ * A factory's options read as unknown values, because a JavaScript caller can pass anything.
+ * Omitted options read as an empty record.
+ */
+function readOptions(factory, options) {
+    if (options === undefined) {
+        return {};
+    }
+    if (!isPlainObject(options)) {
+        throw fault(`${factory}() options is not a plain object. Supply an object or leave it out.`);
+    }
+    return options;
+}
+export { fault, quote, readOptions };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { createValidator } from './create.js';
+export { date } from './date.js';
+export { integer } from './integer.js';
+export { number } from './number.js';
+export { oneOf } from './one-of.js';
+export { path } from './path.js';
+export { port } from './port.js';
+export { text } from './text.js';
+export { url } from './url.js';
+export { uuid } from './uuid.js';
+export type { ParseResult, Validator } from './create.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createValidator } from './create.js';
+export { date } from './date.js';
+export { integer } from './integer.js';
+export { number } from './number.js';
+export { oneOf } from './one-of.js';
+export { path } from './path.js';
+export { port } from './port.js';
+export { text } from './text.js';
+export { url } from './url.js';
+export { uuid } from './uuid.js';

package/dist/integer.d.ts

@@ -0,0 +1,11 @@
+import type { Validator } from './create.js';
+interface IntegerOptions {
+    min?: number;
+    max?: number;
+}
+/** The safe integer a token spells in decimal digits, `-0` as `0`, or undefined when none. */
+declare function readInteger(raw: string): number | undefined;
+/** A decimal whole number that is a safe integer within `min` and `max`, both inclusive. */
+declare function integer(options?: IntegerOptions): Validator<number>;
+export { integer, readInteger };
+export type { IntegerOptions };

package/dist/integer.js

@@ -0,0 +1,30 @@
+import { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero, } from './bounds.js';
+import { createValidator } from './create.js';
+import { reject } from './issues.js';
+const digits = /^-?[0-9]+$/u;
+/** The safe integer a token spells in decimal digits, `-0` as `0`, or undefined when none. */
+function readInteger(raw) {
+    if (!digits.test(raw)) {
+        return undefined;
+    }
+    const value = Number(raw);
+    return Number.isSafeInteger(value) ? withoutNegativeZero(value) : undefined;
+}
+/** A decimal whole number that is a safe integer within `min` and `max`, both inclusive. */
+function integer(options) {
+    const bounds = readBounds(options, {
+        accepts: Number.isSafeInteger,
+        correction: 'Supply a whole number from -9007199254740991 through 9007199254740991.',
+        factory: 'integer',
+        requirement: 'a safe integer',
+    });
+    const sentence = boundsSentence('a whole number', bounds);
+    return createValidator({
+        inputSchema: boundsSchema('integer', bounds),
+        parse: (raw) => {
+            const value = readInteger(raw);
+            return value !== undefined && withinBounds(value, bounds) ? { value } : reject(sentence);
+        },
+    });
+}
+export { integer, readInteger };

package/dist/issues.d.ts

@@ -0,0 +1,6 @@
+import type { StandardSchemaV1 } from '@loomcli/core';
+/** A rejection: one issue with no path and no code, carrying the configuration's one sentence. */
+declare function reject(message: string): StandardSchemaV1.FailureResult;
+/** Joins items as a sentence lists them: `a`, `a or b`, or `a, b, or c`. */
+declare function listing(items: readonly string[]): string;
+export { listing, reject };

package/dist/issues.js

@@ -0,0 +1,17 @@
+/** The longest list that joins with `or` alone. */
+const pair = 2;
+const first = 0;
+/** The index of the last item, counted from the end. */
+const last = -1;
+/** A rejection: one issue with no path and no code, carrying the configuration's one sentence. */
+function reject(message) {
+    return { issues: [{ message }] };
+}
+/** Joins items as a sentence lists them: `a`, `a or b`, or `a, b, or c`. */
+function listing(items) {
+    if (items.length <= pair) {
+        return items.join(' or ');
+    }
+    return `${items.slice(first, last).join(', ')}, or ${items.at(last) ?? ''}`;
+}
+export { listing, reject };

package/dist/number.d.ts

@@ -0,0 +1,9 @@
+import type { Validator } from './create.js';
+interface NumberOptions {
+    min?: number;
+    max?: number;
+}
+/** A finite decimal number, with an optional fraction and exponent, within `min` and `max`. */
+declare function number(options?: NumberOptions): Validator<number>;
+export { number };
+export type { NumberOptions };

package/dist/number.js

@@ -0,0 +1,25 @@
+import { boundsSchema, boundsSentence, readBounds, withinBounds, withoutNegativeZero, } from './bounds.js';
+import { createValidator } from './create.js';
+import { reject } from './issues.js';
+const decimal = /^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/u;
+/** A finite decimal number, with an optional fraction and exponent, within `min` and `max`. */
+function number(options) {
+    const bounds = readBounds(options, {
+        accepts: Number.isFinite,
+        correction: 'Supply a finite number.',
+        factory: 'number',
+        requirement: 'a finite number',
+    });
+    const sentence = boundsSentence('a number', bounds);
+    return createValidator({
+        inputSchema: boundsSchema('number', bounds),
+        parse: (raw) => {
+            if (!decimal.test(raw)) {
+                return reject(sentence);
+            }
+            const value = withoutNegativeZero(Number(raw));
+            return Number.isFinite(value) && withinBounds(value, bounds) ? { value } : reject(sentence);
+        },
+    });
+}
+export { number };

package/dist/one-of.d.ts

@@ -0,0 +1,4 @@
+import type { Validator } from './create.js';
+/** A token exactly equal to one of the declared values, typed as their union. */
+declare function oneOf<const Values extends readonly [string, ...string[]]>(values: Values): Validator<Values[number]>;
+export { oneOf };

package/dist/one-of.js

@@ -0,0 +1,47 @@
+import { createValidator } from './create.js';
+import { fault } from './faults.js';
+import { reject } from './issues.js';
+const empty = 0;
+/** The declared list as unknown items, after faulting on one that is not an array or is empty. */
+function checkList(values) {
+    if (!Array.isArray(values)) {
+        throw fault('oneOf() values is not an array. Supply an array of strings.');
+    }
+    const items = values;
+    if (items.length === empty) {
+        throw fault('oneOf() values is empty. List at least one value.');
+    }
+    return items;
+}
+/** Faults on a value that is not a string, is empty, or was listed earlier. */
+function checkValue(item, seen) {
+    if (typeof item !== 'string') {
+        throw fault('oneOf() lists a value that is not a string. List strings only.');
+    }
+    if (item === '') {
+        throw fault('oneOf() lists an empty string. List nonempty values only.');
+    }
+    if (seen.has(item)) {
+        throw fault(`oneOf() lists ${JSON.stringify(item)} twice. List each value once.`);
+    }
+    seen.add(item);
+}
+/** A token exactly equal to one of the declared values, typed as their union. */
+function oneOf(values) {
+    checkList(values);
+    // The copy is what the validator keeps, so the checks read the copy and not the caller's list.
+    const listed = [...values];
+    const seen = new Set();
+    for (const item of listed) {
+        checkValue(item, seen);
+    }
+    const sentence = `Expected one of: ${listed.join(', ')}.`;
+    return createValidator({
+        inputSchema: { type: 'string', enum: [...listed] },
+        parse: (raw) => {
+            const match = listed.find((value) => value === raw);
+            return match === undefined ? reject(sentence) : { value: match };
+        },
+    });
+}
+export { oneOf };

package/dist/path.d.ts

@@ -0,0 +1,13 @@
+import type { Validator } from './create.js';
+import type { PathKind } from './probe.js';
+interface PathOptions {
+    access?: 'read' | 'write';
+    kind?: PathKind;
+}
+/**
+ * A path resolved against the host's cwd under the host platform's rules, and normalized.
+ * With `access`, the filesystem is probed; the probe is advisory, since the filesystem can change.
+ */
+declare function path(options?: PathOptions): Validator<string>;
+export { path };
+export type { PathOptions };

package/dist/path.js

@@ -0,0 +1,61 @@
+import { posix, win32 } from 'node:path';
+import { createValidator } from './create.js';
+import { fault, readOptions } from './faults.js';
+import { reject } from './issues.js';
+import { readable, writable } from './probe.js';
+const sentences = {
+    read: {
+        any: 'Expected a readable file or directory that exists.',
+        directory: 'Expected a readable directory that exists.',
+        file: 'Expected a readable file that exists.',
+    },
+    write: {
+        any: 'Expected a writable path, or a new path in a writable directory.',
+        directory: 'Expected a writable directory, or a new directory in a writable directory.',
+        file: 'Expected a writable file, or a new file in a writable directory.',
+    },
+};
+function accessOf(value) {
+    if (value === undefined || value === 'read' || value === 'write') {
+        return value;
+    }
+    throw fault('path() access is not "read" or "write". Supply "read" or "write".');
+}
+function kindOf(value, access) {
+    if (value !== undefined && access === undefined) {
+        throw fault('path() kind has no access to check. Supply an access or leave out kind.');
+    }
+    if (value === undefined || value === 'file' || value === 'directory' || value === 'any') {
+        return value ?? 'file';
+    }
+    throw fault('path() kind is not "file", "directory", or "any". Supply one of them.');
+}
+/**
+ * A path resolved against the host's cwd under the host platform's rules, and normalized.
+ * With `access`, the filesystem is probed; the probe is advisory, since the filesystem can change.
+ */
+function path(options) {
+    const declared = readOptions('path', options);
+    const access = accessOf(declared.access);
+    const kind = kindOf(declared.kind, access);
+    const sentence = access === undefined ? 'Expected a path.' : sentences[access][kind];
+    return createValidator({
+        inputSchema: { type: 'string', minLength: 1 },
+        parse: (raw, context) => {
+            if (raw === '' || raw.includes('\0')) {
+                return reject(sentence);
+            }
+            const { cwd, platform } = context.host;
+            const rules = platform === 'win32' ? win32 : posix;
+            const resolved = rules.resolve(cwd, raw);
+            if (access === undefined) {
+                return { value: resolved };
+            }
+            const probe = access === 'read'
+                ? readable(resolved, kind)
+                : writable(resolved, kind, rules.dirname(resolved));
+            return probe.then((passes) => (passes ? { value: resolved } : reject(sentence)));
+        },
+    });
+}
+export { path };

package/dist/port.d.ts

@@ -0,0 +1,4 @@
+import type { Validator } from './create.js';
+/** A TCP or UDP port the operator names, 1 through 65535; port 0 is left to `integer()`. */
+declare function port(): Validator<number>;
+export { port };

package/dist/port.js

@@ -0,0 +1,18 @@
+import { boundsSchema, withinBounds } from './bounds.js';
+import { createValidator } from './create.js';
+import { readInteger } from './integer.js';
+import { reject } from './issues.js';
+const range = { max: 65_535, min: 1 };
+/** A TCP or UDP port the operator names, 1 through 65535; port 0 is left to `integer()`. */
+function port() {
+    return createValidator({
+        inputSchema: boundsSchema('integer', range),
+        parse: (raw) => {
+            const value = readInteger(raw);
+            return value !== undefined && withinBounds(value, range)
+                ? { value }
+                : reject('Expected a port number from 1 through 65535.');
+        },
+    });
+}
+export { port };

package/dist/probe.d.ts

@@ -0,0 +1,11 @@
+type PathKind = 'file' | 'directory' | 'any';
+/** Runs one probe, reading a verdict failure as `false` and rethrowing any other failure. */
+declare function holds(probe: () => Promise<boolean>): Promise<boolean>;
+declare function readable(target: string, kind: PathKind): Promise<boolean>;
+/**
+ * Whether the process can write the entry, or create it when no entry exists: then the parent
+ * must be an existing directory the process can write. Nothing is created.
+ */
+declare function writable(target: string, kind: PathKind, parent: string): Promise<boolean>;
+export { holds, readable, writable };
+export type { PathKind };

package/dist/probe.js

@@ -0,0 +1,66 @@
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+/** The probe failures that are a verdict about the operator's path rather than a broken host. */
+const verdicts = new Set([
+    'ENOENT',
+    'ENOTDIR',
+    'EACCES',
+    'EPERM',
+    'ELOOP',
+    'ENAMETOOLONG',
+    'EINVAL',
+]);
+function codeOf(error) {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+/** Runs one probe, reading a verdict failure as `false` and rethrowing any other failure. */
+async function holds(probe) {
+    try {
+        return await probe();
+    }
+    catch (error) {
+        const code = codeOf(error);
+        if (code !== undefined && verdicts.has(code)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isKind(stats, kind) {
+    if (kind === 'file') {
+        return stats.isFile();
+    }
+    return kind === 'directory' ? stats.isDirectory() : true;
+}
+/** Whether an entry exists, following symbolic links, is of `kind`, and grants `mode`. */
+async function grants(target, kind, mode) {
+    const stats = await stat(target);
+    if (!isKind(stats, kind)) {
+        return false;
+    }
+    await access(target, mode);
+    return true;
+}
+async function readable(target, kind) {
+    return await holds(async () => await grants(target, kind, constants.R_OK));
+}
+/**
+ * Whether the process can write the entry, or create it when no entry exists: then the parent
+ * must be an existing directory the process can write. Nothing is created.
+ */
+async function writable(target, kind, parent) {
+    return await holds(async () => {
+        try {
+            return await grants(target, kind, constants.W_OK);
+        }
+        catch (error) {
+            if (codeOf(error) !== 'ENOENT') {
+                throw error;
+            }
+            return await grants(parent, 'directory', constants.W_OK);
+        }
+    });
+}
+export { holds, readable, writable };

package/dist/text.d.ts

@@ -0,0 +1,11 @@
+import type { Validator } from './create.js';
+interface TextOptions {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    message?: string;
+}
+/** A string whose code-point length is within bounds and which the pattern matches, if any. */
+declare function text(options?: TextOptions): Validator<string>;
+export { text };
+export type { TextOptions };

package/dist/text.js

@@ -0,0 +1,113 @@
+import { createValidator } from './create.js';
+import { fault, readOptions } from './faults.js';
+import { reject } from './issues.js';
+const noLength = 0;
+const oneCharacter = 1;
+const defaultMinLength = 1;
+function lengthOf(name, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < noLength) {
+        throw fault(`text() ${name} is not a non-negative safe integer. Supply a whole number of 0 or more.`);
+    }
+    return value;
+}
+/** Faults on a pattern flag other than `u`, which JSON Schema has no way to state. */
+function checkFlags(pattern) {
+    const others = pattern.flags.replace('u', '');
+    if (others !== '') {
+        const noun = others.length === oneCharacter ? 'flag' : 'flags';
+        throw fault(`text() pattern carries the ${noun} ${others}. Supply a pattern with no flag other than u.`);
+    }
+}
+/** The author's pattern recompiled under the `u` flag, as JSON Schema reads a `pattern`. */
+function patternOf(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!(value instanceof RegExp)) {
+        throw fault('text() pattern is not a RegExp. Supply a regular expression literal.');
+    }
+    checkFlags(value);
+    try {
+        return new RegExp(value.source, 'u');
+    }
+    catch {
+        throw fault('text() pattern does not compile under the u flag. Supply a pattern that is valid with the u flag.');
+    }
+}
+function messageOf(value, pattern) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value === '') {
+        throw fault('text() message is not a nonempty string. Supply one sentence that states the expectation.');
+    }
+    if (pattern === undefined) {
+        throw fault('text() message has no pattern to describe. Supply a pattern or leave out message.');
+    }
+    return value;
+}
+function characters(count) {
+    return count === oneCharacter ? '1 character' : `${count} characters`;
+}
+/** The sentence for bounds with a `maxLength`, where `min` is `minLength` after its default. */
+function boundedSentence(min, max) {
+    if (min === max) {
+        return `Expected exactly ${characters(min)}.`;
+    }
+    if (min === noLength) {
+        return `Expected at most ${characters(max)}.`;
+    }
+    return `Expected from ${min} through ${max} characters.`;
+}
+/** The length rule for the effective bounds, or undefined when every length passes. */
+function lengthRule(min, max) {
+    if (max !== undefined) {
+        return { fits: (count) => count >= min && count <= max, sentence: boundedSentence(min, max) };
+    }
+    if (min === noLength) {
+        return undefined;
+    }
+    const sentence = min === oneCharacter ? 'Expected a nonempty value.' : `Expected at least ${characters(min)}.`;
+    return { fits: (count) => count >= min, sentence };
+}
+/**
+ * The token's length in Unicode code points, as JSON Schema counts it.
+ * Under the `u` flag a dot matches one code point, a lone surrogate included, so replacing each
+ * match with one code unit leaves a string as long as the count.
+ */
+function codePoints(raw) {
+    return raw.replaceAll(/./gsu, '.').length;
+}
+/** A string whose code-point length is within bounds and which the pattern matches, if any. */
+function text(options) {
+    const declared = readOptions('text', options);
+    const minLength = lengthOf('minLength', declared.minLength) ?? defaultMinLength;
+    const maxLength = lengthOf('maxLength', declared.maxLength);
+    if (maxLength !== undefined && minLength > maxLength) {
+        throw fault(`text() minLength ${minLength} is above maxLength ${maxLength}. Supply a minLength at or below maxLength.`);
+    }
+    const pattern = patternOf(declared.pattern);
+    const patternSentence = messageOf(declared.message, pattern) ?? 'Expected a value that matches the required pattern.';
+    const length = lengthRule(minLength, maxLength);
+    return createValidator({
+        inputSchema: {
+            type: 'string',
+            minLength,
+            ...(maxLength === undefined ? {} : { maxLength }),
+            ...(pattern === undefined ? {} : { pattern: pattern.source }),
+        },
+        parse: (raw) => {
+            if (length !== undefined && !length.fits(codePoints(raw))) {
+                return reject(length.sentence);
+            }
+            if (pattern !== undefined && !pattern.test(raw)) {
+                return reject(patternSentence);
+            }
+            return { value: raw };
+        },
+    });
+}
+export { text };

package/dist/uri-grammar.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The RFC 3986 `URI` production, built from the RFC's own rule names:
+ * `scheme ":" hier-part [ "?" query ] [ "#" fragment ]`.
+ * Letters are spelled in both cases, so the expression needs no `i` flag.
+ */
+declare const uriPattern: RegExp;
+/** The RFC 3986 `scheme` production on its own, for checking a declared protocol. */
+declare const schemePattern: RegExp;
+export { schemePattern, uriPattern };

package/dist/uri-grammar.js

@@ -0,0 +1,42 @@
+/**
+ * The RFC 3986 `URI` production, built from the RFC's own rule names:
+ * `scheme ":" hier-part [ "?" query ] [ "#" fragment ]`.
+ * Letters are spelled in both cases, so the expression needs no `i` flag.
+ */
+const hex = '[0-9A-Fa-f]';
+const pctEncoded = `%${hex}{2}`;
+const unreserved = String.raw `A-Za-z0-9\-._~`;
+const subDelims = "!$&'()*+,;=";
+const pchar = `(?:[${unreserved}${subDelims}:@]|${pctEncoded})`;
+const scheme = String.raw `[A-Za-z][A-Za-z0-9+\-.]*`;
+const userinfo = `(?:[${unreserved}${subDelims}:]|${pctEncoded})*`;
+const decOctet = '(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])';
+const ipv4 = String.raw `${decOctet}(?:\.${decOctet}){3}`;
+const h16 = `${hex}{1,4}`;
+const ls32 = `(?:${h16}:${h16}|${ipv4})`;
+const ipv6 = `(?:${[
+    `(?:${h16}:){6}${ls32}`,
+    `::(?:${h16}:){5}${ls32}`,
+    `(?:${h16})?::(?:${h16}:){4}${ls32}`,
+    `(?:(?:${h16}:){0,1}${h16})?::(?:${h16}:){3}${ls32}`,
+    `(?:(?:${h16}:){0,2}${h16})?::(?:${h16}:){2}${ls32}`,
+    `(?:(?:${h16}:){0,3}${h16})?::${h16}:${ls32}`,
+    `(?:(?:${h16}:){0,4}${h16})?::${ls32}`,
+    `(?:(?:${h16}:){0,5}${h16})?::${h16}`,
+    `(?:(?:${h16}:){0,6}${h16})?::`,
+].join('|')})`;
+const ipvFuture = String.raw `[vV]${hex}+\.[${unreserved}${subDelims}:]+`;
+const ipLiteral = String.raw `\[(?:${ipv6}|${ipvFuture})\]`;
+const regName = `(?:[${unreserved}${subDelims}]|${pctEncoded})*`;
+const host = `(?:${ipLiteral}|${ipv4}|${regName})`;
+const authority = `(?:${userinfo}@)?${host}(?::[0-9]*)?`;
+const pathAbempty = `(?:/${pchar}*)*`;
+const pathAbsolute = `/(?:${pchar}+(?:/${pchar}*)*)?`;
+const pathRootless = `${pchar}+(?:/${pchar}*)*`;
+// RFC 3986 also allows an empty path, which the published `uri` format refuses, so soundness drops it.
+const hierPart = `(?://${authority}${pathAbempty}|${pathAbsolute}|${pathRootless})`;
+const queryOrFragment = `(?:${pchar}|[/?])*`;
+const uriPattern = new RegExp(String.raw `^${scheme}:${hierPart}(?:\?${queryOrFragment})?(?:#${queryOrFragment})?$`, 'u');
+/** The RFC 3986 `scheme` production on its own, for checking a declared protocol. */
+const schemePattern = new RegExp(`^${scheme}$`, 'u');
+export { schemePattern, uriPattern };

package/dist/url.d.ts

@@ -0,0 +1,8 @@
+import type { Validator } from './create.js';
+interface UrlOptions {
+    protocols?: readonly [string, ...string[]];
+}
+/** An absolute RFC 3986 URI that the WHATWG parser also reads, optionally with a listed scheme. */
+declare function url(options?: UrlOptions): Validator<URL>;
+export { url };
+export type { UrlOptions };

package/dist/url.js

@@ -0,0 +1,63 @@
+import { createValidator } from './create.js';
+import { fault, quote, readOptions } from './faults.js';
+import { listing, reject } from './issues.js';
+import { schemePattern, uriPattern } from './uri-grammar.js';
+const empty = 0;
+function protocolsOf(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw fault('url() protocols is not an array. Supply an array of scheme names.');
+    }
+    const items = value;
+    if (items.length === empty) {
+        throw fault('url() protocols is empty. List at least one scheme.');
+    }
+    // `Array.from` reads a hole as `undefined`, so a sparse list faults instead of skipping it.
+    return Array.from(items, (item) => {
+        if (typeof item !== 'string' || !schemePattern.test(item)) {
+            throw fault(`url() protocols lists ${quote(item)}, which is not a scheme name. List a letter followed by letters, digits, +, -, or ., with no trailing colon.`);
+        }
+        return item;
+    });
+}
+/**
+ * One scheme as a case-free pattern: each letter as a two-case class, `+` and `.` escaped.
+ * A hyphen stays bare, because the `u` flag JSON Schema patterns use refuses `\-` outside a class.
+ */
+function spellScheme(scheme) {
+    return scheme
+        .replaceAll(/[+.]/gu, String.raw `\$&`)
+        .replaceAll(/[A-Za-z]/gu, (letter) => `[${letter.toLowerCase()}${letter.toUpperCase()}]`);
+}
+/** The pattern that publishes a scheme list, anchored at the start and ending at the colon. */
+function schemesPattern(protocols) {
+    return `^(?:${protocols.map((protocol) => spellScheme(protocol)).join('|')}):`;
+}
+/** An absolute RFC 3986 URI that the WHATWG parser also reads, optionally with a listed scheme. */
+function url(options) {
+    const protocols = protocolsOf(readOptions('url', options).protocols);
+    // The WHATWG parser lowercases the scheme and ends `protocol` with a colon.
+    const listed = new Set(protocols?.map((protocol) => `${protocol.toLowerCase()}:`));
+    const sentence = protocols === undefined
+        ? 'Expected an absolute URL, such as https://example.com.'
+        : `Expected an absolute URL with the scheme ${listing(protocols)}.`;
+    return createValidator({
+        inputSchema: {
+            type: 'string',
+            format: 'uri',
+            ...(protocols === undefined ? {} : { pattern: schemesPattern(protocols) }),
+        },
+        parse: (raw) => {
+            if (!uriPattern.test(raw) || !URL.canParse(raw)) {
+                return reject(sentence);
+            }
+            const parsed = new URL(raw);
+            return protocols === undefined || listed.has(parsed.protocol)
+                ? { value: parsed }
+                : reject(sentence);
+        },
+    });
+}
+export { url };

package/dist/uuid.d.ts

@@ -0,0 +1,4 @@
+import type { Validator } from './create.js';
+/** A UUID of any version in any letter case, read as lowercase so two spellings compare equal. */
+declare function uuid(): Validator<string>;
+export { uuid };

package/dist/uuid.js

@@ -0,0 +1,13 @@
+import { createValidator } from './create.js';
+import { reject } from './issues.js';
+const grouped = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/u;
+/** A UUID of any version in any letter case, read as lowercase so two spellings compare equal. */
+function uuid() {
+    return createValidator({
+        inputSchema: { type: 'string', format: 'uuid' },
+        parse: (raw) => grouped.test(raw)
+            ? { value: raw.toLowerCase() }
+            : reject('Expected a UUID, such as 123e4567-e89b-12d3-a456-426614174000.'),
+    });
+}
+export { uuid };

package/package.json

@@ -1,10 +1,32 @@
 {
   "name": "@loomcli/validators",
-  "version": "0.0.0",
-  "description": "Placeholder for the Loom CLI validator catalog. The first real release follows.",
+  "version": "0.5.0",
+  "description": "The Loom CLI validator catalog. Ships Standard Schema values for common command-line input shapes.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dbtlr/loomcli.git"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "peerDependencies": {
+    "@loomcli/core": "0.5.0"
+  },
+  "engines": {
+    "bun": ">=1.4.0",
+    "node": ">=22.23.2"
   }
 }