Skip to content

list-bundles.md

Latest commit

 

History

History
224 lines (172 loc) · 8.84 KB

list-bundles.md

File metadata and controls

224 lines (172 loc) · 8.84 KB

logicstamp_list_bundles

STEP 2 of the LogicStamp MCP workflow. Call this after logicstamp_refresh_snapshot to see what components are available.

Overview

logicstamp_list_bundles lists all available ROOT component bundles in a snapshot. This command must be called after logicstamp_refresh_snapshot to discover what components are available in your codebase.

The command returns bundle descriptors with component names, file paths, bundle paths (for use in logicstamp_read_bundle), and token estimates. You can filter bundles by directory using the folderPrefix parameter.

⚠️ IMPORTANT: Root vs Dependencies

  • This command only lists ROOT components - Components that have their own bundles (entry points)
  • Dependencies are NOT listed here - Components imported by root components appear in bundle.graph.nodes[] of the root that imports them, not as separate root bundles
  • If a component isn't in this list, it's a dependency. To find it:
    1. Read bundles that might import it (check bundle.graph.nodes[] for the dependency contract)
    2. Search source code to find which root component imports it
    3. Check bundles in the same folder (dependencies are typically co-located)

Important: You MUST call this before reading bundles - it tells you which bundlePath values to use in logicstamp_read_bundle.

When to Use

  • After creating a snapshot - Discover what components are available
  • Exploring a codebase - See all components organized by folder
  • Filtering by directory - Use folderPrefix to focus on specific parts of the codebase
  • Token budgeting - Check token estimates before loading bundles

Parameters

snapshotId (required)

  • Type: string
  • Description: The snapshot ID returned from logicstamp_refresh_snapshot. This identifies which snapshot to list bundles from.

folderPrefix (optional)

  • Type: string

  • Description: Filter bundles by folder path. Only bundles from folders whose path starts with this prefix will be returned.

    Examples:

    • "src/components" - Only bundles from src/components and subdirectories
    • "src/pages" - Only bundles from src/pages and subdirectories
    • "src/utils" - Only bundles from src/utils and subdirectories

Output

Returns a ListBundlesOutput object with:

snapshotId

  • Type: string
  • Description: The snapshot ID that was queried

totalBundles

  • Type: number
  • Description: Total number of bundles found (after filtering by folderPrefix if provided)

bundles

  • Type: BundleDescriptor[]

  • Description: Array of bundle descriptors, each containing:

    • id - Unique bundle identifier (e.g., "bundle_Button")
    • rootComponent - Component name extracted from the file (e.g., "Button")
    • filePath - Relative file path from project root (e.g., "src/components/Button.tsx")
    • folder - Folder path containing this bundle (e.g., "src/components")
    • bundlePath - Use this in logicstamp_read_bundle - Relative path to context.json file (e.g., "src/components/context.json")
    • position - Position in the bundle file (e.g., "1/5" means first of five bundles)
    • bundleHash - Hash identifier for this bundle
    • approxTokens - Approximate token count for this bundle

Example Usage

List All Bundles

{
  "name": "logicstamp_list_bundles",
  "arguments": {
    "snapshotId": "snap_1764033034172_0"
  }
}

Filter by Folder Prefix

{
  "name": "logicstamp_list_bundles",
  "arguments": {
    "snapshotId": "snap_1764033034172_0",
    "folderPrefix": "src/components"
  }
}

This will only return bundles from src/components and its subdirectories.

Example Output

