@typed/app 1.0.0-beta.1

package/dist/internal/extractHttpApiLiterals.js

@@ -0,0 +1,45 @@
+function getLiteralText(node) {
+    if (!node || node.kind !== "literal")
+        return null;
+    return node.text || null;
+}
+function getPathFromRouteType(type) {
+    if (type.kind === "literal") {
+        const raw = type.text;
+        return raw ? (raw.startsWith("/") ? raw : `/${raw}`) : null;
+    }
+    if (type.kind === "object") {
+        const pathProp = type.properties.find((p) => p.name === "path");
+        if (!pathProp)
+            return null;
+        const raw = getLiteralText(pathProp.type);
+        return raw ? (raw.startsWith("/") ? raw : `/${raw}`) : null;
+    }
+    if (type.kind === "reference") {
+        const typeArgs = type.typeArguments;
+        if (typeArgs?.length)
+            return getPathFromRouteType(typeArgs[0]);
+    }
+    return null;
+}
+/**
+ * Extracts route path and method from TypeInfo snapshot exports.
+ * Reads from route and method exports; path from route type (literal or object.path).
+ */
+export function extractEndpointLiterals(snapshot, stem) {
+    let path = `/${stem}`;
+    let method = "GET";
+    const routeExport = snapshot.exports.find((e) => e.name === "route");
+    if (routeExport) {
+        const p = getPathFromRouteType(routeExport.type);
+        if (p)
+            path = p;
+    }
+    const methodExport = snapshot.exports.find((e) => e.name === "method");
+    if (methodExport) {
+        const m = getLiteralText(methodExport.type);
+        if (m)
+            method = m.toUpperCase();
+    }
+    return { path, method, name: stem };
+}

package/dist/internal/httpapiDescriptorTree.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Filesystem tree AST for HttpApi virtual module discovery.
+ * Converts role-classified artifacts into a deterministic tree (ApiRoot, Group, PathlessDirectory, Endpoint, Convention metadata).
+ * Parenthesized pathless directories do not create a named group but preserve composition order.
+ */
+import type { HttpApiDirectoryCompanionKind, HttpApiEndpointCompanionKind, HttpApiFileRole } from "./httpapiFileRoles.js";
+export declare function isPathlessDirectorySegment(segment: string): boolean;
+/** Reference to a directory-level convention file (e.g. _dependencies.ts). */
+export type DirectoryConventionRef = {
+    readonly path: string;
+    readonly kind: HttpApiDirectoryCompanionKind;
+};
+/** Reference to API root or group override convention. */
+export type RootOrGroupConventionRef = {
+    readonly path: string;
+    readonly kind: "api_root" | "group_override";
+};
+/** Reference to an endpoint companion file (e.g. list.openapi.ts). */
+export type EndpointCompanionRef = {
+    readonly path: string;
+    readonly kind: HttpApiEndpointCompanionKind;
+};
+/** Leaf node: endpoint primary with optional companion refs. */
+export type HttpApiEndpointNode = {
+    readonly type: "endpoint";
+    readonly path: string;
+    /** Filename stem without extension (e.g. "list"). */
+    readonly stem: string;
+    readonly companions: readonly EndpointCompanionRef[];
+};
+/** Directory that does not create a named group (e.g. (internal)). */
+export type HttpApiPathlessDirectoryNode = {
+    readonly type: "pathless_directory";
+    /** Full relative dir path (e.g. "users/(internal)"). */
+    readonly dirPath: string;
+    readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+    readonly children: readonly HttpApiTreeNode[];
+};
+/** Named group directory (creates HttpApiGroup). */
+export type HttpApiGroupNode = {
+    readonly type: "group";
+    /** Group name (default from directory segment, override from _group.ts). */
+    readonly groupName: string;
+    /** Full relative dir path (e.g. "users"). */
+    readonly dirPath: string;
+    readonly children: readonly HttpApiTreeNode[];
+    readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+};
+export type HttpApiTreeNode = HttpApiEndpointNode | HttpApiGroupNode | HttpApiPathlessDirectoryNode;
+/** Root of the descriptor tree. */
+export type HttpApiDescriptorTree = {
+    readonly type: "api_root";
+    readonly dirPath: "";
+    readonly children: readonly HttpApiTreeNode[];
+    readonly conventions: readonly (DirectoryConventionRef | RootOrGroupConventionRef)[];
+    /** Diagnostics-ready: unsupported roles collected during parse. */
+    readonly diagnostics: readonly HttpApiTreeDiagnostic[];
+};
+export type HttpApiTreeDiagnostic = {
+    readonly code: string;
+    readonly message: string;
+    readonly path: string;
+};
+export type BuildHttpApiDescriptorTreeInput = {
+    /** Classified file roles (supported and unsupported_reserved). */
+    readonly roles: readonly HttpApiFileRole[];
+    /** Optional: only include paths under this base (relative); not used for filtering if empty. */
+    readonly baseDir?: string;
+};
+/**
+ * Builds a deterministic tree AST from classified file roles.
+ * Pathless directory segments (e.g. "(internal)") are represented as PathlessDirectoryNode and do not create a group name.
+ */
+export declare function buildHttpApiDescriptorTree(input: BuildHttpApiDescriptorTreeInput): HttpApiDescriptorTree;
+//# sourceMappingURL=httpapiDescriptorTree.d.ts.map

