TypeScript API Reference

Schemas

CldpmConfig

Root configuration for cldpm.json.

interface CldpmConfig {
  name: string;
  version: string;      // default: "1.0.0"
  projectsDir: string;  // default: "projects"
  sharedDir: string;    // default: "shared"
}

ProjectConfig

Project configuration for project.json.

interface ProjectConfig {
  name: string;
  description?: string;
  dependencies: ProjectDependencies;
}
 
interface ProjectDependencies {
  skills: string[];
  agents: string[];
  hooks: string[];
  rules: string[];
}

ComponentMetadata

Metadata for shared components.

interface ComponentMetadata {
  name: string;
  description?: string;
  dependencies: ComponentDependencies;
  [key: string]: unknown;  // Extra fields allowed
}
 
interface ComponentDependencies {
  skills: string[];
  agents: string[];
  hooks: string[];
  rules: string[];
}

ResolvedComponent

Resolved component information.

interface ResolvedComponent {
  name: string;
  type: "shared" | "local";
  sourcePath: string;
  files: string[];
  metadata?: ComponentMetadata;
}

ResolvedProject

Fully resolved project with all components.

interface ResolvedProject {
  name: string;
  path: string;
  config: ProjectConfig;
  shared: Record<ComponentType, ResolvedComponent[]>;
  local: Record<ComponentType, ResolvedComponent[]>;
}

Config Functions

loadCldpmConfig

Load cldpm.json from a repository root.

function loadCldpmConfig(repoRoot: string): Promise<CldpmConfig>

Throws: Error if cldpm.json not found.

saveCldpmConfig

Save cldpm.json to a repository root.

function saveCldpmConfig(config: CldpmConfig, repoRoot: string): Promise<void>

loadProjectConfig

Load project.json from a project directory.

function loadProjectConfig(projectPath: string): Promise<ProjectConfig>

Throws: Error if project.json not found.

saveProjectConfig

Save project.json to a project directory.

function saveProjectConfig(
  config: ProjectConfig,
  projectPath: string
): Promise<void>

getProjectPath

Get the path to a project by name.

function getProjectPath(
  projectName: string,
  repoRoot: string
): Promise<string | null>

Returns: Project path or null if not found.

listProjects

List all projects in a repository.

function listProjects(repoRoot: string): Promise<Array<{
  name: string;
  path: string;
  config: ProjectConfig;
}>>

loadComponentMetadata

Load metadata for a shared component.

function loadComponentMetadata(
  compType: ComponentType,
  compName: string,
  repoRoot: string
): Promise<ComponentMetadata | null>

saveComponentMetadata

Save metadata for a shared component.

function saveComponentMetadata(
  metadata: ComponentMetadata,
  compType: ComponentType,
  compName: string,
  repoRoot: string
): Promise<void>

Resolver Functions

resolveProject

Resolve a project with all its components.

function resolveProject(
  projectNameOrPath: string,
  repoRoot: string
): Promise<ResolvedProject>

Throws: Error if project not found.

resolveComponent

Resolve a shared component.

function resolveComponent(
  compType: ComponentType,
  compName: string,
  sharedDir: string
): Promise<ResolvedComponent | null>

resolveLocalComponent

Resolve a local component in a project.

function resolveLocalComponent(
  compType: ComponentType,
  compName: string,
  projectPath: string
): Promise<ResolvedComponent | null>

listSharedComponents

List all shared components in a repository.

function listSharedComponents(
  repoRoot: string
): Promise<Record<ComponentType, string[]>>

resolveComponentDependencies

Resolve all dependencies for a component (including transitive).

function resolveComponentDependencies(
  compType: ComponentType,
  compName: string,
  repoRoot: string
): Promise<Array<[ComponentType, string]>>

getAllDependenciesForComponent

Get all dependencies organized by type.

function getAllDependenciesForComponent(
  compType: ComponentType,
  compName: string,
  repoRoot: string
): Promise<Record<ComponentType, string[]>>

Linker Functions

syncProjectLinks

Synchronize all symlinks for a project.

function syncProjectLinks(
  projectPath: string,
  repoRoot: string
): Promise<{ created: string[]; missing: string[] }>

addComponentLink

Add a single component symlink to a project.

function addComponentLink(
  projectPath: string,
  compType: ComponentType,
  compName: string,
  repoRoot: string
): Promise<boolean>

removeComponentLink

Remove a component symlink from a project.

function removeComponentLink(
  projectPath: string,
  compType: ComponentType,
  compName: string
): Promise<boolean>

createSymlink

Create a symlink (low-level).

function createSymlink(source: string, target: string): Promise<boolean>

removeProjectLinks

Remove all symlinks from a project.

function removeProjectLinks(projectPath: string): Promise<void>

getLocalComponents

Get all local components in a project.

function getLocalComponents(
  projectPath: string
): Promise<Record<ComponentType, string[]>>

getSharedComponents

Get all shared (symlinked) components in a project.

function getSharedComponents(
  projectPath: string
): Promise<Record<ComponentType, string[]>>

Helper Functions

createCldpmConfig

Create a CldpmConfig with defaults.

function createCldpmConfig(
  name: string,
  options?: Partial<Omit<CldpmConfig, "name">>
): CldpmConfig

createProjectConfig

Create a ProjectConfig with defaults.

function createProjectConfig(
  name: string,
  options?: Partial<Omit<ProjectConfig, "name">>
): ProjectConfig

createComponentMetadata

Create ComponentMetadata with defaults.

function createComponentMetadata(
  name: string,
  options?: Partial<Omit<ComponentMetadata, "name">>
): ComponentMetadata

parseComponentRef

Parse component reference (e.g., "skill:my-skill").

function parseComponentRef(ref: string): {
  type: ComponentType | null;
  name: string;
}

getSingularType

Get singular form of component type.

function getSingularType(type: ComponentType): string
// "skills" -> "skill"

Types

ComponentType

type ComponentType = "skills" | "agents" | "hooks" | "rules";

ComponentTypes

const ComponentTypes: readonly ["skills", "agents", "hooks", "rules"];

Usage Go SDK