feat(core): add ctx.dotdir — scoped dot directory API

.changeset/dotdir.md

@@ -0,0 +1,5 @@
+---
+'@kidd-cli/core': minor
+---
+
+Add `ctx.dotdir` — a `DotDirectoryClient` for scoped filesystem operations in CLI dot directories with file protection registry.

packages/core/src/context/create-context.ts

@@ -2,6 +2,7 @@ import * as clack from '@clack/prompts'
 import pc from 'picocolors'
 import type { Colors } from 'picocolors/types'
 
+import { createDotDirectory } from '@/lib/dotdir/index.js'
 import { createLog } from '@/lib/log.js'
 import type { AnyRecord, KiddStore, Merge, ResolvedDirs } from '@/types/index.js'
 
@@ -67,12 +68,15 @@ export function createContext<TArgs extends AnyRecord, TConfig extends AnyRecord
     version: options.meta.version,
   }
 
+  const ctxDotdir = createDotDirectory({ dirs: options.meta.dirs })
+
   // Middleware-augmented properties (e.g. `report`, `auth`) are added at runtime.
   // See `decorateContext` — they are intentionally absent here.
   return {
     args: options.args as CommandContext<TArgs, TConfig>['args'],
     colors: Object.freeze({ ...pc }) as Colors,
     config: options.config as CommandContext<TArgs, TConfig>['config'],
+    dotdir: ctxDotdir,
     fail(message: string, failOptions?: { code?: string; exitCode?: number }): never {
       // Accepted exception: ctx.fail() is typed `never` and caught by the CLI boundary.
       // This is the framework's halt mechanism — the runner catches the thrown ContextError.

packages/core/src/context/types.ts

@@ -1,5 +1,6 @@
 import type { Colors } from 'picocolors/types'
 
+import type { DotDirectory } from '@/lib/dotdir/types.js'
 import type {
   AnyRecord,
   DeepReadonly,
@@ -296,6 +297,12 @@ export interface CommandContext<
    */
   readonly config: DeepReadonly<Merge<CliConfig, TConfig>>
 
+  /**
+   * Dot directory manager for reading/writing files in the CLI's
+   * dot directories (e.g. `~/.myapp/`, `<project>/.myapp/`).
+   */
+  readonly dotdir: DotDirectory
+
   /**
    * Pure string formatters for data serialization (no I/O).
    */

packages/core/src/index.ts

@@ -16,4 +16,10 @@ export type {
 } from './types/index.js'
 export type { Colors } from 'picocolors/types'
 export type { CommandContext, Log, Prompts, Spinner } from './context/types.js'
+export type {
+  DotDirectory,
+  DotDirectoryClient,
+  DotDirectoryError,
+  ProtectedFileEntry,
+} from './lib/dotdir/types.js'
 export type { Report } from './middleware/report/types.js'