package/dist/internal/httpapiDescriptorTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpapiDescriptorTree.d.ts","sourceRoot":"","sources":["../../src/internal/httpapiDescriptorTree.ts"],"names":[],"mappings":"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"}

package/dist/internal/httpapiDescriptorTree.js

@@ -0,0 +1,182 @@
+/**
+ * Filesystem tree AST for HttpApi virtual module discovery.
+ * Converts role-classified artifacts into a deterministic tree (ApiRoot, Group, PathlessDirectory, Endpoint, Convention metadata).
+ * Parenthesized pathless directories do not create a named group but preserve composition order.
+ */
+import { compareHttpApiPathOrder, sortHttpApiPaths, } from "./httpapiFileRoles.js";
+/** Path segment is pathless when it matches (name) and does not create an HttpApiGroup. */
+const PATHLESS_DIRECTORY_PATTERN = /^\([^)]*\)$/;
+export function isPathlessDirectorySegment(segment) {
+    return PATHLESS_DIRECTORY_PATTERN.test(segment);
+}
+/**
+ * Builds a deterministic tree AST from classified file roles.
+ * Pathless directory segments (e.g. "(internal)") are represented as PathlessDirectoryNode and do not create a group name.
+ */
+export function buildHttpApiDescriptorTree(input) {
+    const { roles } = input;
+    const diagnostics = [];
+    const supported = [];
+    for (const r of roles) {
+        if (r.role === "unsupported_reserved") {
+            diagnostics.push({
+                code: r.diagnosticCode,
+                message: r.diagnosticMessage,
+                path: r.path,
+            });
+        }
+        else {
+            supported.push(r);
+        }
+    }
+    const apiRootConventions = [];
+    const directoryConventionsByDir = new Map();
+    const endpointCompanionsByKey = new Map();
+    for (const r of supported) {
+        if (r.role === "api_root") {
+            apiRootConventions.push({ path: r.path, kind: "api_root" });
+            continue;
+        }
+        if (r.role === "group_override") {
+            const dir = dirname(r.path);
+            directoryConventionsByDir.set(dir, [
+                ...(directoryConventionsByDir.get(dir) ?? []),
+                { path: r.path, kind: "group_override" },
+            ]);
+            continue;
+        }
+        if (r.role === "directory_companion") {
+            const dir = dirname(r.path);
+            const list = directoryConventionsByDir.get(dir) ?? [];
+            list.push({ path: r.path, kind: r.kind });
+            directoryConventionsByDir.set(dir, list);
+            continue;
+        }
+        if (r.role === "endpoint_primary") {
+            continue;
+        }
+        if (r.role === "endpoint_companion") {
+            const dir = dirname(r.path);
+            const key = dir ? `${dir}/${r.endpointStem}` : r.endpointStem;
+            const list = endpointCompanionsByKey.get(key) ?? [];
+            list.push({ path: r.path, kind: r.kind });
+            endpointCompanionsByKey.set(key, list);
+        }
+    }
+    const allDirs = new Set();
+    function addDirAndAncestors(d) {
+        allDirs.add(d);
+        const idx = d.lastIndexOf("/");
+        if (idx > 0)
+            addDirAndAncestors(d.slice(0, idx));
+    }
+    for (const r of supported) {
+        const p = "path" in r ? r.path : "";
+        addDirAndAncestors(dirname(p));
+    }
+    for (const [dir] of directoryConventionsByDir) {
+        addDirAndAncestors(dir);
+    }
+    const sortedDirs = sortHttpApiPaths([...allDirs]);
+    const dirSegments = (dirPath) => dirPath ? dirPath.split("/").filter(Boolean) : [];
+    const childrenByParentDir = new Map();
+    for (const d of sortedDirs) {
+        const segments = dirSegments(d);
+        if (segments.length === 0)
+            continue;
+        const parent = segments.length === 1 ? "" : segments.slice(0, -1).join("/");
+        const list = childrenByParentDir.get(parent) ?? [];
+        if (!list.includes(d))
+            list.push(d);
+        childrenByParentDir.set(parent, list);
+    }
+    function buildNode(dirPath) {
+        const directFiles = supported
+            .filter((r) => {
+            if (r.role !== "endpoint_primary")
+                return false;
+            const p = r.path;
+            const d = dirname(p);
+            return d === dirPath;
+        })
+            .map((r) => r)
+            .sort((a, b) => compareHttpApiPathOrder(a.path, b.path));
+        const childDirs = (childrenByParentDir.get(dirPath) ?? []).slice().sort(compareHttpApiPathOrder);
+        const nodes = [];
+        for (const f of directFiles) {
+            const stem = stemFromPath(f.path);
+            const companionKey = dirPath ? `${dirPath}/${stem}` : stem;
+            const companions = endpointCompanionsByKey.get(companionKey) ?? [];
+            nodes.push({
+                type: "endpoint",
+                path: f.path,
+                stem,
+                companions: [...companions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+            });
+        }
+        for (const childDir of childDirs) {
+            const segments = dirSegments(childDir);
+            const segmentName = segments[segments.length - 1] ?? "";
+            if (isPathlessDirectorySegment(segmentName)) {
+                const childNodes = buildNode(childDir);
+                const conventions = directoryConventionsByDir.get(childDir) ?? [];
+                nodes.push({
+                    type: "pathless_directory",
+                    dirPath: childDir,
+                    conventions: [...conventions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+                    children: childNodes.length === 0 ? [] : childNodes.slice().sort(compareTreeNodes),
+                });
+            }
+            else {
+                const groupName = segmentName;
+                const childNodes = buildNode(childDir);
+                const conventions = directoryConventionsByDir.get(childDir) ?? [];
+                nodes.push({
+                    type: "group",
+                    groupName,
+                    dirPath: childDir,
+                    children: childNodes.length === 0 ? [] : childNodes.slice().sort(compareTreeNodes),
+                    conventions: [...conventions].sort((a, b) => compareHttpApiPathOrder(a.path, b.path)),
+                });
+            }
+        }
+        return nodes.slice().sort(compareTreeNodes);
+    }
+    const rootChildren = buildNode("");
+    const rootConventions = [...apiRootConventions];
+    const rootDirConventions = directoryConventionsByDir.get("") ?? [];
+    for (const c of rootDirConventions) {
+        rootConventions.push(c);
+    }
+    rootConventions.sort((a, b) => compareHttpApiPathOrder(a.path, b.path));
+    return {
+        type: "api_root",
+        dirPath: "",
+        children: rootChildren,
+        conventions: rootConventions,
+        diagnostics,
+    };
+}
+function dirname(p) {
+    const i = p.lastIndexOf("/");
+    return i < 0 ? "" : p.slice(0, i);
+}
+function stemFromPath(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const extIdx = base.lastIndexOf(".");
+    return extIdx <= 0 ? base : base.slice(0, extIdx);
+}
+function nodeSortKey(n) {
+    switch (n.type) {
+        case "endpoint":
+            return n.path;
+        case "group":
+        case "pathless_directory":
+            return n.dirPath;
+        default:
+            return "";
+    }
+}
+function compareTreeNodes(a, b) {
+    return compareHttpApiPathOrder(nodeSortKey(a), nodeSortKey(b));
+}

package/dist/internal/httpapiEndpointContract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Endpoint contract validation for HttpApi virtual module.
+ * Validates required fields (route, method, handler). Optional: headers, body, error, success.
+ * Route covers path + query; headers/body mirror decoders from HttpServerRequest;
+ * error/success encode response payloads with annotated status codes.
+ * Handler returns require structural type checking (assignable to success/error schemas)
+ * and coercion into HttpServerResponse via Effect's HttpApi layer.
+ *
+ * @see .docs/specs/httpapi-virtual-module-plugin/spec.md (Endpoint contract, Endpoint Contract Validator)
+ */
+import type { ValidationResult } from "./validation.js";
+/** Minimal endpoint contract shape (runtime check) */
+export interface EndpointContractInput {
+    readonly route?: unknown;
+    readonly method?: unknown;
+    readonly handler?: unknown;
+    readonly headers?: unknown;
+    readonly body?: unknown;
+    readonly error?: unknown;
+    readonly success?: unknown;
+}
+/** Validated endpoint contract */
+export interface ValidatedEndpointContract {
+    readonly route: unknown;
+    readonly method: string;
+    readonly handler: unknown;
+}
+/**
+ * Validates endpoint contract: required route, method, handler; optional headers, body, error, success.
+ */
+export declare function validateEndpointContract(input: unknown): ValidationResult<ValidatedEndpointContract>;
+//# sourceMappingURL=httpapiEndpointContract.d.ts.map

package/dist/internal/httpapiEndpointContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpapiEndpointContract.d.ts","sourceRoot":"","sources":["../../src/internal/httpapiEndpointContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcxD,sDAAsD;AACtD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,kCAAkC;AAClC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AASD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,yBAAyB,CAAC,CAsD7C"}

package/dist/internal/httpapiEndpointContract.js

@@ -0,0 +1,79 @@
+/**
+ * Endpoint contract validation for HttpApi virtual module.
+ * Validates required fields (route, method, handler). Optional: headers, body, error, success.
+ * Route covers path + query; headers/body mirror decoders from HttpServerRequest;
+ * error/success encode response payloads with annotated status codes.
+ * Handler returns require structural type checking (assignable to success/error schemas)
+ * and coercion into HttpServerResponse via Effect's HttpApi layer.
+ *
+ * @see .docs/specs/httpapi-virtual-module-plugin/spec.md (Endpoint contract, Endpoint Contract Validator)
+ */
+import { validateNonEmptyString } from "./validation.js";
+/** Supported HTTP method literals for endpoint contract */
+const HTTP_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+]);
+/**
+ * Checks that value is a non-null object (route/schema-like values are objects).
+ */
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Validates endpoint contract: required route, method, handler; optional headers, body, error, success.
+ */
+export function validateEndpointContract(input) {
+    if (!isObject(input)) {
+        return { ok: false, reason: "Endpoint contract must be an object" };
+    }
+    const contract = input;
+    if (contract.route === undefined) {
+        return { ok: false, reason: "Endpoint contract missing required field: route" };
+    }
+    if (!isObject(contract.route)) {
+        return { ok: false, reason: "Endpoint contract route must be an object (path + pathSchema + querySchema)" };
+    }
+    const route = contract.route;
+    if (route.pathSchema === undefined) {
+        return { ok: false, reason: "Endpoint contract route must include pathSchema" };
+    }
+    if (route.querySchema === undefined) {
+        return { ok: false, reason: "Endpoint contract route must include querySchema" };
+    }
+    const methodResult = validateNonEmptyString(contract.method, "method");
+    if (!methodResult.ok) {
+        return {
+            ok: false,
+            reason: `Endpoint contract method: ${methodResult.reason}`,
+        };
+    }
+    if (!HTTP_METHODS.has(methodResult.value)) {
+        return {
+            ok: false,
+            reason: `Endpoint contract method must be one of: ${[...HTTP_METHODS].join(", ")}`,
+        };
+    }
+    if (contract.handler === undefined) {
+        return { ok: false, reason: "Endpoint contract missing required field: handler" };
+    }
+    if (typeof contract.handler !== "function") {
+        return {
+            ok: false,
+            reason: "Endpoint contract handler must be a function",
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            route: contract.route,
+            method: methodResult.value,
+            handler: contract.handler,
+        },
+    };
+}

