xiaoju
ae757e4d44
CI / check (pull_request) Successful in 2m52s
Closes #147. Changes default behavior of `uwf thread list` to show only active threads (idle + running). Adds `--all` flag to opt into the previous full-list behavior. Explicit `--status` still wins over `--all`. - cmdThreadList gains a `showAll: boolean` parameter (default false) - CLI registers `--all` option and passes it through - Test suite includes new `default behavior (issue #147)` describe block covering 9 scenarios; existing tests updated where they implicitly relied on the old "show everything" behavior - README, cli-reference, and usage-reference updated to document the new default and the `--all` flag Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@united-workforce/util
Shared utilities: encoding, IDs, logging, frontmatter parsing, storage paths, and CLI reference generation.
Overview
Layer 1 shared infrastructure used across CLI, agent-kit, and agent packages. Provides Crockford Base32 encoding, ULID generation, structured logging with fixed 8-char tags, frontmatter markdown parsing/validation, process-level debug logging, and helpers for the default workflow data directory.
Dependencies: none (standalone)
Installation
bun add @united-workforce/util
API
All exports come from src/index.ts.
Encoding and IDs
function encodeUint64AsCrockford(value: bigint): string
function generateUlid(nowMs: number): string
function extractUlidTimestamp(ulid: string): number | null
Logging
function createLogger(options?: { sink: { kind: "stderr" } }): LogFn
type LogFn = (tag: string, message: string) => void
// CreateLoggerOptions and LoggerSink are internal types
Process logger
function createProcessLogger(options: CreateProcessLoggerOptions): ProcessLogger
type ProcessLogger = {
pid: string;
log: ProcessLogFn;
};
type ProcessLoggerContext = {
thread: string | null;
workflow: string | null;
};
type CreateProcessLoggerOptions = {
storageRoot: string | null;
context: ProcessLoggerContext;
};
type ProcessLogFn = (
tag: string,
msg: string,
context: Record<string, string> | null,
) => void;
Frontmatter markdown
function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
function validateFrontmatter(
parsed: ParsedFrontmatterMarkdown,
schema: Record<string, unknown>,
): FrontmatterValidationError[]
type ParsedFrontmatterMarkdown = {
frontmatter: Record<string, unknown>;
body: string;
};
type AgentFrontmatter = { /* standard agent frontmatter fields */ };
type FrontmatterScope = string;
type FrontmatterStatus = string;
type FrontmatterValidationError = { path: string; message: string };
Result helpers
function ok<T>(value: T): Result<T, never>
function err<E>(error: E): Result<never, E>
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
Storage paths
function getDefaultWorkflowStorageRoot(): string
function getGlobalCasDir(storageRoot: string | undefined): string
Refs and misc
function normalizeRefsField(value: unknown): string[]
function generateCliReference(): string
function env(name: string, fallback: string): string
Usage
import {
createLogger,
generateUlid,
getDefaultWorkflowStorageRoot,
parseFrontmatterMarkdown,
} from "@united-workforce/util";
const log = createLogger();
log("4KNMR2PX", "Loading workflow...");
const root = getDefaultWorkflowStorageRoot();
const threadId = generateUlid(Date.now());
Internal Structure
src/
├── index.ts
├── base32.ts Crockford Base32 encode/decode
├── ulid.ts ULID generation
├── logger.ts Structured logger
├── process-logger/ Process-level debug log files
├── frontmatter-markdown/ Parse and validate agent frontmatter
├── refs-field.ts Normalize refs arrays on CAS nodes
├── result.ts ok / err helpers
├── storage-root.ts Default ~/.uwf paths
├── env.ts Environment variable helper
├── cli-reference.ts Markdown CLI reference generator
└── types.ts LogFn, Result, logger options
Configuration
getDefaultWorkflowStorageRoot() resolves to ~/.uwf unless overridden by environment (see storage-root.ts).