Zero-dependency bootstrap files that must never import npm packages or SDK code
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:
packages/squad-cli/src/cli/core/fs calls to StorageProvider")| 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 |
FSStorageProvider, StorageProvider, or any SDK abstractionimport or require statements referencing packages outside node:* built-insnode:fs, node:path, node:child_process, node:util, and other Node.js built-in modules— zero dependencies markers in file headers as a signalThe 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.
fs calls to StorageProvider without checking this list firstimport { X } from '@bradygaster/squad-sdk' to a bootstrap filecore/ can safely import SDK codeWhen adding a new file that runs before SDK init:
detect-squad-dir-zero-deps.test.ts for the pattern)— zero dependencies marker in the file headerRegression tests guard these files, but prevention is better than detection.