package/dist/internal/httpapiFileRoles.d.ts

@@ -0,0 +1,67 @@
+/**
+ * File-role classification for HttpApi virtual module discovery.
+ * Implements the supported file-role matrix: API root, group, endpoint primary, endpoint companions, directory companions.
+ * Diagnostics-ready metadata for unsupported reserved names.
+ */
+/** Script extensions that count as API source candidates (aligned with router plugin). */
+export declare const HTTPAPI_SCRIPT_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+export declare const HTTPAPI_SCRIPT_EXTENSION_SET: Set<string>;
+/** Directory companion filenames (exact match). */
+export declare const HTTPAPI_DIRECTORY_COMPANION_FILES: readonly ["_dependencies.ts", "_middlewares.ts", "_prefix.ts", "_openapi.ts"];
+/** Endpoint companion suffixes (stem ends with these before extension). */
+export declare const HTTPAPI_ENDPOINT_COMPANION_SUFFIXES: readonly [".name", ".dependencies", ".middlewares", ".prefix", ".openapi"];
+export type HttpApiDirectoryCompanionKind = (typeof HTTPAPI_DIRECTORY_COMPANION_FILES)[number];
+export type HttpApiEndpointCompanionKind = (typeof HTTPAPI_ENDPOINT_COMPANION_SUFFIXES)[number];
+/** Role of a discovered file relative to the API root. */
+export type HttpApiFileRole = {
+    readonly role: "api_root";
+    readonly path: string;
+} | {
+    readonly role: "group_override";
+    readonly path: string;
+} | {
+    readonly role: "endpoint_primary";
+    readonly path: string;
+} | {
+    readonly role: "endpoint_companion";
+    readonly path: string;
+    readonly kind: HttpApiEndpointCompanionKind;
+    readonly endpointStem: string;
+} | {
+    readonly role: "directory_companion";
+    readonly path: string;
+    readonly kind: HttpApiDirectoryCompanionKind;
+} | {
+    readonly role: "unsupported_reserved";
+    readonly path: string;
+    readonly diagnosticCode: string;
+    readonly diagnosticMessage: string;
+};
+/** Diagnostic-ready metadata for classification issues (e.g. unsupported companion name). */
+export type HttpApiFileRoleDiagnostic = {
+    readonly code: string;
+    readonly message: string;
+    readonly path: string;
+};
+/** Normalized path (posix) relative to API base; used for stable ordering. */
+export declare function normalizeHttpApiRelativePath(relativePath: string): string;
+/**
+ * Returns true if the file has a supported script extension for API discovery.
+ */
+export declare function isHttpApiScriptExtension(ext: string): boolean;
+/**
+ * Classifies a single file path (relative to API root, posix) into an HttpApi file role.
+ * Does not read the filesystem; only interprets path and filename.
+ * Returns diagnostic-ready metadata for unsupported reserved names.
+ */
+export declare function classifyHttpApiFileRole(relativePath: string): HttpApiFileRole;
+/**
+ * Stable sort key for discovered files: normalized relative path (posix).
+ * Use with Array.sort(compareHttpApiPathOrder) for deterministic ordering.
+ */
+export declare function compareHttpApiPathOrder(a: string, b: string): number;
+/**
+ * Sorts an array of relative paths in deterministic API discovery order.
+ */
+export declare function sortHttpApiPaths(paths: readonly string[]): string[];
+//# sourceMappingURL=httpapiFileRoles.d.ts.map