{
  "snapshotId": "snap_1764033034172_0",
  "totalBundles": 45,
  "bundles": [
    {
      "id": "bundle_Button",
      "rootComponent": "Button",
      "filePath": "src/components/Button.tsx",
      "folder": "src/components",
      "bundlePath": "src/components/context.json",
      "position": "1/20",
      "bundleHash": "abc123def456",
      "approxTokens": 2500
    },
    {
      "id": "bundle_Card",
      "rootComponent": "Card",
      "filePath": "src/components/Card.tsx",
      "folder": "src/components",
      "bundlePath": "src/components/context.json",
      "position": "2/20",
      "bundleHash": "def456ghi789",
      "approxTokens": 3200
    },
    {
      "id": "bundle_HomePage",
      "rootComponent": "HomePage",
      "filePath": "src/pages/index.tsx",
      "folder": "src/pages",
      "bundlePath": "src/pages/context.json",
      "position": "1/5",
      "bundleHash": "ghi789jkl012",
      "approxTokens": 8500
    }
  ]
}

Workflow

This is STEP 2 of the LogicStamp MCP workflow:

  1. ✅ Call logicstamp_refresh_snapshot - Creates snapshot (STEP 1)
  2. ✅ Call logicstamp_list_bundles - Lists available bundles (STEP 2 - you are here)
  3. Call logicstamp_read_bundle - Read specific bundles using bundlePath from this output (STEP 3)

Using the Output

The bundlePath field from each bundle descriptor is what you'll use in logicstamp_read_bundle:

{
  "name": "logicstamp_read_bundle",
  "arguments": {
    "snapshotId": "snap_1764033034172_0",
    "bundlePath": "src/components/context.json",
    "rootComponent": "Button"
  }
}

Filtering Strategies

By Component Type

Use folderPrefix to filter by component type:

  • "src/components" - UI components
  • "src/pages" - Page components
  • "src/utils" - Utility modules
  • "src/hooks" - Custom hooks

By Feature Area

Filter by feature directories:

  • "src/features/auth" - Authentication features
  • "src/features/dashboard" - Dashboard features
  • "src/features/profile" - User profile features

By Layer

Filter by architectural layer:

  • "src/components" - Presentation layer
  • "src/services" - Service layer
  • "src/api" - API layer

Important Notes

  • Must call after refresh_snapshot: This command requires a valid snapshotId from logicstamp_refresh_snapshot.
  • bundlePath is required: The bundlePath field from the output is what you use in logicstamp_read_bundle.
  • Multiple bundles per file: A single context.json file can contain multiple bundles. Use rootComponent to specify which one you want.
  • Token estimates: The approxTokens field provides a rough estimate. Actual token counts may vary.
  • ⚠️ Only lists ROOT components: If a component isn't in this list, it's a dependency. Read the bundle of the root component that imports it, then check bundle.graph.nodes[] for the dependency contract.

Related Commands

Watch Mode Behavior

When watch mode (stamp context --watch) is active, this command automatically handles race conditions that can occur when files are being written:

  • Initial delay: Adds a small delay before reading files to let watch mode finish writing:
    • Regular watch mode: 200ms delay
    • Strict watch mode (--strict-watch): 500ms delay (breaking change detection takes slightly longer)
  • Retry logic: If JSON parsing fails (indicating a partially written file), automatically retries up to 3 times with exponential backoff (100ms, 200ms, 400ms)
    • Worst case total wait: ~900ms (200ms initial + retries) for regular watch, ~1.1s for strict watch
  • Transparent operation: This behavior is automatic and only applies when watch mode is active - no performance impact when watch mode is off

⚠️ Important for AI Assistants: These delays are internal to the MCP tool and handled automatically. Do not use sleep() or other delays before calling this tool - the tool handles all necessary waiting internally. When watch mode is active, bundles are already fresh - just call the tool directly.

This ensures reliable file reading even when watch mode is actively regenerating context files, with minimal user-perceived latency.

Error Handling

If the command fails, it will throw an error with a descriptive message. Common errors:

  • Snapshot not found - The snapshotId doesn't exist. Make sure you've called logicstamp_refresh_snapshot first.
  • Invalid snapshot ID - The snapshotId format is incorrect
  • Context files missing - The snapshot's context files are missing or corrupted
  • File read errors - When watch mode is active, retries are attempted automatically. If all retries fail, the error will indicate the file may still be writing

See Also