@cam5/baby-bird 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -218,6 +218,13 @@ type LlmKind = 'plain' | 'claude';
 interface LlmPreset {
     /** argv; when promptVia is "arg", any "{prompt}" token is replaced with the prompt. */
     command: string[];
+    /**
+     * argv for `bb ask`: an interactive chat about a tour. Tokens: "{context-file}" is the path of a
+     * file holding the tour context (a system prompt), "{context}" is that text inline, and
+     * "{message}" is the user's opening message (argv entries that are only "{message}" are dropped
+     * when there is none).
+     */
+    chatCommand?: string[];
     promptVia?: PromptVia;
     /**
      * "claude": the Claude Code CLI; streaming flags and --json-schema are added
@@ -233,6 +240,7 @@ declare const ConfigSchema: z.ZodObject<{
         preset: z.ZodString;
         presets: z.ZodRecord<z.ZodString, z.ZodObject<{
             command: z.ZodArray<z.ZodString>;
+            chatCommand: z.ZodOptional<z.ZodArray<z.ZodString>>;
             promptVia: z.ZodOptional<z.ZodEnum<{
                 stdin: "stdin";
                 arg: "arg";
@@ -245,6 +253,7 @@ declare const ConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
         args: z.ZodArray<z.ZodString>;
         command: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        chatCommand: z.ZodNullable<z.ZodArray<z.ZodString>>;
         promptVia: z.ZodNullable<z.ZodEnum<{
             stdin: "stdin";
             arg: "arg";
@@ -286,10 +295,6 @@ declare const ConfigSchema: z.ZodObject<{
             auto: "auto";
             always: "always";
         }>;
-        theme: z.ZodEnum<{
-            dark: "dark";
-            light: "light";
-        }>;
     }, z.core.$strip>;
     cache: z.ZodObject<{
         enabled: z.ZodBoolean;
@@ -302,6 +307,7 @@ declare const PartialConfigSchema: z.ZodObject<{
         preset: z.ZodOptional<z.ZodString>;
         presets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             command: z.ZodArray<z.ZodString>;
+            chatCommand: z.ZodOptional<z.ZodArray<z.ZodString>>;
             promptVia: z.ZodOptional<z.ZodEnum<{
                 stdin: "stdin";
                 arg: "arg";
@@ -314,6 +320,7 @@ declare const PartialConfigSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         command: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        chatCommand: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
         promptVia: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             stdin: "stdin";
             arg: "arg";
@@ -355,10 +362,6 @@ declare const PartialConfigSchema: z.ZodObject<{
             auto: "auto";
             always: "always";
         }>>;
-        theme: z.ZodOptional<z.ZodEnum<{
-            dark: "dark";
-            light: "light";
-        }>>;
     }, z.core.$strip>>;
     cache: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -410,6 +413,15 @@ interface ResolvedLlm {
 }
 declare function allPresets(config: Config): Record<string, LlmPreset>;
 declare function resolveLlm(config: Config): ResolvedLlm;
+interface ResolvedChat {
+    /** argv template; see LlmPreset.chatCommand for the tokens. */
+    command: string[];
+    /** Preset name the command came from, or null for llm.chatCommand / a custom command. */
+    preset: string | null;
+    env: Record<string, string>;
+}
+/** The interactive command `bb ask` runs. Errors when neither the preset nor llm.chatCommand provides one. */
+declare function resolveChat(config: Config): ResolvedChat;
 /** Minimal POSIX-ish shell splitting: whitespace separated, single/double quotes, backslash escapes. */
 declare function shellSplit(input: string): string[];
 
@@ -498,12 +510,15 @@ declare function materializeTour(input: MaterializeInput): Tour;
  */
 declare function sliceHunk(hunk: Hunk, range: [number, number] | undefined, maxLines: number): HunkLine[];
 
