aligndev 0.0.0 → 0.18.0

package/dist/project/discovery.js

@@ -0,0 +1,287 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { isNodeError } from "../errors.js";
+import { formatRange } from "./format.js";
+import { readProjectReport } from "./layout.js";
+import { containsRange, rangesOverlap, readMarker, } from "./markers.js";
+const PROJECT_CONFIG_FILENAME = ".alignfirst.json";
+export function buildInventory(root, marker, ctx) {
+    const state = { directories: [], candidates: [], directoryClaims: [], issues: [] };
+    walkProjectsDirectory(root, marker, undefined, state);
+    const projects = classifyCandidates(state, ctx);
+    reportSharedCompanions(projects, state.issues);
+    reportOverlappingClaims(projects, state.directoryClaims, state.issues);
+    sortInventory(state.directories, projects, state.issues);
+    return { root, directories: state.directories, projects, issues: state.issues };
+}
+function walkProjectsDirectory(path, marker, enclosingRanges, state) {
+    const effectiveRanges = marker.portRanges ?? enclosingRanges;
+    state.directories.push({
+        path,
+        ...(marker.description === undefined ? {} : { description: marker.description }),
+        ...(marker.portRanges === undefined ? {} : { portRanges: marker.portRanges }),
+        others: [],
+    });
+    for (const candidate of readDirectoryCandidates(path)) {
+        const childMarker = readMarker(candidate.path);
+        if (childMarker === undefined) {
+            state.candidates.push({ ...candidate, enclosingRanges: effectiveRanges });
+            continue;
+        }
+        for (const portRange of childMarker.portRanges ?? []) {
+            reportOutsideRange(candidate.path, portRange, effectiveRanges, state.issues);
+            state.directoryClaims.push({
+                scope: path,
+                path: candidate.path,
+                portRange,
+            });
+        }
+        walkProjectsDirectory(candidate.path, childMarker, effectiveRanges, state);
+    }
+}
+function readDirectoryCandidates(directory) {
+    return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .flatMap((entry) => readDirectoryCandidate(directory, entry.name))
+        .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+function readDirectoryCandidate(directory, name) {
+    try {
+        return [{ name, directory, path: realpathSync(join(directory, name)) }];
+    }
+    catch (error) {
+        if (isNodeError(error) && (error.code === "ENOENT" || error.code === "ENOTDIR"))
+            return [];
+        throw error;
+    }
+}
+function classifyCandidates(state, ctx) {
+    const linkedCandidates = [];
+    const ordinaryCandidates = [];
+    for (const candidate of state.candidates) {
+        (isLinkedWorktree(candidate.path) ? linkedCandidates : ordinaryCandidates).push(candidate);
+    }
+    const classified = ordinaryCandidates.flatMap((candidate) => classifyCandidate(candidate, state, ctx));
+    const projects = excludeWorkFilesRepositories(classified, state.directories);
+    attachLinkedWorktrees(linkedCandidates, projects, state.directories);
+    return projects;
+}
+function classifyCandidate(candidate, state, ctx) {
+    if (mainWorktreeGitDirectory(candidate.path) === undefined) {
+        if (existsSync(join(candidate.path, PROJECT_CONFIG_FILENAME))) {
+            state.issues.push({ path: candidate.path, message: "not a git main worktree" });
+        }
+        else {
+            addOther(state.directories, candidate.directory, candidate.name);
+        }
+        return [];
+    }
+    const description = readProjectReport(ctx.alignfirstCommand, candidate.path, ctx.env);
+    if ("error" in description) {
+        state.issues.push({ path: candidate.path, message: description.error });
+        return [];
+    }
+    const project = {
+        name: candidate.name,
+        path: candidate.path,
+        directory: candidate.directory,
+        description,
+        ...(description.config?.portRange === undefined
+            ? {}
+            : { portRange: description.config.portRange }),
+        workspaces: [],
+    };
+    const enclosingRange = findEnclosingRange(candidate.enclosingRanges, project.portRange);
+    if (enclosingRange?.code !== undefined)
+        project.portRangeCode = enclosingRange.code;
+    if (description.cli !== null && !description.cli.satisfied) {
+        state.issues.push({
+            path: candidate.path,
+            message: `AlignFirst CLI ${description.cli.installed} does not satisfy required range ` +
+                description.cli.range,
+        });
+    }
+    reportOutsideRange(project.path, project.portRange, candidate.enclosingRanges, state.issues);
+    return [project];
+}
+// A repository holding another project's `.plans` target, such as a work-files clone, is listed
+// with the others.
+function excludeWorkFilesRepositories(projects, directories) {
+    const plansTargets = projects.flatMap((project) => {
+        const target = realPlansPath(project);
+        return target === undefined ? [] : [{ owner: project.path, target }];
+    });
+    return projects.filter((project) => {
+        const holdsPlans = plansTargets.some(({ owner, target }) => owner !== project.path && isSameOrInside(target, project.path));
+        if (holdsPlans)
+            addOther(directories, project.directory, project.name);
+        return !holdsPlans;
+    });
+}
+function realPlansPath(project) {
+    const plans = project.description.locations[".plans"];
+    if (!plans.exists)
+        return;
+    try {
+        return realpathSync(plans.path);
+    }
+    catch {
+        return;
+    }
+}
+function isSameOrInside(path, ancestor) {
+    return path === ancestor || path.startsWith(`${ancestor}${sep}`);
+}
+function isLinkedWorktree(path) {
+    try {
+        return lstatSync(join(path, ".git")).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function attachLinkedWorktrees(candidates, projects, directories) {
+    const mainsByGitDirectory = new Map();
+    for (const project of projects) {
+        const gitDirectory = mainWorktreeGitDirectory(project.path);
+        if (gitDirectory === undefined)
+            continue;
+        mainsByGitDirectory.set(gitDirectory, {
+            name: project.name,
+            directory: project.directory,
+            path: project.path,
+            gitDirectory,
+            project,
+        });
+    }
+    for (const candidate of candidates) {
+        const main = linkedWorktreeMain(candidate.path, mainsByGitDirectory);
+        if (main === undefined)
+            addOther(directories, candidate.directory, candidate.name);
+        else
+            main.project.workspaces.push(candidate.name);
+    }
+}
+function mainWorktreeGitDirectory(projectPath) {
+    const gitPath = join(projectPath, ".git");
+    try {
+        if (!lstatSync(gitPath).isDirectory())
+            return;
+        return realpathSync(gitPath);
+    }
+    catch {
+        return;
+    }
+}
+function linkedWorktreeMain(worktreePath, mainsByGitDirectory) {
+    const worktreeGitFile = join(worktreePath, ".git");
+    try {
+        if (!lstatSync(worktreeGitFile).isFile())
+            return;
+        const metadataDirectory = resolveGitdirFile(worktreeGitFile);
+        const mainGitDirectory = resolveMetadataPath(metadataDirectory, "commondir");
+        const main = mainsByGitDirectory.get(mainGitDirectory);
+        if (main === undefined)
+            return;
+        if (dirname(metadataDirectory) !== join(mainGitDirectory, "worktrees"))
+            return;
+        const backlink = resolveMetadataPath(metadataDirectory, "gitdir");
+        if (backlink !== realpathSync(worktreeGitFile))
+            return;
+        return main;
+    }
+    catch {
+        return;
+    }
+}
+function resolveGitdirFile(gitFile) {
+    const match = /^gitdir:\s*(.+)\s*$/u.exec(readFileSync(gitFile, "utf8"));
+    if (match === null)
+        throw new Error(`Invalid Git file: ${gitFile}`);
+    return realpathSync(resolve(dirname(gitFile), match[1]));
+}
+function resolveMetadataPath(metadataDirectory, filename) {
+    const target = readFileSync(join(metadataDirectory, filename), "utf8").trim();
+    if (target.length === 0)
+        throw new Error(`Empty Git metadata file: ${filename}`);
+    return realpathSync(resolve(metadataDirectory, target));
+}
+function addOther(directories, directoryPath, name) {
+    const directory = directories.find(({ path }) => path === directoryPath);
+    if (directory === undefined)
+        throw new Error(`Unknown projects directory: ${directoryPath}`);
+    directory.others.push(name);
+}
+function reportOutsideRange(path, range, enclosingRanges, issues) {
+    if (range === undefined || enclosingRanges === undefined)
+        return;
+    if (findEnclosingRange(enclosingRanges, range) !== undefined)
+        return;
+    issues.push({
+        path,
+        message: `port range ${formatRange(range)} fits no single enclosing range: ` +
+            enclosingRanges.map(formatRange).join(", "),
+    });
+}
+function findEnclosingRange(ranges, claim) {
+    if (claim === undefined)
+        return;
+    return ranges?.find((range) => containsRange(range, claim));
+}
+// Two projects can share a companion only through a `_` in a directory name.
+function reportSharedCompanions(projects, issues) {
+    const projectsByCompanion = new Map();
+    for (const project of projects) {
+        const dir = project.description.companion?.dir;
+        if (dir === undefined)
+            continue;
+        projectsByCompanion.set(dir, [...(projectsByCompanion.get(dir) ?? []), project]);
+    }
+    for (const [dir, group] of projectsByCompanion) {
+        if (group.length < 2)
+            continue;
+        for (const project of group) {
+            const others = group
+                .filter((other) => other !== project)
+                .map((other) => other.path)
+                .toSorted();
+            issues.push({
+                path: project.path,
+                message: `shares companion directory ${dir} with ${others.join(", ")}`,
+            });
+        }
+    }
+}
+function reportOverlappingClaims(projects, directoryClaims, issues) {
+    const claims = [
+        ...directoryClaims,
+        ...projects.flatMap((project) => project.portRange === undefined
+            ? []
+            : [{ scope: project.directory, path: project.path, portRange: project.portRange }]),
+    ].toSorted((left, right) => left.scope.localeCompare(right.scope) || left.path.localeCompare(right.path));
+    for (let index = 0; index < claims.length; ++index) {
+        const claim = claims[index];
+        for (let previous = 0; previous < index; ++previous) {
+            const other = claims[previous];
+            if (claim.scope !== other.scope || !rangesOverlap(claim.portRange, other.portRange))
+                continue;
+            issues.push({
+                path: claim.path,
+                message: `port range ${formatRange(claim.portRange)} overlaps ${basename(other.path)}`,
+                conflict: {
+                    left: { path: other.path, portRange: other.portRange },
+                    right: { path: claim.path, portRange: claim.portRange },
+                },
+            });
+        }
+    }
+}
+function sortInventory(directories, projects, issues) {
+    directories.sort((left, right) => left.path.localeCompare(right.path));
+    projects.sort((left, right) => left.path.localeCompare(right.path));
+    issues.sort((left, right) => left.path.localeCompare(right.path));
+    for (const directory of directories)
+        directory.others.sort((left, right) => left.localeCompare(right));
+    for (const project of projects)
+        project.workspaces.sort((left, right) => left.localeCompare(right));
+}

package/dist/project/format.d.ts

@@ -0,0 +1,6 @@
+import type { PortRange } from "./markers.js";
+export declare function formatRange(range: PortRange): string;
+/** Escapes C0, C1 and line-separator characters for a terminal-safe line. */
+export declare function escapeControlCharacters(value: string): string;
+/** Escapes the characters JSON.stringify leaves as-is: C1 and the line separators. */
+export declare function escapeAdditionalJsonCharacters(value: string): string;

package/dist/project/format.js

@@ -0,0 +1,31 @@
+export function formatRange(range) {
+    return `${range.first}..${range.last}`;
+}
+/** Escapes C0, C1 and line-separator characters for a terminal-safe line. */
+export function escapeControlCharacters(value) {
+    return Array.from(value, (character) => {
+        if (!isControlCharacter(character, true))
+            return character;
+        const jsonEscape = JSON.stringify(character).slice(1, -1);
+        return jsonEscape === character ? unicodeEscape(character) : jsonEscape;
+    }).join("");
+}
+/** Escapes the characters JSON.stringify leaves as-is: C1 and the line separators. */
+export function escapeAdditionalJsonCharacters(value) {
+    return Array.from(value, (character) => isControlCharacter(character, false) ? unicodeEscape(character) : character).join("");
+}
+function isControlCharacter(character, includeC0) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === undefined)
+        return false;
+    return ((includeC0 && codePoint <= 0x1f) ||
+        (codePoint >= 0x7f && codePoint <= 0x9f) ||
+        codePoint === 0x2028 ||
+        codePoint === 0x2029);
+}
+function unicodeEscape(character) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === undefined)
+        throw new Error("Cannot escape an empty character");
+    return `\\u${codePoint.toString(16).padStart(4, "0")}`;
+}

