README
¶
codingcontext
Go package for dynamically assembling context for AI coding agents.
Installation
go get github.com/kitproj/coding-context-cli/pkg/codingcontext
Usage
Basic Example
package main
import (
"context"
"fmt"
"log/slog"
"os"
"github.com/kitproj/coding-context-cli/pkg/codingcontext"
)
func main() {
// Create a new context with options
ctx := codingcontext.New(
codingcontext.WithWorkDir("."),
codingcontext.WithParams(codingcontext.Params{
"issue_number": "123",
"feature": "authentication",
}),
codingcontext.WithLogger(slog.New(slog.NewTextHandler(os.Stderr, nil))),
)
// Run a task and get the result
result, err := ctx.Run(context.Background(), "my-task")
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
// Access the assembled context
for _, rule := range result.Rules {
fmt.Println(rule.Content)
}
fmt.Println(result.Task.Content)
}
}
Advanced Example
package main
import (
"context"
"fmt"
"log/slog"
"os"
"github.com/kitproj/coding-context-cli/pkg/codingcontext"
)
func main() {
// Create selectors for filtering rules
selectors := make(codingcontext.Selectors)
selectors.SetValue("language", "go")
selectors.SetValue("stage", "implementation")
// Create context with all options
ctx := codingcontext.New(
codingcontext.WithWorkDir("."),
codingcontext.WithResume(false),
codingcontext.WithParams(codingcontext.Params{
"issue_number": "123",
}),
codingcontext.WithSelectors(selectors),
codingcontext.WithRemotePaths([]string{
"https://github.com/org/repo//path/to/rules",
}),
codingcontext.WithEmitTaskFrontmatter(true),
codingcontext.WithLogger(slog.New(slog.NewTextHandler(os.Stderr, nil))),
)
// Run the task and get the result
result, err := ctx.Run(context.Background(), "implement-feature")
if err != nil {
fmt.Fprintf(os.Stderr, "Error: %v\n", err)
os.Exit(1)
}
// Process the result
fmt.Printf("Task: %s\n", result.Task.Content)
fmt.Printf("Rules found: %d\n", len(result.Rules))
// Access task metadata
if taskName, ok := result.Task.FrontMatter["task_name"]; ok {
fmt.Printf("Task name from frontmatter: %s\n", taskName)
}
}
API Reference
Types
Context
The main type for assembling context.
Result
Result holds the assembled context from running a task:
Rules []Markdown- List of included rule filesTask Markdown- Task file with frontmatter and content
Markdown
Represents a markdown file with frontmatter and content:
Path string- Path to the markdown fileFrontMatter FrontMatter- Parsed YAML frontmatterContent string- Expanded content of the markdownTokens int- Estimated token count
Params
Map of parameter key-value pairs for template substitution.
Selectors
Map structure for filtering rules based on frontmatter metadata.
FrontMatter
Map representing parsed YAML frontmatter from markdown files.
Functions
New(opts ...Option) *Context
Creates a new Context with the given options.
Options:
WithWorkDir(dir string)- Set the working directoryWithResume(resume bool)- Enable resume modeWithParams(params Params)- Set parametersWithSelectors(selectors Selectors)- Set selectors for filteringWithRemotePaths(paths []string)- Set remote directories to downloadWithEmitTaskFrontmatter(emit bool)- Enable task frontmatter inclusion in resultWithLogger(logger *slog.Logger)- Set logger
(*Context) Run(ctx context.Context, taskName string) (*Result, error)
Executes the context assembly for the given task name and returns the assembled result structure with rule and task markdown files (including frontmatter and content).
ParseMarkdownFile(path string, frontmatter any) (string, error)
Parses a markdown file into frontmatter and content.
AllTaskSearchPaths(baseDir, homeDir string) []string
Returns the standard search paths for task files. baseDir is the working directory to resolve relative paths from.
AllRulePaths(baseDir, homeDir string) []string
Returns the standard search paths for rule files. baseDir is the working directory to resolve relative paths from.
See Also
Documentation
¶
Index ¶
- func AllRulePaths(baseDir, homeDir string) []string
- func AllTaskSearchPaths(baseDir, homeDir string) []string
- func DownloadedRulePaths(dir string) []string
- func DownloadedTaskSearchPaths(dir string) []string
- func ParseMarkdownFile(path string, frontmatter any) (string, error)
- type Context
- type FrontMatter
- type Markdown
- type Option
- type Params
- type Result
- type Selectors
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AllRulePaths ¶
AllRulePaths returns the standard search paths for rule files baseDir is the working directory to resolve relative paths from
func AllTaskSearchPaths ¶
AllTaskSearchPaths returns the standard search paths for task files baseDir is the working directory to resolve relative paths from
func DownloadedRulePaths ¶
DownloadedRulePaths returns the search paths for rule files in downloaded directories
func DownloadedTaskSearchPaths ¶
DownloadedTaskSearchPaths returns the search paths for task files in downloaded directories
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context holds the configuration and state for assembling coding context
type FrontMatter ¶
FrontMatter represents parsed YAML frontmatter from markdown files
type Markdown ¶
type Markdown struct {
Path string // Path to the markdown file
FrontMatter FrontMatter // Parsed YAML frontmatter
Content string // Expanded content of the markdown
Tokens int // Estimated token count
}
Markdown represents a markdown file with frontmatter and content
func (*Markdown) BootstrapPath ¶
BootstrapPath returns the path to the bootstrap script for this markdown file, if it exists. Returns empty string if the path is empty.
type Option ¶
type Option func(*Context)
Option is a functional option for configuring a Context
func WithEmitTaskFrontmatter ¶
WithEmitTaskFrontmatter enables task frontmatter emission
func WithRemotePaths ¶
WithRemotePaths sets the remote paths
func WithSelectors ¶
WithSelectors sets the selectors
type Params ¶
Params is a map of parameter key-value pairs for template substitution
type Result ¶
type Result struct {
Rules []Markdown // List of included rule files
Task Markdown // Task file with frontmatter and content
}
Result holds the assembled context from running a task
type Selectors ¶
Selectors stores selector key-value pairs where values are stored in inner maps Multiple values for the same key use OR logic (match any value in the inner map) Each value can be represented exactly once per key
func (*Selectors) GetValue ¶
GetValue returns true if the given value exists in the inner map for the given key. Returns false if the key doesn't exist or the value is not present.
func (*Selectors) MatchesIncludes ¶
func (includes *Selectors) MatchesIncludes(frontmatter FrontMatter) bool
MatchesIncludes returns true if the frontmatter matches all include selectors If a key doesn't exist in frontmatter, it's allowed Multiple values for the same key use OR logic (matches if frontmatter value is in the inner map)
Source Files