Documentation
¶
Index ¶
- Constants
- Variables
- func AddProjectFlag(cmd *cobra.Command)
- func EffectiveLimit(flag, def int) int
- func FailContract(cmd *cobra.Command, code, message string) error
- func FailInvalidOrderBy(cmd *cobra.Command) error
- func FailProjectRequired(cmd *cobra.Command) error
- func FilterCanaryTokens(content []byte) []byte
- func GetAvailablePrompts() ([]string, error)
- func GuardContract(cmd *cobra.Command, err error) error
- func LoadProjectConfig() (*config.ProjectConfig, error)
- func LoadPrompt(promptArg string) (string, error)
- func OpenIndexRO(cmd *cobra.Command, dbPath string) (*storage.DB, error)
- func ReadEmbeddedFile(path string) ([]byte, error)
- func ReadProjectID(cmd *cobra.Command) string
- func ValidatePromptArg(promptArg string) error
- func WriteProjectID(cmd *cobra.Command, root string) (string, error)
Constants ¶
const ExitCodeContract = contract.ExitCode
ExitCodeContract is the exit status a contract refusal uses. It is distinct from 1 so a caller can tell "canary refused because you asked for something it will not do" from "the command failed".
const ProjectFlag = "project"
ProjectFlag is the flag every project-scoped command registers.
Variables ¶
var ErrContractFailed = contract.ErrFailed
ErrContractFailed is the sentinel a command returns once it has already printed its contract line. main() maps it to ExitCodeContract; nothing prints it, because the JSON line on stdout is the entire message.
var ErrNoIndex = errors.New("no index; run 'canary index'")
ErrNoIndex is what a read-only command returns when the project has never been indexed. It names the fix rather than creating the database itself: a read must never have a write side effect.
Functions ¶
func AddProjectFlag ¶ added in v0.3.3
AddProjectFlag registers --project on cmd.
func EffectiveLimit ¶
CANARY: REQ=ENG-4323; FEATURE="ContextCaps"; ASPECT=CLI; STATUS=TESTED; TEST=TestCANARY_CBIN_205_EffectiveLimit; UPDATED=2026-08-31 EffectiveLimit maps CLI --limit semantics (0/unset => def, -1 => unlimited) to the storage layer's convention (0 => unlimited). Defaults are deliberately small to protect agent context; callers pass -1 to explicitly request everything.
func FailContract ¶ added in v0.3.3
FailContract prints the one-line JSON contract on stdout and returns ErrContractFailed. Nothing else may reach stdout on that path: the caller is a program parsing the line, and a stray banner would corrupt it.
It returns rather than calling os.Exit because it runs inside RunE, where exiting skips every deferred database Close and temp-file cleanup between here and main. cmd is silenced so cobra adds neither the error nor the command's usage block to the output.
func FailInvalidOrderBy ¶ added in v0.3.3
FailInvalidOrderBy emits the INVALID_ORDER_BY contract.
func FailProjectRequired ¶ added in v0.3.3
FailProjectRequired emits the PROJECT_REQUIRED contract.
func FilterCanaryTokens ¶
FilterCanaryTokens removes CANARY tokens with OWNER=canary from file content This strips out CANARY CLI internal tracking tokens when copying templates to user projects
func GetAvailablePrompts ¶
GetAvailablePrompts returns the list of available embedded prompt names (command prompts from prompts/commands/* and system prompts from prompts/sys/*).
func GuardContract ¶ added in v0.3.3
GuardContract turns a storage contract error into its machine-readable refusal on stdout (ErrContractFailed, exit 2) and passes every other error through unchanged. It exists so the two contracts are emitted identically wherever they can arise, rather than being re-spelled at each call site.
func LoadProjectConfig ¶
func LoadProjectConfig() (*config.ProjectConfig, error)
LoadProjectConfig loads the .canary/project.yaml configuration
func LoadPrompt ¶
LoadPrompt loads a custom prompt from file or embedded prompt name. This is a stub implementation that will be expanded in the future to support: - Loading prompts from embedded FS - Loading prompts from filesystem - Template variable substitution - Prompt validation and caching
func OpenIndexRO ¶ added in v0.3.3
OpenIndexRO opens the token index read-only for cmd. A missing index yields ErrNoIndex; nothing is created on any path.
cmd may be nil. When it is not, usage output is suppressed for this error: "no index; run 'canary index'" is a state problem, and answering it with the command's full flag list buries the one line that matters.
func ReadEmbeddedFile ¶
ReadEmbeddedFile safely reads a file from the embedded filesystem It tries with and without the "base/" prefix to handle different embed scenarios
func ReadProjectID ¶ added in v0.3.3
ReadProjectID resolves the project a *reading* command scopes to:
--project <id> -> that id otherwise -> "" (unscoped)
The unscoped default is deliberate, and it is not the same as guessing a name. A database holding one project answers an unscoped query exactly as it always did; a database holding several refuses with storage.ErrProjectRequired and names --project as the fix. Defaulting the scope to the configured project.key instead would be worse than useless: it answers no question a single-project database could not already answer, and the day someone adds a key to project.yaml every row indexed before that change would silently vanish from every read.
It reads one flag off cmd and cannot fail, so it returns no error: an error return every caller was obliged to check and no caller could ever see is noise that hides the checks that matter. It takes no root either -- unlike WriteProjectID it never consults project.yaml.
func ValidatePromptArg ¶
ValidatePromptArg validates a prompt argument format
func WriteProjectID ¶ added in v0.3.3
WriteProjectID resolves the project a *writing* command stores rows under. A writer must name a project -- a row with no identity is reachable by no scoped read and no scoped delete -- so an unconfigured repository resolves to config's "default", the same value migration 000007 backfills onto pre-scoping rows.
Types ¶
This section is empty.
Source Files