stdlib

name	stdlib
description	Kukicha stdlib authoring guide — full package table, common usage patterns, security check patterns, common pitfalls, and rules for adding/modifying stdlib packages. Use when working in stdlib/ or reviewing stdlib usage.

stdlib/ — Standard Library

Each package lives in stdlib/<name>/ with:

• <name>.kuki — Kukicha source (types, enums, function signatures, inline implementations)
• <name>.go — Generated by make generate from the .kuki file. Never edit directly.

Packages

Package	Purpose	Key Functions
stdlib/cast	Smart type coercion (any → scalar)	SmartInt, SmartFloat64, SmartBool, SmartString, Atoi, ParseFloat
stdlib/cli	CLI argument parsing with subcommands	New, Version (enables --version), Description, Arg, AddFlag, Action, Run, RunApp, NewCommand, WithCommands, GlobalFlag, BoolGlobalFlag, IntGlobalFlag, GetString, GetBool, GetInt, GetRest, ParseArgs, NewArgs, IsJSON, IsTTY, Respond, Context, Error, Fatal, Info, Success — App/SubcommandDef builder methods: StringFlag, BoolFlag, IntFlag, Short, RestArg, Flag, Arg, Action. Use typed constructors (BoolFlag/IntFlag/StringFlag) instead of Flag when the type is known; use Short to register one-char aliases; use RestArg to collect overflow positionals; use BoolGlobalFlag/IntGlobalFlag for typed global flags.
stdlib/color	ANSI terminal styling. Package-level funcs delegate to a default styler bound to os.Stdout; capability detection delegates to stdlib/term.	NewStyler, Enabled, SetEnabled, Bold, Dim, Italic, Underline, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, BrightRed, BrightGreen, BrightYellow, BrightBlue, BrightMagenta, BrightCyan, BrightWhite, Error (each is also a method on Styler)
stdlib/concurrent	Parallel execution and concurrent map	Parallel, ParallelWithLimit, Map, MapWithLimit, Go
stdlib/crypto	Hashing, HMAC, and secure random (Go stdlib only)	SHA256, SHA256Bytes, HMAC, HMACBytes, RandomToken, RandomBytes, Equal
stdlib/ctx	Context timeout/cancellation helpers	Background, FromContext, WithTimeout, WithDeadline, WithCancel; Type: Handle
stdlib/db	SQL database (raw SQL + struct scanning, zero external deps)	Open, Close, Ping, Query, QueryRow, Exec, ScanAll, ScanOne, ScanRow, CloseRows, Transaction, TransactionWith, TxQuery, TxQueryRow, TxExec, Count, Exists; Types: Pool, Row, Rows, Tx, TxOptions; Enums: IsolationLevel
stdlib/datetime	Named formats, duration helpers, arithmetic, comparison	Format, Parse, Now, Today, AddDays, IsBefore, Unix, Sleep; Constants: ISO8601, RFC3339, Date, Time, DateTime
stdlib/encoding	Base64 and hex encoding/decoding	Base64Encode, Base64Decode, Base64URLEncode, Base64URLDecode, HexEncode, HexDecode
stdlib/env	Typed env vars with onerr	Get, GetOr, GetInt, GetIntOrDefault, GetBool, GetBoolOrDefault, GetFloat, GetList, Set, Unset, IsSet, All
stdlib/errors	Error wrapping and dual-message helpers	Wrap, Opaque, NewPublic, Public
stdlib/fetch	HTTP client (Builder, Auth, Sessions, Safe URL helpers, Retry, Context)	Get, SafeGet, Post, GetCtx, SafeGetCtx, PostCtx, Json, Decode, Text, Bytes, CheckStatus, URLTemplate, URLWithQuery, PathEscape, QueryEscape, New, NewExternal, Header/Timeout/Retry/MaxBodySize/Transport/WithContext/Do, BearerAuth, BasicAuth, FormData, NewSession, DownloadTo
stdlib/files	File I/O operations	Read, ReadBytes, Write, WriteString, Append, AppendString, Exists, IsDir, IsFile, Copy, Move, Delete, DeleteAll, List, ListRecursive, MkDir, MkDirAll, TempFile, TempDir, Size, ModTime, Basename, Dirname, Extension, Join, Abs, UseWith, Watch
stdlib/game	2D game library (kukichalang/game, Ebitengine wrapper, WASM-only)	Window, OnSetup, OnUpdate, OnDraw, Run, Clear, DrawRect, DrawCircle, DrawLine, DrawText, IsKeyDown, IsKeyPressed, MousePosition, MouseClicked, Overlaps, OverlapsCircle, CircleOverlapsRect, MakeColor, Random, RandomFloat, FrameCount
stdlib/git	Git/GitHub operations via gh CLI	ListTags, TagExists, DefaultBranch, CurrentBranch, ReleaseExists, CreateRelease, PreviewRelease, RepoExists, CurrentUser, Clone, CloneShallow
stdlib/html	Component-style HTML with auto-escaping	Render, Escape, Attr, Embed, WriteTo, WriteStatusTo, String, IsEmpty, Join, Map, When, WhenElse; Type: Fragment
stdlib/http	HTTP response/request helpers + security	JSON, JSONStatus, JSONCreated, JSONError, JSONBadRequest, JSONNotFound, Text, HTML, SafeHTML, ReadJSON, ReadJSONLimit, Redirect, SafeRedirect, SafeURL, SetSecureHeaders, SecureHeaders, WithCSRF, Serve, MethodNotAllowed, IsGet/IsPost/IsPut/IsDelete/IsPatch, GetQueryParam, GetHeader; Constants: StatusOK/NotFound/etc
stdlib/input	User input utilities	ReadLine, Prompt, Confirm, Choose; Form builder: NewForm, Text, Confirm, Choose, Validate, Default, Run, String, Bool. Use Default(key, value) to set the substituted value when the user submits a blank line — caller controls the displayed prompt (mask separately when needed, e.g. for API keys).
stdlib/log	Leveled structured logger (Text + JSON formats); package-level funcs bind to os.Stderr, color via color.NewStyler so log honors term overrides.	New, SetLevel, SetFormat, Debug, Info, Warn, Error, Fatal (each also a method on Logger)
stdlib/iterator	Functional iteration (Go 1.23 iter.Seq)	Values, Filter, Map, FlatMap, Take, Skip, Enumerate, Chunk, Zip, Reduce, Collect, Any, All, Find
stdlib/json	encoding/json wrapper	Bytes, PrettyBytes, ParseInto, ParseStringInto, Write, ReadInto, Read, NewEncoder, NewDecoder, Encode, Decode, WithIndent, WriteOutput, Parse, ParseString, Pretty
stdlib/llm	Shared schema utilities for tool definitions	Prop, Schema, Required
stdlib/llm/chat	Chat Completions API (OpenAI-compatible)	New/Ask/Send/SendRaw/Complete/CompleteWithSystem, System/User/Assistant, Temperature/MaxTokens, AddTool, JSONMode, Stream/StreamEvents, Retry, WithContext, FromCompletion/ExecuteToolCalls, GetText/GetToolCalls/HasToolCalls
stdlib/llm/responses	OpenResponses API (POST /v1/responses)	New/Ask/Send/AskRaw/SendRaw/Respond/RespondWithInstructions, Instructions/User/System/Developer/Assistant, Temperature/MaxOutputTokens, AddTool, JSONMode/JSONSchema, Store, Stream/StreamEvents, Retry, WithContext, FromResponse/ExecuteFunctionCalls/FunctionCallOutput, GetText/GetFunctionCalls/HasFunctionCalls
stdlib/llm/anthropic	Anthropic Messages API (POST /v1/messages)	New/Ask/Send/AskRaw/SendRaw/Complete/CompleteWithSystem, System/User/Assistant/ToolResult, Temperature/MaxTokens, AdaptiveThinking/Thinking/Effort, AddTool, Stream/StreamEvents, Retry, WithContext, FromResponse/ExecuteToolUses, GetText/GetThinking/GetToolUses/HasToolUses
stdlib/maps	Map utilities	Keys, Values, Contains, Has, Merge, SortedKeys, Filter, MapValues, Pick, Omit
stdlib/set	Generic set operations	From, Add, AddIn, Remove, RemoveIn, Contains, Len, IsEmpty, ToSlice, Union, Intersect, Difference, IsSubset, IsSuperset, Equal
stdlib/mcp	Model Context Protocol server + client	New, Serve, ServeHTTP, Tool, ToolWithOpts, ToolRich, ToolWithSampling, Resource, TextResource, ResourceTemplate, TextResourceTemplate, Prompt, UserPrompt, Prop, Schema, Required, TextResult, ErrorResult, Connect, BearerConnect, ConnectWithClient, Close, ListTools, CallTool, ListResources, ListResourceTemplates, ReadResource, ListPrompts, GetPrompt, NewWithCompletion, Completions, CompletionsPage, NewRouter
stdlib/must	Panic-on-error startup helpers	Do, DoMsg, Ok, OkMsg, Env, EnvOr, EnvInt, EnvIntOr, EnvBool, EnvBoolOr, EnvList, EnvListOr, True, False, NotEmpty, NotNil
stdlib/netguard	Network restriction & SSRF protection	NewSSRFGuard, NewAllow, NewBlock, Check, DialContext, HTTPTransport, HTTPClient
stdlib/obs	Structured observability helpers	New, NewCorrelationID, Debug, Info, Warn, Error, Log, Start, Stop, Fail (set Logger.Component / Logger.CorrelationID directly)
stdlib/parse	Data format parsing	Json, JsonLines, JsonPretty, Csv, CsvWithHeader, Yaml, YamlPretty
stdlib/random	Random string and numeric generation	String, Alphanumeric, Int, Float
stdlib/regex	Regular expression matching and replacement	Match, Find, FindAll, FindGroups, FindAllGroups, Replace, ReplaceFunc, Split, IsValid, Compile, MustCompile + compiled variants
stdlib/retry	Retry with backoff	New, Attempts, Delay, Linear, Sleep
stdlib/sandbox	os.Root filesystem sandboxing	New, Close, Read, ReadString, Write, WriteString, Append, AppendString, MkDir, MkDirAll, List, Exists, IsDir, IsFile, Stat, Delete, DeleteAll, Rename, Path, FS
stdlib/semver	Semantic versioning (parse, bump, compare)	Parse, Bump, Format, Valid, Compare, Greater, Highest
stdlib/shell	Safe command execution	Run, Output, Lines, Check (run for side effect — nil or error), Capture (stdout+stderr+error), New/Dir/SetTimeout/Env/Execute, Args/FlagIf/Preview, Stdin, StdinBytes, Success, Require, GetOutput, GetError, ExitCode, Which, Getenv, Setenv, Unsetenv, Environ
stdlib/skills (deprecated)	Runtime discovery of agent SKILL.md manifests — copy the package or call filepath.Walk directly	Discover, AgentSkills, ClaudeSkills
stdlib/slice	Slice operations (all generic)	Filter, Reject, Partition, Map, GroupBy, Sort, SortBy, First, Last, Drop, DropLast, Reverse, Unique, Chunk, Contains, IndexOf, Concat, Get, GetOr, FirstOne, FirstOr, LastOne, LastOr, Find, FindOr, FindIndex, FindLast, FindLastOr, IsEmpty, IsNotEmpty, Pop, Shift, Sum, Min, Max, Average
stdlib/sort	Sorting slices (strings, ints, floats, custom)	Strings, Ints, Float64s, By, ByKey, Reverse
stdlib/sqlite	SQLite convenience layer over stdlib/db (ncruces/go-sqlite3)	Open, OpenMemory, OpenWith, Pragma, SetPragma, Tables, TableExists, IntegrityCheck, Vacuum, Backup, Version, BatchExec, CreateFunction, Dump
stdlib/sqliteext	Register ncruces ext/* packages (regexp, uuid, hash, vec1, spellfix1, …) on a stdlib/sqlite pool	Register
stdlib/string	String utilities	ToUpper, ToLower, Title, Trim, TrimSpace, TrimPrefix, TrimSuffix, TrimLeft, TrimRight, Split, SplitN, Join, Fields, Contains, HasPrefix, HasSuffix, Index, LastIndex, Count, Replace, ReplaceAll, Repeat, PadRight, PadLeft, Concat, EqualFold, Len, IsEmpty, IsBlank, Lines
stdlib/table	Terminal table rendering (plain, box, markdown). Width math is ANSI-aware via term.VisibleWidth so colored cells align with plain neighbors.	New, AddRow, Print, PrintWithStyle, ToString, ToStringWithStyle
stdlib/template	Convenience wrapper over Go's text/template and html/template — hides the Parse + bytes.Buffer dance. One-shot Render/HTML, parsed-once Compile/CompileHTML returning a Render method.	Render, HTML, Compile, CompileHTML, Template.Render, HTMLTemplate.Render
stdlib/term	Single source of truth for tty / color / width detection — delegate here from any tty-aware stdlib package instead of rolling per-package globals.	IsTTY, ColorEnabled, ColorEnabledFor, SetColorEnabled, ResetColorOverride, Width, VisibleWidth (ANSI-CSI-aware), PadRightVisible
stdlib/test	Test assertion helpers (use in *_test.kuki only)	AssertEqual, AssertNotEqual, AssertTrue, AssertFalse, AssertNoError, AssertError, AssertNotEmpty, AssertNil, AssertNotNil
stdlib/validate	Input validation	NotEmpty, MinLength, MaxLength, Length, LengthBetween, Matches, Email, URL, Alpha, Alphanumeric, Numeric, NoWhitespace, StartsWith, EndsWith, Contains, OneOf, Positive, Negative, NonNegative, NonZero, InRange, Min, Max, PositiveFloat, InRangeFloat, ParseInt, ParsePositiveInt, ParseFloat, ParseBool, NotEmptyList, ListMinLength, ListMaxLength, WithMessage, Require, NoHTML, SafeFilename, NoNullBytes

Testing Stdlib Packages

Use the table-driven pattern for all *_test.kuki files:

petiole slice_test

import "stdlib/slice"
import "stdlib/test"
import "testing"

type FirstCase
    name    string
    n       int
    wantLen int

func TestFirst(t reference testing.T)
    items := list of string{"a", "b", "c", "d", "e"}
    cases := list of FirstCase{
        FirstCase{name: "3 elements", n: 3, wantLen: 3},
        FirstCase{name: "n > length", n: 10, wantLen: 5},
        FirstCase{name: "n=0", n: 0, wantLen: 0},
    }
    for tc in cases
        t.Run(tc.name, (t reference testing.T) =>
            result := slice.First(items, tc.n)
            test.AssertEqual(t, len(result), tc.wantLen)
        )

Conventions:

• Case types are declared at file scope, named <FunctionName>Case; name string is always the first field
• t.Run(tc.name, (t reference testing.T) => ...) wraps every assertion body
• Use test.AssertEqual, test.AssertNoError, test.AssertError in preference to bare t.Errorf
• A comment # --- TestFoo --- separates each function's table from the next
• Import stdlib/test only in *_test.kuki files, never in library code

Security Patterns

The compiler enforces several security checks. Use the safe alternatives below to avoid compile errors.

Security Check Table

Category	Unsafe (compiler error)	Safe alternative
SQL Injection	db.Query(pool, "SELECT * FROM t WHERE name = '{name}'")	db.Query(pool, "SELECT * FROM t WHERE name = $1", name)
XSS	http.HTML(w, userInput)	http.SafeHTML(w, userInput), html.Render() with html.Escape(), or Go's html/template (auto-escapes {{ }})
SSRF	fetch.Get(url) (in HTTP handler)	fetch.SafeGet(url) one-shot, or fetch.NewExternal(url) |> ... |> Do() for chains
Open Redirect	http.Redirect(w, r, userURL)	http.SafeRedirect(w, r, url, "example.com")
Path Traversal	files.Read(userInput) (in HTTP handler)	sandbox.New("/var/data") + sandbox.Read(box, userInput)
Command Injection	shell.Run("git log {branch}")	shell.Output("git", "log", branch)
Inline JS (XSS)	html.Render("<script>...</script>")	Static .js file with <script src="...">
Inline Event Handler (XSS)	html.Render("<button onclick='...'>")	addEventListener in a static .js file
Regex panic / ReDoS	regex.Match(userPattern, text) (non-literal pattern)	regex.MatchSafe(pattern, text) (returns error), or hoist with regex.MustCompile at init + regex.MatchCompiled
Prompt Injection	chat.Ask("Triage: {issue.body}") (raw untrusted text)	safe.Wrap("body", safe.Truncate(issue.body, 4000)) + safe.Frame(instructions, blocks) from stdlib/llm/safe

HTTP handler detection: any function with an http.ResponseWriter parameter triggers the handler-context checks.

http.SafeRedirect rejects non-http/https schemes (javascript:, data:, file:, vbscript:), protocol-relative //host, and bare relative paths in addition to checking the host allow-list.

The regex check is a lint warning, not a hard error: regex.* callsites with non-literal patterns get security/regex-panic warnings unless they're in stdlib/. Stdlib files are exempt because regex.MatchSafe legitimately forwards patterns.

Import Aliases

When a package's last path segment collides with a local variable name, use as. Always use these standard aliases:

Package	Standard alias	Reason
stdlib/ctx	ctxpkg	Clashes with local ctx variable
stdlib/db	dbpkg	Clashes with local db variable
stdlib/errors	errs	Clashes with local err / errors
stdlib/json	jsonpkg	Clashes with encoding/json
stdlib/string	strpkg	Clashes with string type name
stdlib/http	httphelper	Clashes with net/http

Common Pitfalls

Patterns that look correct but introduce subtle bugs.

WaitGroups in goroutines — use defer wg.Done()

Always make defer wg.Done() the first statement in a goroutine body. An explicit wg.Done() at the end is silently skipped if the task panics, hanging wg.Wait() forever.

# WRONG — hangs if t() panics
go func()
    t()
    wg.Done()
()

# CORRECT — defer fires even on panic
go func()
    defer wg.Done()
    t()
()

Context/cancel lifetime — defer cancel in the function that owns the resource

Never call defer ctxpkg.Cancel(h) inside a helper that returns a resource built with that context. The cancel fires when the helper returns — before the resource is ever used — making the timeout dead on arrival. Defer cancel in the same function whose lifetime covers the resource's use.

# WRONG — cancel fires when buildCmd returns, context is already dead
func buildCmd(cmd Command) reference exec.Cmd
    h := ctxpkg.WithTimeout(ctxpkg.Background(), time.Duration(cmd.timeout) * time.Second)
    defer ctxpkg.Cancel(h)   # fires here, before exec.Run
    return exec.CommandContext(ctxpkg.Value(h), cmd.name, many cmd.args)

# CORRECT — cancel deferred in Execute, fires after execCmd.Run() completes
func Execute(cmd Command) Result
    execCmd := exec.Command(cmd.name, many cmd.args)
    if cmd.timeout > 0
        h := ctxpkg.WithTimeout(ctxpkg.Background(), time.Duration(cmd.timeout) * time.Second)
        defer ctxpkg.Cancel(h)   # fires after Run()
        execCmd = exec.CommandContext(ctxpkg.Value(h), cmd.name, many cmd.args)
    ...

io.ReadCloser wrapping — never use io.NopCloser on a live body

io.NopCloser replaces Close() with a no-op. Wrapping a response body with it means Close() never reaches the underlying connection, leaking it. When you need to cap reads with io.LimitReader, preserve the original closer with a wrapper type that delegates both Read and Close.

# WRONG — NopCloser silences Close(), TCP connection is never released
resp.Body = io.NopCloser(io.LimitReader(resp.Body, maxSize))

# CORRECT — limitReadCloser delegates Read to LimitReader, Close to original body
type limitReadCloser
    r io.Reader
    c io.Closer

func Read on b reference limitReadCloser (p list of byte) (int, error)
    return b.r.Read(p)

func Close on b reference limitReadCloser () error
    return b.c.Close()

resp.Body = reference of limitReadCloser{r: io.LimitReader(resp.Body, maxSize), c: resp.Body}

Module Structure

Every stdlib module is pure Kukicha: <name>.kuki source + <name>.go generated output. There are no hand-written Go implementation files anywhere in stdlib/.

To re-export an external Go type (so callers can use it in type assertions without importing the original package), use a transparent type alias in the .kuki source:

type TextContent = mcp.TextContent     # re-exports external type; generates: type TextContent = mcp.TextContent

This generates Go's type X = Y form — the types are identical, enabling cross-package type assertions like result.(*mcp.TextContent).

WASM-only packages

Some external stdlib packages (e.g., game) depend on libraries with native platform requirements. The codegen automatically emits a //go:build js constraint for these packages and any user code that imports them.

The list of WASM-only packages is defined in wasmOnlyPackages in internal/codegen/codegen_imports.go.

External stdlib packages

externalStdlibPackages map in internal/codegen/codegen_imports.go maps stdlib names to external module paths:

• "game" → "github.com/kukichalang/game"
• "infer" → "github.com/kukichalang/infer"
• "ort" → "github.com/kukichalang/infer/ort"
• "webinfer" → "github.com/kukichalang/infer/webinfer"

Registry stubs (.kuki only, no .go) kept in main repo: stdlib/game/, stdlib/infer/, stdlib/ort/, stdlib/webinfer/.

Vulnerability Auditing

The stdlib is extracted as a standalone Go module (.kukicha/stdlib/) with its own go.mod (embedded in cmd/kukicha/stdlib.go). When users run kukicha audit in their project, govulncheck follows the replace directive into the extracted stdlib and checks its dependencies transitively.

When updating stdlib dependencies (the stdlibGoMod constant in cmd/kukicha/stdlib.go), always run kukicha audit afterward to verify no new vulnerabilities were introduced.

Critical Rules

1. Never edit generated *.go files in stdlib — edit .kuki source, then make generate
2. Never edit internal/semantic/stdlib_registry_gen.go or go_stdlib_gen.go — both are auto-generated
3. Types must be defined in .kuki — so the Kukicha compiler knows about them
4. After adding an exported function or enum to a stdlib .kuki file, run make genstdlibregistry so onerr, pipe expressions, and cross-package enum resolution work correctly
5. To deprecate a stdlib function, add # kuki:deprecated "Use NewFunc instead" above it in the .kuki source, then run make genstdlibregistry
6. To mark a function as security-sensitive, add # kuki:security "category" above it, then run make genstdlibregistry
7. When wrapping an external Go call (vendored third-party package) inside a stdlib .kuki file, attach # kuki:returns N above the statement if the call appears as the operand of onerr or any step of |> — otherwise semantic analysis errors with "return signature is unknown". Go stdlib calls do not need this directive: the hybrid resolver in internal/semantic/go_stdlib_live.go resolves signatures via go/importer on miss, so any user-facing Go stdlib function works out of the box. Adding entries to cmd/gengostdlib/main.go is now an optional speed-up (avoids importer cold start), not a correctness requirement.
8. Every stdlib package must have a *_test.kuki file using the table-driven pattern
9. stdlib/test is test-only — import it only in *_test.kuki files, never in library .kuki files