07-reliability-rate-limits-and-version-fallbacks.md

layout	default
title	Chapter 7: Reliability, Rate Limits, and Version Fallbacks
nav_order	7
parent	OpenSrc Tutorial

Chapter 7: Reliability, Rate Limits, and Version Fallbacks

Welcome to Chapter 7: Reliability, Rate Limits, and Version Fallbacks. In this part of OpenSrc Tutorial: Deep Source Context for Coding Agents, you will build an intuitive mental model first, then move into concrete implementation details and practical production tradeoffs.

Real-world source fetching must account for imperfect metadata, missing tags, and API rate limits.

Built-In Fallback Patterns

• if exact tag is missing, clone default branch with warning
• if package repo metadata is missing, return explicit error
• if host APIs rate-limit requests, surface actionable failures

Reliability Practices

1. pin critical imports to explicit versions where possible
2. cache fetched sources in CI workspace artifacts for repeatability
3. monitor for registry/API availability issues in automation jobs

Source References

• Git clone fallback behavior
• GitHub/GitLab repo resolution behavior

Summary

You now understand how OpenSrc behaves under common failure modes and how to design safer workflows around them.

Next: Chapter 8: Team Operations and Governance

Source Code Walkthrough

src/commands/clean.ts

The CleanOptions interface in src/commands/clean.ts handles a key part of this chapter's functionality:

import type { Registry } from "../types.js";

export interface CleanOptions {
  cwd?: string;
  /** Only clean packages (all registries) */
  packages?: boolean;
  /** Only clean repos */
  repos?: boolean;
  /** Only clean specific registry */
  registry?: Registry;
}

/**
 * Remove all fetched packages and/or repositories
 */
export async function cleanCommand(options: CleanOptions = {}): Promise<void> {
  const cwd = options.cwd || process.cwd();
  const cleanPackages =
    options.packages || (!options.packages && !options.repos);
  const cleanRepos =
    options.repos || (!options.packages && !options.repos && !options.registry);

  let packagesRemoved = 0;
  let reposRemoved = 0;

  // Get current sources
  const sources = await listSources(cwd);

  // Remaining after clean
  let remainingPackages: PackageEntry[] = [...sources.packages];
  let remainingRepos: RepoEntry[] = [...sources.repos];

This interface is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.

src/lib/tsconfig.ts

The hasTsConfig function in src/lib/tsconfig.ts handles a key part of this chapter's functionality:

 * Check if tsconfig.json exists
 */
export function hasTsConfig(cwd: string = process.cwd()): boolean {
  return existsSync(join(cwd, "tsconfig.json"));
}

/**
 * Check if tsconfig.json already excludes opensrc/
 */
export async function hasOpensrcExclude(
  cwd: string = process.cwd(),
): Promise<boolean> {
  const tsconfigPath = join(cwd, "tsconfig.json");

  if (!existsSync(tsconfigPath)) {
    return false;
  }

  try {
    const content = await readFile(tsconfigPath, "utf-8");
    const config = JSON.parse(content) as TsConfig;

    if (!config.exclude) {
      return false;
    }

    return config.exclude.some(
      (entry) =>
        entry === OPENSRC_DIR ||
        entry === `${OPENSRC_DIR}/` ||
        entry === `./${OPENSRC_DIR}`,
    );

This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.

src/lib/tsconfig.ts

The hasOpensrcExclude function in src/lib/tsconfig.ts handles a key part of this chapter's functionality:

 * Check if tsconfig.json already excludes opensrc/
 */
export async function hasOpensrcExclude(
  cwd: string = process.cwd(),
): Promise<boolean> {
  const tsconfigPath = join(cwd, "tsconfig.json");

  if (!existsSync(tsconfigPath)) {
    return false;
  }

  try {
    const content = await readFile(tsconfigPath, "utf-8");
    const config = JSON.parse(content) as TsConfig;

    if (!config.exclude) {
      return false;
    }

    return config.exclude.some(
      (entry) =>
        entry === OPENSRC_DIR ||
        entry === `${OPENSRC_DIR}/` ||
        entry === `./${OPENSRC_DIR}`,
    );
  } catch {
    return false;
  }
}

/**
 * Add opensrc/ to tsconfig.json exclude array

This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.

src/lib/tsconfig.ts

The ensureTsconfigExclude function in src/lib/tsconfig.ts handles a key part of this chapter's functionality:

 * Add opensrc/ to tsconfig.json exclude array
 */
export async function ensureTsconfigExclude(
  cwd: string = process.cwd(),
): Promise<boolean> {
  const tsconfigPath = join(cwd, "tsconfig.json");

  if (!existsSync(tsconfigPath)) {
    return false;
  }

  // Already excluded
  if (await hasOpensrcExclude(cwd)) {
    return false;
  }

  try {
    const content = await readFile(tsconfigPath, "utf-8");
    const config = JSON.parse(content) as TsConfig;

    if (!config.exclude) {
      config.exclude = [];
    }

    config.exclude.push(OPENSRC_DIR);

    // Preserve formatting by using 2-space indent (most common for tsconfig)
    await writeFile(
      tsconfigPath,
      JSON.stringify(config, null, 2) + "\n",
      "utf-8",
    );

This function is important because it defines how OpenSrc Tutorial: Deep Source Context for Coding Agents implements the patterns covered in this chapter.

How These Components Connect

flowchart TD
    A[CleanOptions]
    B[hasTsConfig]
    C[hasOpensrcExclude]
    D[ensureTsconfigExclude]
    E[TsConfig]
    A --> B
    B --> C
    C --> D
    D --> E

Loading