@http-forge/core 0.4.1 → 0.4.3

package/dist/infrastructure/test-suite/interfaces.d.ts

@@ -147,6 +147,7 @@ export interface ITestSuiteService {
     deleteSuite(id: string): Promise<boolean>;
     duplicateSuite(sourceId: string, newName: string): Promise<TestSuite>;
     createTempSuiteFromCollection(collectionId: string): Promise<TestSuite | undefined>;
+    createTempSuiteFromFolder(collectionId: string, folderPath: string, recursive?: boolean): Promise<TestSuite | undefined>;
     saveTempSuite(suite: TestSuite, name: string): Promise<TestSuite>;
 }
 /**

package/dist/infrastructure/test-suite/test-suite-service.d.ts

@@ -79,6 +79,16 @@ export declare class TestSuiteService implements ITestSuiteService {
      * Create a temporary suite from a collection
      */
     createTempSuiteFromCollection(collectionId: string): Promise<TestSuite | undefined>;
+    /**
+     * Create a temporary suite from a single folder within a collection.
+     *
+     * @param collectionId - the owning collection
+     * @param folderPath - slash-separated folder names (e.g. "Auth/Login")
+     * @param recursive - include requests in nested subfolders (default: true)
+     */
+    createTempSuiteFromFolder(collectionId: string, folderPath: string, recursive?: boolean): Promise<TestSuite | undefined>;
+    /** Convert a folder path into an id-safe slug. */
+    private slugifyFolderPath;
     /**
      * Save a temporary suite as a permanent one
      */

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

@@ -20,6 +20,17 @@ export declare function runRequest(options: RunRequestOptions): Promise<unknown>
  * Returns typed result; never calls process.exit.
  */
 export declare function runCollection(options: RunCollectionOptions): Promise<unknown>;
+/**
+ * Execute the requests under a specific folder of a collection without MCP
+ * server overhead. Thin wrapper over {@link runCollection} that scopes the run
+ * to `options.folderPath` (recursively by default). Returns the same result
+ * shape as a collection run.
+ */
+export declare function runFolder(options: RunCollectionOptions & ({
+    folderPath: string;
+} | {
+    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 */
@@ -84,6 +114,16 @@ export interface RunCollectionOptions {
     delay?: number;
     /** Extra response fields to include: perRequest, failedOnly, consoleOutput */
     include?: string[];
+    /**
+     * Restrict execution to requests under this folder path (slash-separated
+     * folder names, e.g. "Auth/Login"). When omitted, the whole collection runs.
+     */
+    folderPath?: string;
+    /**
+     * When a `folderPath` is provided, include requests in nested subfolders
+     * (default: true). When false, only requests directly in that folder run.
+     */
+    recursive?: boolean;
 }
 /**
  * Options for directly executing a test suite without MCP.
@@ -118,6 +158,18 @@ export declare function runRequest(options: RunRequestOptions): Promise<unknown>
  * Returns typed result object; never calls process.exit.
  */
 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 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 & ({
+    folderPath: string;
+} | {
+    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.1",
+  "version": "0.4.3",
   "description": "Headless HTTP testing engine with Postman collection support, dynamic variables, and script-based automation.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",