@http-forge/core 0.4.2 → 0.4.4

package/dist/infrastructure/collection/collection-service.d.ts

@@ -22,6 +22,8 @@ export declare class CollectionService implements ICollectionService {
     private collections;
     private fileWatcher?;
     private loader;
+    /** Debounce timer for coalescing rapid file-watcher change events */
+    private debounceTimer;
     /**
      * In-memory Local Values for collection variables (not persisted)
      */

package/dist/infrastructure/collection/folder-collection-store.d.ts

@@ -49,6 +49,15 @@ export declare class FolderCollectionStore implements ICollectionStore {
      * Ensure collections directory exists
      */
     private ensureDirectory;
+    /**
+     * Read and parse a JSON metadata file, tolerating transient partial/empty reads.
+     *
+     * While another process writes files (e.g. importing a collection), a file watcher may
+     * trigger a load before the write completes, yielding empty or truncated content. Such
+     * cases are transient and expected, so they are skipped silently. Genuinely malformed
+     * (non-empty, complete) JSON is still reported.
+     */
+    private readJsonFileSafe;
     /**
      * Load all collections from disk
      */

package/dist/runtime/direct-execution.d.ts

@@ -26,9 +26,11 @@ export declare function runCollection(options: RunCollectionOptions): Promise<un
  * to `options.folderPath` (recursively by default). Returns the same result
  * shape as a collection run.
  */
-export declare function runFolder(options: RunCollectionOptions & {
+export declare function runFolder(options: RunCollectionOptions & ({
     folderPath: string;
-}): Promise<unknown>;
+} | {
+    folderRef: string;
+})): Promise<unknown>;
 /**
  * Execute a test suite without MCP server overhead.
  * Returns typed result; never calls process.exit.

package/dist/runtime/ref-resolver.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Reference Resolver
+ *
+ * Resolves user-supplied collection / folder / request references that may be
+ * an id, a slug, or a display name. Resolution proceeds by tier in order
+ * (id -> slug -> name) and stops at the first tier that yields a match.
+ *
+ * - id   : exact match against the immutable, canonical `id`.
+ * - slug : `generateSlug(name)` computed with sibling-ordered de-duplication
+ *          (mirrors the on-disk directory/file naming).
+ * - name : case-insensitive match against the display `name`.
+ *
+ * A name (and, defensively, a slug) can match more than one sibling; when that
+ * happens an {@link AmbiguousRefError} is thrown carrying the candidate list so
+ * callers can present a clear disambiguation message instead of silently
+ * picking one.
+ *
+ * Used by the direct-execution run APIs to let the CLI address things with a
+ * single flag per concept.
+ */
+import type { Collection, CollectionRequestItem } from '../types/collection';
+/** Tier that produced a successful match. */
+export type RefTier = 'id' | 'slug' | 'name';
+/** Kind of reference being resolved (used for messaging). */
+export type RefKind = 'collection' | 'folder' | 'request';
+/** A candidate item surfaced when a reference is ambiguous. */
+export interface RefCandidate {
+    id: string;
+    name: string;
+    /** Human-readable location (e.g. folder path) for disambiguation. */
+    path: string;
+}
+/** Information about how a reference was resolved (for transparency/logging). */
+export interface ResolutionInfo {
+    kind: RefKind;
+    value: string;
+    tier: RefTier;
+    id: string;
+    path?: string;
+}
+/**
+ * Thrown when a reference value matches multiple items within the same scope.
+ */
+export declare class AmbiguousRefError extends Error {
+    readonly kind: RefKind;
+    readonly value: string;
+    readonly candidates: RefCandidate[];
+    constructor(kind: RefKind, value: string, candidates: RefCandidate[]);
+}
+/**
+ * Resolve a collection reference (id, slug, or name) among all collections.
+ */
+export declare function resolveCollectionRef(collections: Collection[], value: string): {
+    collection: Collection;
+    tier: RefTier;
+};
+/**
+ * Resolve a slash-separated folder reference into the folder-name path expected
+ * by the collection runner. Each segment is resolved id -> slug -> name against
+ * the folders at that level of the tree.
+ *
+ * @returns the resolved folder path (folder names joined by '/') and the tier
+ *   that matched each segment.
+ */
+export declare function resolveFolderRef(collection: Collection, slashPath: string): {
+    folderPath: string;
+    tiers: RefTier[];
+};
+/**
+ * Resolve a request reference (id, slug, or name) to a request id.
+ *
+ * When `folderPath` (folder names joined by '/') is provided, the search is
+ * scoped to that folder's subtree (recursively); otherwise the whole collection
+ * is searched. Ambiguous matches throw {@link AmbiguousRefError}.
+ */
+export declare function resolveRequestRef(collection: Collection, value: string, folderPath?: string): {
+    request: CollectionRequestItem;
+    tier: RefTier;
+    folderPath: string;
+};

package/dist/runtime/runtime-contracts.d.ts

@@ -9,6 +9,7 @@
  * 2. Direct execution: runRequest/runCollection/runSuite without MCP
  * 3. CLI: subcommands that use modes 1 and 2
  */
+import type { ResolutionInfo } from './ref-resolver';
 /**
  * Configuration for creating an embeddable MCP runtime instance.
  */
@@ -47,10 +48,27 @@ export declare function createMcpRuntime(options: McpRuntimeOptions): Promise<Mc
 export interface RunRequestOptions {
     /** Workspace root folder path */
     workspaceFolder: string;
-    /** Collection ID containing the request */
-    collectionId: string;
-    /** Request ID to execute */
-    requestId: string;
+    /** Collection ID containing the request (exact id). */
+    collectionId?: string;
+    /** Request ID to execute (exact id). */
+    requestId?: string;
+    /**
+     * Collection reference resolved by tier id -> slug -> name. Used when an
+     * exact `collectionId` is not provided.
+     */
+    collectionRef?: string;
+    /**
+     * Request reference resolved by tier id -> slug -> name. Used when an exact
+     * `requestId` is not provided. Scoped to `folderRef` when that is provided.
+     */
+    requestRef?: string;
+    /**
+     * Optional folder reference (slash-separated id/slug/name segments) that
+     * scopes request resolution to that folder's subtree.
+     */
+    folderRef?: string;
+    /** Called for each reference resolved, for transparency/logging. */
+    onResolve?: (info: ResolutionInfo) => void;
     /** Environment name (defaults to currently selected) */
     environment?: string;
     /** Extra variables to inject into execution */
@@ -70,8 +88,20 @@ export interface RunRequestOptions {
 export interface RunCollectionOptions {
     /** Workspace root folder path */
     workspaceFolder: string;
-    /** Collection ID to execute */
-    collectionId: string;
+    /** Collection ID to execute (exact id). */
+    collectionId?: string;
+    /**
+     * Collection reference resolved by tier id -> slug -> name. Used when an
+     * exact `collectionId` is not provided.
+     */
+    collectionRef?: string;
+    /**
+     * Folder reference (slash-separated id/slug/name segments) resolved to a
+     * folder path. Used when an exact `folderPath` is not provided.
+     */
+    folderRef?: string;
+    /** Called for each reference resolved, for transparency/logging. */
+    onResolve?: (info: ResolutionInfo) => void;
     /** Environment name (defaults to currently selected) */
     environment?: string;
     /** Extra variables injected into every request */
@@ -130,12 +160,16 @@ export declare function runRequest(options: RunRequestOptions): Promise<unknown>
 export declare function runCollection(options: RunCollectionOptions): Promise<unknown>;
 /**
  * Execute the requests under a specific folder of a collection without MCP
- * server. Thin wrapper over {@link runCollection} scoped to `folderPath`
- * (recursively by default). Returns the same result shape as a collection run.
+ * server. Thin wrapper over {@link runCollection} scoped to a folder
+ * (recursively by default). The folder may be given as `folderPath` (folder
+ * names joined by '/') or `folderRef` (slash-separated id/slug/name segments).
+ * Returns the same result shape as a collection run.
  */
-export declare function runFolder(options: RunCollectionOptions & {
+export declare function runFolder(options: RunCollectionOptions & ({
     folderPath: string;
-}): Promise<unknown>;
+} | {
+    folderRef: string;
+})): Promise<unknown>;
 /**
  * Execute a test suite directly without MCP server.
  * Returns typed result object; never calls process.exit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@http-forge/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Headless HTTP testing engine with Postman collection support, dynamic variables, and script-based automation.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",