feat(core): add ctx.dotdir API and rename Context to CommandContext

[zrosenbauer]

Summary

• ctx.dotdir — New DotDirectoryClient on the command context providing scoped filesystem operations (read, write, readJson, writeJson, exists, remove, ensure, path) for CLI dot directories (~/.myapp/, <project>/.myapp/). Includes a protection registry so middleware can guard sensitive files — auth middleware now protects auth.json by default.
• Context → CommandContext — Renamed the core interface for clearer delineation between command handlers and screen components. Module augmentation declarations (auth, report, icons) updated accordingly.
• useCommandContext → useScreenContext — Renamed the React hook to match ScreenContext naming.

Breaking changes

• Context type is now CommandContext — update imports and declare module blocks
• useCommandContext() hook is now useScreenContext()
• No backwards-compatibility aliases

Test plan

• pnpm check passes (typecheck + lint + format) — 0 errors
• pnpm test passes — 780/780 tests across 58 test files
• New dotdir tests: protection.test.ts, create-dot-directory.test.ts, create-dot-directory-client.test.ts
• Verify auth middleware still works — auth.json is now protected, existing auth code doesn't use ctx.dotdir yet so no behavioral change

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
oss-kidd	Ignored	Preview	Mar 24, 2026 10:24pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 9b97280

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@kidd-cli/core	Minor
@kidd-cli/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR performs a comprehensive refactoring that renames the Context interface to CommandContext across the entire codebase and introduces a new dot-directory client subsystem for scoped file management. The refactoring propagates the type change through command handlers, middleware, runtime execution, UI hooks, and documentation. In parallel, a new dotdir property is added to the context, providing methods for reading, writing, and protecting files in global and local scopes via a DotDirectoryClient. The UI hook useCommandContext is renamed to useScreenContext. All middleware module augmentations are updated to attach properties to CommandContext instead of Context.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The review demand stems from the high file count (60+ files) but with predominantly repetitive, mechanical type substitutions (Context → CommandContext). The novel complexity is concentrated in the new dotdir implementation (protection registry, directory client factory, filesystem operations with Result error types), which requires verification that the error handling paths are correct and the protection mechanism properly enforces file access controls. The type threading through runtime, middleware chains, and module augmentations is straightforward and can be spot-checked. Existing command logic remains intact.

Possibly related PRs

• feat(core): replace screen hooks with useCommandContext() #100 — Modifies overlapping screen/context API changes including ScreenContext/ScreenRenderFn types and UI provider naming conventions
• feat(core): React/Ink render support and UI components #91 — Adds screen() UI provider and render support, directly affected by the useCommandContext → useScreenContext hook rename
• feat(packages/core): add icons middleware #56 — Updates icons middleware module augmentation and types from Context to CommandContext

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the two main changes: adding ctx.dotdir API and renaming Context to CommandContext.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, covering all major features, breaking changes, and test results.
Docstring Coverage	✅ Passed	Docstring coverage is 82.93% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/dotdir-and-context-rename

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/dotdir-and-context-rename

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}