Change a Web-Development CLI Made of JavaScript and Native Code in the Right Layer

## Find the Layer That Owns a CLI Behavior and Trace Global and Local Paths Map the request to the component that owns the behavior before editing: - JavaScript or TypeScript entrypoints own high-level local CLI behavior and package exports; - native crates own the standalone global binary, runtime bootstrap, package-manager integration, installers, migrations, and shared process utilities; - the native binding owns the bridge between the local JavaScript CLI and native command implementations; - core packages expose bundled build, test, documentation, and packaging surfaces; - repository tooling owns local registries, build helpers, fixtures, and release support; - documentation and generated project guidance are separate products with different sources. Trace global and local command routes independently when both can implement the same user command. A fix in one path is incomplete if the other path remains inconsistent. Do not edit generated project guidance when the task concerns repository contributor instructions. Prefer canonical architecture and configuration documents over copied explanations. ## Keep Built-In Commands and Task Runner Tasks Separate Distinguish built-in toolchain commands from the task runner. A built-in test, build, lint, or format command may invoke a bundled implementation, while a run command executes a package script or configured task with the same name. Treat package scripts as first-class run targets. Use explicit task configuration only when a task needs dependencies, caching, command configuration, input tracking, or environment tracking. A task name must have one owner. Do not define the same name in both package scripts and tool configuration. Keep task configuration in the current canonical config file; do not reintroduce retired standalone config formats. Keep public test imports on the supported package surface and generate compatibility shims from the owning build script. Do not recreate removed packages or assume an external dependency is a local workspace member. Before changing routing, inspect command help, bundled tool versions, package exports, and the nearest task documentation. ## Pick the Smallest Tests That Fit the Kind of Change Use the smallest validation set that covers the changed behavior: - documentation or agent guidance: verify referenced paths, commands, links, and whitespace; - JavaScript CLI behavior: run the repository check, unit tests, and focused package tests; - native CLI or crate behavior: run native checks, tests, and lints; - command output or interaction design: run focused pseudo-terminal snapshot tests and review the diff; - global CLI behavior: rebuild and install the local global binary, then verify its version and focused commands; - release or packaging behavior: run the release build; - pre-merge integration: bootstrap the CLI, run the full test set, and inspect repository status. Use fix mode only when formatting or lint rewrites are intentionally in scope. For behavior changes, locate the nearest existing test before editing and add coverage in the same area. Do not run broad unrelated suites for documentation-only changes, and do not claim CLI routing is correct from unit tests alone when bundled-tool dispatch is involved. ## Add Pseudo-Terminal Snapshot Tests That Run on Unix and Windows Put new command-line and interactive-flow cases in the repository’s pseudo-terminal snapshot harness. Define each case with explicit argument arrays rather than shell strings. Use the harness helper commands instead of platform-specific core utilities so the same fixture behaves on Unix and Windows. Declare whether a case targets the local CLI, global CLI, or both; local cases require a fresh local distribution build. Snapshot mismatches must fail with a reviewable diff and produce a candidate output file. Update snapshots only through the explicit record mode, then review the recorded output as code before committing it. For command UX changes, test both the focused behavior and its transcript. For install or migration behavior, serve the packed checkout through the repository’s local registry interface rather than bypassing real package-manager behavior. Keep interactive milestones and keystroke steps explicit so failures identify the phase that diverged. ## Follow Each Language's Lint Rules and Change Generated Files Only via Generators For native code, follow the repository lint restrictions, shared output helpers, environment configuration, path handling, and nearby command style. For TypeScript, use the canonical compiler, terminal-output helpers, and repository task configuration. Do not duplicate language rules in contributor guidance when the linter, compiler config, or source reference is authoritative. Treat generated bindings, shims, agent files, distributions, and snapshot outputs as owned artifacts. Change them only through their generator or explicit snapshot acceptance flow. Keep diffs scoped to the requested ownership layer and leave unrelated tracked or untracked files untouched. If a generated file changes unexpectedly, investigate the source or generator instead of patching the derivative. When validating an installed global CLI, use the documented bootstrap path and confirm the resolved version. Do not infer that a package build also refreshed the installed binary. ## Debug by Comparing the Global Native Path with the Local JavaScript Path Start by recording the bundled component versions and inspecting top-level and command-specific help. For routing defects, compare the global native path with the local JavaScript-and-binding path. For configuration defects, compare static extraction with the JavaScript resolver fallback. For package-manager defects, inspect both command-surface and installation layers plus their terminal snapshots. For check, lint, format, type-check, or test defects, validate the end-to-end command. Bundled-tool routing can make isolated package tests pass while user configuration is silently ignored. When a failure depends on local versus global flavor, reproduce both explicitly. When it depends on generated output, rebuild the exact derivative before concluding the source fix is ineffective. Use navigation guidance to find authoritative files; do not let a concise agent guide replace detailed architecture, migration, task, or snapshot documentation.