protected-files

name	protected-files
description	Zero-dependency bootstrap files that must never import npm packages or SDK code
domain	dependency-safety
confidence	high
source	earned — CLI startup crashes when bootstrap files import SDK code

Context

The CLI (squad-cli) has bootstrap utilities that run before the Squad SDK is loaded. If these files import SDK code (e.g., FSStorageProvider, anything from squad-sdk), the CLI breaks at startup — no helpful error, just a crash.

This skill applies when:

• Touching any file in packages/squad-cli/src/cli/core/
• Running sweeping refactors (e.g., "convert all fs calls to StorageProvider")
• Adding new bootstrap utilities

Protected File List

File	Purpose
packages/squad-cli/src/cli/core/detect-squad-dir.ts	Finds .squad/ directory at startup — runs before SDK init
packages/squad-cli/src/cli/core/errors.ts	Error classes (SquadError, fatal()) — used by all CLI entry points
packages/squad-cli/src/cli/core/gh-cli.ts	GitHub CLI wrapper — uses only node:child_process and node:util
packages/squad-cli/src/cli/core/output.ts	Color/emoji console output — pure ANSI codes, zero imports
packages/squad-cli/src/cli/core/history-split.ts	Separates portable knowledge from project data — pure string logic

Rules

• ❌ NEVER convert these files to use FSStorageProvider, StorageProvider, or any SDK abstraction
• ❌ NEVER add import or require statements referencing packages outside node:* built-ins
• ✅ ONLY use node:fs, node:path, node:child_process, node:util, and other Node.js built-in modules
• ✅ DO check this list before sweeping refactors
• ✅ LOOK for — zero dependencies markers in file headers as a signal

SDK/CLI Package Boundary

The packages/squad-cli/src/cli/core/ directory contains a mix of early-startup bootstrap utilities and later SDK-dependent modules. The protected list above is the authoritative set of zero-dependency bootstrap files. If you need to add SDK imports to another core/ file, verify it is not in the protected list and confirm the SDK is loaded at that point in the startup sequence.

Anti-Patterns

• Converting all fs calls to StorageProvider without checking this list first
• Adding import { X } from '@bradygaster/squad-sdk' to a bootstrap file
• Assuming every file in core/ can safely import SDK code

Adding New Bootstrap Utilities

When adding a new file that runs before SDK init:

1. Add it to the Protected File List table above
2. Write a matching zero-dependency regression test (see detect-squad-dir-zero-deps.test.ts for the pattern)
3. Add — zero dependencies marker in the file header

Regression tests guard these files, but prevention is better than detection.