-interface PromptInput {
+/** The change as gathered from git and the code host. */
+interface ChangeInput {
     source: TourSource;
     branch: string | null;
     diff: ParsedDiff;
     commits: CommitInfo[];
     pullRequest?: PullRequestInfo;
+}
+interface PromptInput extends ChangeInput {
     /** Soft budget for the whole prompt, in bytes. */
     maxBytes: number;
     /** The runner enforces the JSON schema itself (e.g. claude --json-schema); adjusts the output instruction. */
@@ -520,6 +535,14 @@ interface BuiltPrompt {
     truncation: TruncationReport;
 }
 declare function buildPrompt(input: PromptInput): BuiltPrompt;
+/**
+ * The change itself: source, PR text, commit subjects, the file table, and the diff with every
+ * hunk labeled by id. Diffs are shortened biggest-file-first to fit `maxBytes`.
+ */
+declare function renderChange(input: ChangeInput, maxBytes: number): {
+    text: string;
+    truncation: TruncationReport;
+};
 declare function describeSource(source: TourSource, branch: string | null): string;
 
 /** Bump whenever the prompt text or its assembly changes materially; it is part of the cache key. */
@@ -747,6 +770,23 @@ interface TourResult {
 declare function prepareTour(opts: TourOptions): Promise<PreparedTour>;
 declare function generateTour(opts: TourOptions, prepared?: PreparedTour): Promise<TourResult>;
 
+interface ChatContextInput {
+    tour: Tour;
+    /** The change the tour was built from, as gathered by prepareTour. */
+    change: ChangeInput;
+    /** Soft budget for the whole context, in bytes; the tour is always kept and the diff is shortened to fit. */
+    maxBytes: number;
+    /** Where the tour JSON lives on disk, when cached, so a tool-using assistant can open it. */
+    tourPath?: string | null;
+}
+interface ChatContext {
+    /** Markdown meant for a system prompt: framing, the tour, then the change and its diff. */
+    text: string;
+    truncation: TruncationReport;
+}
+/** The text `bb ask` hands to the chat command as context. */
+declare function buildChatContext(input: ChatContextInput): ChatContext;
+
 interface CollectOptions {
     cwd: string;
     exclude: string[];
@@ -773,6 +813,44 @@ declare function diffStats(diff: ParsedDiff): {
     deletions: number;
 };
 
+interface ChatArgvInput {
+    command: string[];
+    contextFile: string;
+    context: string;
+    message?: string;
+}
+/** Fill the tokens in a chat command. Entries that are exactly "{message}" are dropped when there is no message. */
+declare function chatArgv(input: ChatArgvInput): string[];
+/** Which tokens a chat command uses, so the caller can warn about a message or context that would go nowhere. */
+declare function chatSlots(command: string[]): {
+    context: boolean;
+    message: boolean;
+};
+interface LaunchChatOptions {
+    /** argv template; see chatArgv for the tokens. */
+    command: string[];
+    /** The system-prompt-like context, written to a temp file for "{context-file}". */
+    context: string;
+    /** Opening message, if any. */
+    message?: string;
+    cwd: string;
+    env?: Record<string, string>;
+    debug?: (msg: string) => void;
+    /** Defaults to the terminal ("inherit"); tests use "ignore". */
+    stdio?: 'inherit' | 'ignore';
+}
+interface ChatOutcome {
+    /** The command's exit code, or 128 + signal number when a signal ended it. */
+    exitCode: number;
+    signal: NodeJS.Signals | null;
+}
+/**
+ * Run an interactive chat command in the foreground, attached to this terminal, and resolve when it
+ * exits. Ctrl+C reaches the child through the terminal, so bb ignores SIGINT itself while the chat
+ * runs; SIGTERM and SIGHUP are forwarded.
+ */
+declare function launchChat(opts: LaunchChatOptions): Promise<ChatOutcome>;
+
 /**
  * JSON Schema for the model's answer, handed to `claude --json-schema` so the
  * CLI enforces the shape itself. Kept deliberately simple (no tuples, no
@@ -855,10 +933,8 @@ interface RenderOptions {
     section?: number;
     /** Whether the tour came from the cache, for the header note. */
     fromCache?: boolean;
-    /** Language-aware token colors in excerpts, layered under add/del background tints. Needs color. */
+    /** Language-aware token colors in excerpts. Needs color. */
     highlight?: boolean;
-    /** Which background tints to use for added/removed lines. */
-    theme?: 'dark' | 'light';
 }
 interface Renderer {
     render(tour: Tour, opts: RenderOptions): string;
@@ -880,4 +956,4 @@ interface PagerOptions {
 /** Write output to stdout, through $PAGER (default `less -RFX`) when it would not fit the screen. */
 declare function writeMaybePaged(output: string, opts: PagerOptions): Promise<void>;
 
-export { BUILTIN_PRESETS, BadLlmOutputError, BbError, type BuiltPrompt, type CacheEntry, ClaudeStreamParser, CliRenderer, type CodeHost, type CommandKind, CommandProvider, type CommitInfo, type CompleteOptions, type Config, ConfigError, type ConfigLayer, ConfigSchema, DEFAULT_CONFIG, type DiffFile, type Excerpt, type FileStatus, GhCodeHost, GitError, type Hunk, type HunkLine, type LineType, type LlmEvent, LlmFailedError, type LlmKind, type LlmPreset, type LlmProvider, type LlmTourOutput, LlmTourOutputSchema, type LoadedConfig, NoChangesError, NoCodeHost, NotARepoError, OTHER_CHANGES_TITLE, PROMPT_VERSION, type ParsedDiff, type PartialConfig, PartialConfigSchema, type PreparedTour, type ProgressSink, type PromptInput, type PullRequestInfo, type RangeRequest, type RangeResolvedBy, type RenderOptions, type Renderer, type ResolveOptions, type ResolvedLlm, type ResolvedRange, type Section, TOUR_JSON_SCHEMA, type Tour, TourCache, type TourContext, type TourGenerator, type TourOptions, type TourResult, TourSchema, type TourSource, type TourStats, type TruncationReport, UsageError, type WorkingResolvedBy, allPresets, buildPrompt, collectCommits, collectDiff, createCodeHost, createProvider, currentBranch, deepMerge, defaultCacheDir, describeSource, detectDefaultBranch, diffStats, extractJson, formatIssues, generateTour, gitRoot, loadConfig, materializeTour, noProgress, parseDiff, prepareTour, projectConfigPath, promptHeader, relativeTime, resolveLlm, resolveRange, revParse, shellSplit, sliceHunk, userConfigPath, wrap, writeMaybePaged };
+export { BUILTIN_PRESETS, BadLlmOutputError, BbError, type BuiltPrompt, type CacheEntry, type ChangeInput, type ChatContext, type ChatContextInput, type ChatOutcome, ClaudeStreamParser, CliRenderer, type CodeHost, type CommandKind, CommandProvider, type CommitInfo, type CompleteOptions, type Config, ConfigError, type ConfigLayer, ConfigSchema, DEFAULT_CONFIG, type DiffFile, type Excerpt, type FileStatus, GhCodeHost, GitError, type Hunk, type HunkLine, type LaunchChatOptions, type LineType, type LlmEvent, LlmFailedError, type LlmKind, type LlmPreset, type LlmProvider, type LlmTourOutput, LlmTourOutputSchema, type LoadedConfig, NoChangesError, NoCodeHost, NotARepoError, OTHER_CHANGES_TITLE, PROMPT_VERSION, type ParsedDiff, type PartialConfig, PartialConfigSchema, type PreparedTour, type ProgressSink, type PromptInput, type PullRequestInfo, type RangeRequest, type RangeResolvedBy, type RenderOptions, type Renderer, type ResolveOptions, type ResolvedChat, type ResolvedLlm, type ResolvedRange, type Section, TOUR_JSON_SCHEMA, type Tour, TourCache, type TourContext, type TourGenerator, type TourOptions, type TourResult, TourSchema, type TourSource, type TourStats, type TruncationReport, UsageError, type WorkingResolvedBy, allPresets, buildChatContext, buildPrompt, chatArgv, chatSlots, collectCommits, collectDiff, createCodeHost, createProvider, currentBranch, deepMerge, defaultCacheDir, describeSource, detectDefaultBranch, diffStats, extractJson, formatIssues, generateTour, gitRoot, launchChat, loadConfig, materializeTour, noProgress, parseDiff, prepareTour, projectConfigPath, promptHeader, relativeTime, renderChange, resolveChat, resolveLlm, resolveRange, revParse, shellSplit, sliceHunk, userConfigPath, wrap, writeMaybePaged };

package/dist/index.js

@@ -23,7 +23,10 @@ import {
   TourSchema,
   UsageError,
   allPresets,
+  buildChatContext,
   buildPrompt,
+  chatArgv,
+  chatSlots,
   collectCommits,
   collectDiff,
   createCodeHost,
@@ -38,6 +41,7 @@ import {
   formatIssues,
   generateTour,
   gitRoot,
+  launchChat,
   loadConfig,
   materializeTour,
   noProgress,
@@ -46,6 +50,8 @@ import {
   projectConfigPath,
   promptHeader,
   relativeTime,
+  renderChange,
+  resolveChat,
   resolveLlm,
   resolveRange,
   revParse,
@@ -54,7 +60,7 @@ import {
   userConfigPath,
   wrap,
   writeMaybePaged
-} from "./chunk-7ALXKEST.js";
+} from "./chunk-YI2UL4IC.js";
 export {
   BUILTIN_PRESETS,
   BadLlmOutputError,
@@ -80,7 +86,10 @@ export {
   TourSchema,
   UsageError,
   allPresets,
+  buildChatContext,
   buildPrompt,
+  chatArgv,
+  chatSlots,
   collectCommits,
   collectDiff,
   createCodeHost,
@@ -95,6 +104,7 @@ export {
   formatIssues,
   generateTour,
   gitRoot,
+  launchChat,
   loadConfig,
   materializeTour,
   noProgress,
@@ -103,6 +113,8 @@ export {
   projectConfigPath,
   promptHeader,
   relativeTime,
+  renderChange,
+  resolveChat,
   resolveLlm,
   resolveRange,
   revParse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cam5/baby-bird",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Guided code tours for git changes, on the command line.",
   "license": "MIT",
   "type": "module",