package/dist/project/guide.d.ts

@@ -0,0 +1,3 @@
+import type { CommandForms } from "../command-form.js";
+import type { ProjectInventory } from "./discovery.js";
+export declare function renderProjectsGuide(forms: CommandForms, inventory?: ProjectInventory): string;

package/dist/project/guide.js

@@ -0,0 +1,69 @@
+import { dirname } from "node:path";
+import { renderGuideTemplate } from "../guide/render-template.js";
+import { escapeAdditionalJsonCharacters, formatRange } from "./format.js";
+// The projects guide serves the OpenClaw playbook only.
+export function renderProjectsGuide(forms, inventory) {
+    const guide = renderGuideTemplate("project.md", "openclaw", forms);
+    if (inventory === undefined)
+        return guide;
+    const sections = inventory.directories.map((directory) => renderDirectory(inventory, directory));
+    return `${guide}\n\n${sections.join("\n\n")}`;
+}
+function renderDirectory(inventory, directory) {
+    const lines = [`## Directory ${renderData(directory.path)}`];
+    if (directory.description !== undefined) {
+        lines.push("", `Description: ${renderData(directory.description)}`);
+    }
+    lines.push("", "Port ranges:");
+    if (directory.portRanges === undefined)
+        lines.push("- (none)");
+    else {
+        for (const range of directory.portRanges)
+            lines.push(`- ${renderMarkerRange(range)}`);
+    }
+    lines.push("", "Projects:");
+    const projects = inventory.projects.filter((project) => project.directory === directory.path);
+    if (projects.length === 0)
+        lines.push("- (none)");
+    else {
+        for (const project of projects) {
+            lines.push(`- ${renderData(project.name)} — ${renderProjectRange(project.portRange, project.portRangeCode)}`);
+        }
+    }
+    lines.push("", "Nested directories:");
+    const nested = inventory.directories.filter((candidate) => candidate.path !== directory.path && dirname(candidate.path) === directory.path);
+    if (nested.length === 0)
+        lines.push("- (none)");
+    else {
+        for (const child of nested) {
+            lines.push(`- ${renderData(child.path)} — ${renderRanges(child.portRanges)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function renderData(value) {
+    const escaped = escapeAdditionalJsonCharacters(JSON.stringify(value));
+    const delimiter = "`".repeat(longestBacktickRun(escaped) + 1);
+    return `${delimiter}${escaped}${delimiter}`;
+}
+function longestBacktickRun(value) {
+    let longest = 0;
+    for (const [run] of value.matchAll(/`+/gu))
+        longest = Math.max(longest, run.length);
+    return longest;
+}
+function renderRange(range, absent = "(none)") {
+    return range === undefined ? absent : formatRange(range);
+}
+function renderProjectRange(range, code) {
+    const rendered = renderRange(range, "(portless)");
+    return `${rendered}${code === undefined ? "" : ` (${code})`}`;
+}
+function renderRanges(ranges) {
+    return ranges === undefined ? "(none)" : ranges.map(renderMarkerRange).join(", ");
+}
+function renderMarkerRange(range) {
+    const code = range.code ?? "default";
+    const description = range.description === undefined ? "" : ` — ${renderData(range.description)}`;
+    return `${formatRange(range)} (${code})${description}`;
+}

package/dist/project/layout.d.ts

@@ -0,0 +1,36 @@
+import type { PortRange } from "./markers.js";
+export type ItemName = ".alignfirst.json" | ".alignfirst.md" | "DEVELOPERS.md" | "docs" | ".plans" | "_aligndev";
+export interface ProjectReport {
+    source: ConfigSource | null;
+    cli: ProjectCliReport | null;
+    config: ProjectConfigView | null;
+    companion: CompanionReport | null;
+    locations: Record<ItemName, ItemLocation>;
+}
+export type ConfigSource = "project" | "companion";
+export interface ProjectCliReport {
+    installed: string;
+    range: string;
+    satisfied: boolean;
+}
+export interface ProjectConfigView {
+    ticketIdPattern?: string;
+    plans?: {
+        folder?: string;
+    };
+    portRange?: PortRange;
+}
+export interface CompanionReport {
+    dir: string;
+    exists: boolean;
+}
+export interface ItemLocation {
+    path: string;
+    in: "project" | "companion";
+    exists: boolean;
+}
+export interface ProjectError {
+    error: string;
+}
+export declare function readProjectReport(command: string[], cwd: string, env: NodeJS.ProcessEnv): ProjectReport | ProjectError;
+export declare function companionInUse(report: ProjectReport, items: readonly ItemName[]): boolean;

package/dist/project/layout.js

@@ -0,0 +1,128 @@
+import { runAlignfirst } from "../alignfirst-cli.js";
+import { errorMessage } from "../errors.js";
+const MIN_ALIGNFIRST_VERSION = "0.5.0";
+export function readProjectReport(command, cwd, env) {
+    const result = runAlignfirst(command, ["config", "--json"], cwd, env);
+    if (result.status !== 0) {
+        const error = firstLine(result.stderr);
+        return { error: error === "" ? "alignfirst config failed" : error };
+    }
+    let value;
+    try {
+        value = JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`Invalid alignfirst config report for ${cwd}: ${errorMessage(error)}`);
+    }
+    return parseProjectReport(value, cwd);
+}
+function firstLine(value) {
+    return value.trim().split("\n", 1)[0] ?? "";
+}
+function parseProjectReport(value, path) {
+    if (!isRecord(value))
+        throw invalidReport(path);
+    if (value.source === "root" || value.locations === undefined)
+        throw outdatedAlignfirst(path);
+    return {
+        source: parseSource(value.source, path),
+        cli: parseCli(value.cli, path),
+        config: parseConfig(value.config, path),
+        companion: parseCompanion(value.companion, path),
+        locations: parseLocations(value.locations, path),
+    };
+}
+function parseSource(value, path) {
+    if (value === "project" || value === "companion" || value === null)
+        return value;
+    throw invalidReport(path);
+}
+function parseCli(value, path) {
+    if (value === null)
+        return null;
+    if (!isRecord(value) ||
+        typeof value.installed !== "string" ||
+        typeof value.range !== "string" ||
+        typeof value.satisfied !== "boolean") {
+        throw invalidReport(path);
+    }
+    return { installed: value.installed, range: value.range, satisfied: value.satisfied };
+}
+function parseConfig(value, path) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        throw invalidReport(path);
+    const ticketIdPattern = value.ticketIdPattern;
+    const plans = parsePlans(value.plans, path);
+    const portRange = value.portRange;
+    if (ticketIdPattern !== undefined && typeof ticketIdPattern !== "string")
+        throw invalidReport(path);
+    if (portRange !== undefined && !isPortRange(portRange))
+        throw invalidReport(path);
+    return {
+        ...(ticketIdPattern === undefined ? {} : { ticketIdPattern }),
+        ...(plans === undefined ? {} : { plans }),
+        ...(portRange === undefined ? {} : { portRange }),
+    };
+}
+function parsePlans(value, path) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        throw invalidReport(path);
+    if (value.folder !== undefined && typeof value.folder !== "string")
+        throw invalidReport(path);
+    return value.folder === undefined ? {} : { folder: value.folder };
+}
+// The report's other companion fields (`entries`, `flags`) are alignfirst's concern.
+function parseCompanion(value, path) {
+    if (value === null)
+        return null;
+    if (!isRecord(value) || typeof value.dir !== "string" || typeof value.exists !== "boolean") {
+        throw invalidReport(path);
+    }
+    return { dir: value.dir, exists: value.exists };
+}
+function parseLocations(value, path) {
+    if (!isRecord(value))
+        throw invalidReport(path);
+    const location = (name) => parseLocation(value[name], path);
+    return {
+        ".alignfirst.json": location(".alignfirst.json"),
+        ".alignfirst.md": location(".alignfirst.md"),
+        "DEVELOPERS.md": location("DEVELOPERS.md"),
+        docs: location("docs"),
+        ".plans": location(".plans"),
+        _aligndev: location("_aligndev"),
+    };
+}
+function parseLocation(value, path) {
+    if (!isRecord(value) ||
+        typeof value.path !== "string" ||
+        (value.in !== "project" && value.in !== "companion") ||
+        typeof value.exists !== "boolean") {
+        throw invalidReport(path);
+    }
+    return { path: value.path, in: value.in, exists: value.exists };
+}
+function invalidReport(path) {
+    return new Error(`Invalid alignfirst config report for ${path}`);
+}
+function outdatedAlignfirst(path) {
+    return new Error(`The alignfirst CLI used in ${path} is too old: aligndev requires alignfirst ` +
+        `${MIN_ALIGNFIRST_VERSION} or later.`);
+}
+function isPortRange(value) {
+    return isRecord(value) && typeof value.first === "number" && typeof value.last === "number";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+// Some of the given items exists in the companion directory.
+export function companionInUse(report, items) {
+    return items.some((item) => {
+        const location = report.locations[item];
+        return location.in === "companion" && location.exists;
+    });
+}

package/dist/project/markers.d.ts

@@ -0,0 +1,18 @@
+export declare const MARKER_FILENAME = ".alignfirst-projects.json";
+export interface PortRange {
+    first: number;
+    last: number;
+}
+export interface ProjectsMarker {
+    description?: string;
+    portRanges?: MarkerPortRange[];
+}
+export interface MarkerPortRange extends PortRange {
+    code?: string;
+    description?: string;
+}
+export declare function readMarker(dir: string): ProjectsMarker | undefined;
+export declare function writeMarker(dir: string, marker: ProjectsMarker): void;
+export declare function assertValidPortRanges(ranges: MarkerPortRange[], label: string): void;
+export declare function containsRange(available: PortRange, allocation: PortRange): boolean;
+export declare function rangesOverlap(left: PortRange, right: PortRange): boolean;

package/dist/project/markers.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { errorMessage } from "../errors.js";
+import { formatRange } from "./format.js";
+export const MARKER_FILENAME = ".alignfirst-projects.json";
+const markerPortRangeSchema = type({
+    "+": "reject",
+    first: "1 <= number.integer <= 65535",
+    last: "1 <= number.integer <= 65535",
+    "code?": /^[a-z][a-z0-9-]*$/,
+    "description?": "string",
+});
+const markerSchema = type({
+    "+": "reject",
+    "description?": "string",
+    "portRanges?": markerPortRangeSchema.array().atLeastLength(1),
+});
+export function readMarker(dir) {
+    const path = join(dir, MARKER_FILENAME);
+    if (!existsSync(path))
+        return;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw invalidMarker(path, errorMessage(error));
+    }
+    const marker = markerSchema(value);
+    if (marker instanceof type.errors) {
+        throw invalidMarker(path, marker.summary.split("\n", 1)[0]);
+    }
+    if (marker.portRanges !== undefined)
+        assertValidPortRanges(marker.portRanges, path);
+    return marker;
+}
+export function writeMarker(dir, marker) {
+    writeFileSync(join(dir, MARKER_FILENAME), `${JSON.stringify(marker, undefined, 2)}\n`);
+}
+export function assertValidPortRanges(ranges, label) {
+    for (const range of ranges)
+        assertValidPortRange(range, label);
+    assertUniquePortRangeCodes(ranges, label);
+    if (ranges.filter(({ code }) => code === undefined).length > 1) {
+        throw new Error(`Invalid ${label}: at most one port range may have no code`);
+    }
+    for (let index = 0; index < ranges.length; ++index) {
+        const range = ranges[index];
+        for (let previous = 0; previous < index; ++previous) {
+            const other = ranges[previous];
+            if (!rangesOverlap(range, other))
+                continue;
+            throw new Error(`Invalid ${label}: port ranges ${formatRange(other)} and ${formatRange(range)} overlap`);
+        }
+    }
+}
+function assertValidPortRange(range, label) {
+    if (!Number.isInteger(range.first) ||
+        !Number.isInteger(range.last) ||
+        range.first < 1 ||
+        range.first > 65_535 ||
+        range.last < 1 ||
+        range.last > 65_535) {
+        throw new Error(`Invalid ${label}: port range endpoints must be integers from 1 to 65535`);
+    }
+    if (range.first > range.last) {
+        throw new Error(`Invalid ${label}: portRange.first must not exceed portRange.last`);
+    }
+}
+function assertUniquePortRangeCodes(ranges, label) {
+    const codes = new Set();
+    for (const { code } of ranges) {
+        if (code === undefined)
+            continue;
+        if (codes.has(code)) {
+            throw new Error(`Invalid ${label}: duplicate port range code ${JSON.stringify(code)}`);
+        }
+        codes.add(code);
+    }
+}
+export function containsRange(available, allocation) {
+    return allocation.first >= available.first && allocation.last <= available.last;
+}
+export function rangesOverlap(left, right) {
+    return left.first <= right.last && right.first <= left.last;
+}
+function invalidMarker(path, detail) {
+    return new Error(`Invalid projects marker ${path}: ${detail}`);
+}

package/dist/project/ports.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectInventory } from "./discovery.js";
+import { type PortRange } from "./markers.js";
+export declare function findFreeBlock(inventory: ProjectInventory, size: number, code?: string): PortRange;