package/dist/internal/httpapiFileRoles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpapiFileRoles.d.ts","sourceRoot":"","sources":["../../src/internal/httpapiFileRoles.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,0FAA0F;AAC1F,eAAO,MAAM,yBAAyB,yEAS5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,aAExC,CAAC;AAEF,mDAAmD;AACnD,eAAO,MAAM,iCAAiC,+EAKpC,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,mCAAmC,4EAMtC,CAAC;AAEX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAC;AACrD,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,mCAAmC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5D;IACE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC,CAAC;AAEN,6FAA6F;AAC7F,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAMF,8EAA8E;AAC9E,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAwF7E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEnE"}

package/dist/internal/httpapiFileRoles.js

@@ -0,0 +1,145 @@
+/**
+ * File-role classification for HttpApi virtual module discovery.
+ * Implements the supported file-role matrix: API root, group, endpoint primary, endpoint companions, directory companions.
+ * Diagnostics-ready metadata for unsupported reserved names.
+ */
+import { toPosixPath } from "./path.js";
+/** Script extensions that count as API source candidates (aligned with router plugin). */
+export const HTTPAPI_SCRIPT_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mts",
+    ".cts",
+    ".mjs",
+    ".cjs",
+];
+export const HTTPAPI_SCRIPT_EXTENSION_SET = new Set(HTTPAPI_SCRIPT_EXTENSIONS.map((e) => e.toLowerCase()));
+/** Directory companion filenames (exact match). */
+export const HTTPAPI_DIRECTORY_COMPANION_FILES = [
+    "_dependencies.ts",
+    "_middlewares.ts",
+    "_prefix.ts",
+    "_openapi.ts",
+];
+/** Endpoint companion suffixes (stem ends with these before extension). */
+export const HTTPAPI_ENDPOINT_COMPANION_SUFFIXES = [
+    ".name",
+    ".dependencies",
+    ".middlewares",
+    ".prefix",
+    ".openapi",
+];
+const DIRECTORY_COMPANION_SET = new Set(HTTPAPI_DIRECTORY_COMPANION_FILES.map((f) => f.toLowerCase()));
+/** Normalized path (posix) relative to API base; used for stable ordering. */
+export function normalizeHttpApiRelativePath(relativePath) {
+    const posix = toPosixPath(relativePath);
+    return posix.replace(/^\.\//, "").replace(/\/+/g, "/");
+}
+/**
+ * Returns true if the file has a supported script extension for API discovery.
+ */
+export function isHttpApiScriptExtension(ext) {
+    return HTTPAPI_SCRIPT_EXTENSION_SET.has(ext.toLowerCase());
+}
+/**
+ * Classifies a single file path (relative to API root, posix) into an HttpApi file role.
+ * Does not read the filesystem; only interprets path and filename.
+ * Returns diagnostic-ready metadata for unsupported reserved names.
+ */
+export function classifyHttpApiFileRole(relativePath) {
+    const path = normalizeHttpApiRelativePath(relativePath);
+    const lastSlash = path.lastIndexOf("/");
+    const dir = lastSlash < 0 ? "" : path.slice(0, lastSlash);
+    const fileName = lastSlash < 0 ? path : path.slice(lastSlash + 1);
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith(".d.ts")) {
+        return {
+            role: "unsupported_reserved",
+            path,
+            diagnosticCode: "HTTPAPI-ROLE-001",
+            diagnosticMessage: `declaration files are not API sources: ${fileName}`,
+        };
+    }
+    const extIdx = fileName.lastIndexOf(".");
+    if (extIdx <= 0) {
+        return {
+            role: "unsupported_reserved",
+            path,
+            diagnosticCode: "HTTPAPI-ROLE-002",
+            diagnosticMessage: `filename must have a script extension: ${fileName}`,
+        };
+    }
+    const ext = fileName.slice(extIdx);
+    if (!isHttpApiScriptExtension(ext)) {
+        return {
+            role: "unsupported_reserved",
+            path,
+            diagnosticCode: "HTTPAPI-ROLE-003",
+            diagnosticMessage: `unsupported extension for API source: ${fileName}`,
+        };
+    }
+    const stem = fileName.slice(0, extIdx);
+    if (stem === "_api" && dir === "") {
+        return { role: "api_root", path };
+    }
+    if (stem === "_group") {
+        return { role: "group_override", path };
+    }
+    if (DIRECTORY_COMPANION_SET.has(fileName)) {
+        const kind = HTTPAPI_DIRECTORY_COMPANION_FILES.find((k) => k.toLowerCase() === lower);
+        return { role: "directory_companion", path, kind };
+    }
+    if (stem === "_api" || stem === "_group") {
+        return {
+            role: "unsupported_reserved",
+            path,
+            diagnosticCode: "HTTPAPI-ROLE-004",
+            diagnosticMessage: `convention file "${fileName}" must be at API root (_api.ts) or directory root (_group.ts)`,
+        };
+    }
+    for (const suffix of HTTPAPI_ENDPOINT_COMPANION_SUFFIXES) {
+        if (stem.endsWith(suffix)) {
+            const endpointStem = stem.slice(0, -suffix.length);
+            if (endpointStem === "") {
+                return {
+                    role: "unsupported_reserved",
+                    path,
+                    diagnosticCode: "HTTPAPI-ROLE-005",
+                    diagnosticMessage: `endpoint companion must have a base name: ${fileName}`,
+                };
+            }
+            return {
+                role: "endpoint_companion",
+                path,
+                kind: suffix,
+                endpointStem,
+            };
+        }
+    }
+    if (stem.startsWith("_")) {
+        return {
+            role: "unsupported_reserved",
+            path,
+            diagnosticCode: "HTTPAPI-ROLE-006",
+            diagnosticMessage: `reserved underscore-prefixed filename not in supported matrix: ${fileName}`,
+        };
+    }
+    return { role: "endpoint_primary", path };
+}
+/**
+ * Stable sort key for discovered files: normalized relative path (posix).
+ * Use with Array.sort(compareHttpApiPathOrder) for deterministic ordering.
+ */
+export function compareHttpApiPathOrder(a, b) {
+    const na = normalizeHttpApiRelativePath(a);
+    const nb = normalizeHttpApiRelativePath(b);
+    return na.localeCompare(nb, "en");
+}
+/**
+ * Sorts an array of relative paths in deterministic API discovery order.
+ */
+export function sortHttpApiPaths(paths) {
+    return [...paths].sort(compareHttpApiPathOrder);
+}

package/dist/internal/httpapiId.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse and resolve `api:` virtual module IDs (router-plugin semantics).
+ * Used by HttpApi virtual module plugin for target-directory resolution.
+ */
+export declare const HTTPAPI_VIRTUAL_MODULE_PREFIX = "api:";
+export type ParseHttpApiVirtualModuleIdResult = {
+    readonly ok: true;
+    readonly relativeDirectory: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Parses an `api:./<directory>` (or `api:<directory>`) ID.
+ * Normalizes bare directory to `./<directory>`.
+ */
+export declare function parseHttpApiVirtualModuleId(id: string, prefix?: string): ParseHttpApiVirtualModuleIdResult;
+export type ResolveHttpApiTargetDirectoryResult = {
+    readonly ok: true;
+    readonly targetDirectory: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Resolves the target directory for an `api:` ID relative to the importer.
+ * Rejects paths that escape the importer base directory.
+ */
+export declare function resolveHttpApiTargetDirectory(id: string, importer: string, prefix?: string): ResolveHttpApiTargetDirectoryResult;
+//# sourceMappingURL=httpapiId.d.ts.map