@lushly-dev/afd-core weekly downloads statistics

@lushly-dev/afd-core

Core types and utilities for Agent-First Development.

Installation

npm install @lushly-dev/afd-core
# or
pnpm add @lushly-dev/afd-core

Overview

This package provides the foundational types used across all AFD packages:

• CommandResult - Standard result type with UX-enabling fields
• CommandError - Actionable error structure
• CommandDefinition - Full command schema with handler
• MCP types - Model Context Protocol types for agent communication

Entry points

Import	Contents	Runs in
@lushly-dev/afd-core	All types and helpers; not connectors or platform	Node.js and browsers
@lushly-dev/afd-core/commands	Command types, defaultExpose, validateCommandName, createCommandRegistry, MCP tool conversion	Node.js and browsers
@lushly-dev/afd-core/result	CommandResult, success, failure, error, isSuccess, isFailure	Node.js and browsers
@lushly-dev/afd-core/connectors	GitHubConnector, PackageManagerConnector and their types	Node.js only
@lushly-dev/afd-core/platform	exec, findUp, isWindows and other process helpers	Node.js only

Connectors live in their own subpath

GitHubConnector and PackageManagerConnector spawn processes through node:child_process, so they are exported only from the connectors subpath:

import { GitHubConnector, PackageManagerConnector } from '@lushly-dev/afd-core/connectors';

Since 2.0 the root entry no longer re-exports them, so it bundles for the browser (for example with esbuild --bundle --platform=browser).

Contract version

AFD_CONTRACT_VERSION is the version of the AFD contract this package implements: the wire shapes, pipeline variables, behavior vectors and conformance suite that the TypeScript, Python, Rust and C++ implementations share (spec/VERSION). It is independent of the package version. afd-help reports it as contractVersion.

import { AFD_CONTRACT_VERSION } from '@lushly-dev/afd-core';

Running processes

exec(['git', 'status'], options) from the platform subpath never uses a shell. It captures at most maxOutputBytes (default 10 MiB, DEFAULT_MAX_OUTPUT_BYTES) from each of stdout and stderr. Past that it kills the process and returns errorCode: 'OUTPUT_LIMIT_EXCEEDED' with the output captured up to the limit.

Usage

Creating Command Results

import { success, failure, type CommandResult } from '@lushly-dev/afd-core';

// Successful result with UX-enabling fields
const result: CommandResult<Document> = success(
  { id: 'doc-123', title: 'My Document' },
  {
    confidence: 0.95,
    reasoning: 'Document created with all required fields',
    sources: [{ type: 'template', title: 'Default Template' }]
  }
);

// Failed result with actionable error
const error = failure({
  code: 'VALIDATION_ERROR',
  message: 'Title is required',
  suggestion: 'Provide a title and try again',
  retryable: false
});

Using Type Guards

import { isSuccess, isFailure } from '@lushly-dev/afd-core';

if (isSuccess(result)) {
  console.log(result.data); // Typed as T (undefined for void commands)
}

if (isFailure(result)) {
  console.log(result.error); // TypeScript knows error exists
}

isSuccess checks only success === true, so a void command's success(undefined) is a success. isFailure checks only success === false, so every result is exactly one of the two, and { success: false } without an error is a failure. Results built with failure() always carry an error; read one from an untrusted peer defensively (result.error?.code).

Defining Commands

import {
  type CommandDefinition,
  createCommandRegistry,
  success,
  validationError
} from '@lushly-dev/afd-core';

interface CreateDocInput {
  title: string;
  content?: string;
}

interface Document {
  id: string;
  title: string;
  content: string;
}

const createDocument: CommandDefinition<CreateDocInput, Document> = {
  name: 'document-create',
  description: 'Creates a new document',
  category: 'documents',
  parameters: [
    { name: 'title', type: 'string', description: 'Document title', required: true },
    { name: 'content', type: 'string', description: 'Document content' }
  ],
  handler: async (input) => {
    if (!input.title) {
      return failure(validationError('Title is required'));
    }
    
    const doc = await db.createDocument(input);
    return success(doc, {
      confidence: 1.0,
      reasoning: 'Document created successfully'
    });
  }
};

// Register and execute
const registry = createCommandRegistry();
registry.register(createDocument);

const result = await registry.execute('document-create', { title: 'Test' });

The registry follows the same rules as the MCP server:

• Pass { interface: 'mcp' } (or 'cli', 'agent', 'palette') as the context to execute, executeBatch or executeStream and the command's expose options are checked on every entry point, including each batch entry.
• executeBatch validates the whole request with isBatchRequest() before running anything, and options.timeout is a deadline at any parallelism.
• A handler that throws returns COMMAND_EXECUTION_ERROR without the exception message or stack. Pass createCommandRegistry({ devMode: true }) to include them.

Batch and stream execution live in executeBatch() and executeStream(), which take an execute callback like executePipeline(), so other hosts can reuse the same semantics. The MCP server uses them too.…