@levelcode/sdk 0.0.5 → 0.1.0

package/dist/sdk/src/skills/load-skills.d.ts

@@ -0,0 +1,42 @@
+import { type SkillsMap } from '@levelcode/common/types/skill';
+export { formatAvailableSkillsXml } from '@levelcode/common/util/skills';
+export type LoadSkillsOptions = {
+    /** Working directory for project skills. Defaults to process.cwd() */
+    cwd?: string;
+    /** Optional specific skills directory path */
+    skillsPath?: string;
+    /** Whether to log errors during loading */
+    verbose?: boolean;
+};
+/**
+ * Load skills from .agents/skills and .claude/skills directories.
+ *
+ * By default, searches for skills in (later overrides earlier):
+ * - `~/.claude/skills/` (global, Claude Code compatible)
+ * - `~/.agents/skills/` (global)
+ * - `{cwd}/.claude/skills/` (project, Claude Code compatible)
+ * - `{cwd}/.agents/skills/` (project, highest priority)
+ *
+ * Each skill must be in its own directory with a SKILL.md file:
+ * - `.agents/skills/my-skill/SKILL.md`
+ * - `.claude/skills/my-skill/SKILL.md`
+ *
+ * @param options.cwd - Working directory for project skills
+ * @param options.skillsPath - Optional path to a specific skills directory
+ * @param options.verbose - Whether to log errors during loading
+ * @returns Record of skill definitions keyed by skill name
+ *
+ * @example
+ * ```typescript
+ * // Load from default locations
+ * const skills = await loadSkills({ verbose: true })
+ *
+ * // Load from a specific directory
+ * const skills = await loadSkills({ skillsPath: './my-skills' })
+ *
+ * // Access a skill
+ * const gitReleaseSkill = skills['git-release']
+ * console.log(gitReleaseSkill.description)
+ * ```
+ */
+export declare function loadSkills(options?: LoadSkillsOptions): Promise<SkillsMap>;

package/dist/sdk/src/testing/env.d.ts

@@ -0,0 +1,5 @@
+import type { SdkEnv } from '../types/env';
+/**
+ * Test-only SDK env builder.
+ */
+export declare const createTestSdkEnv: (overrides?: Partial<SdkEnv>) => SdkEnv;

package/dist/sdk/src/tools/change-file.d.ts

@@ -0,0 +1,7 @@
+import type { LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { LevelCodeFileSystem } from '@levelcode/common/types/filesystem';
+export declare function changeFile(params: {
+    parameters: unknown;
+    cwd: string;
+    fs: LevelCodeFileSystem;
+}): Promise<LevelCodeToolOutput<'str_replace'>>;

package/dist/sdk/src/tools/code-search.d.ts

@@ -0,0 +1,13 @@
+import type { LevelCodeToolOutput } from '../../../common/src/tools/list';
+import { Logger } from '@levelcode/common/types/contracts/logger';
+export declare function codeSearch({ projectPath, pattern, flags, cwd, maxResults, globalMaxResults, maxOutputStringLength, timeoutSeconds, logger, }: {
+    projectPath: string;
+    pattern: string;
+    flags?: string;
+    cwd?: string;
+    maxResults?: number;
+    globalMaxResults?: number;
+    maxOutputStringLength?: number;
+    timeoutSeconds?: number;
+    logger?: Logger;
+}): Promise<LevelCodeToolOutput<'code_search'>>;

package/dist/sdk/src/tools/glob.d.ts

@@ -0,0 +1,8 @@
+import type { LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { LevelCodeFileSystem } from '@levelcode/common/types/filesystem';
+export declare function glob(params: {
+    pattern: string;
+    projectPath: string;
+    cwd?: string;
+    fs: LevelCodeFileSystem;
+}): Promise<LevelCodeToolOutput<'glob'>>;

package/dist/sdk/src/tools/index.d.ts

@@ -0,0 +1,16 @@
+import { changeFile } from './change-file';
+import { codeSearch } from './code-search';
+import { glob } from './glob';
+import { listDirectory } from './list-directory';
+import { getFiles } from './read-files';
+import { runFileChangeHooks } from './run-file-change-hooks';
+import { runTerminalCommand } from './run-terminal-command';
+export declare const ToolHelpers: {
+    runTerminalCommand: typeof runTerminalCommand;
+    codeSearch: typeof codeSearch;
+    glob: typeof glob;
+    listDirectory: typeof listDirectory;
+    getFiles: typeof getFiles;
+    runFileChangeHooks: typeof runFileChangeHooks;
+    changeFile: typeof changeFile;
+};

package/dist/sdk/src/tools/list-directory.d.ts

@@ -0,0 +1,7 @@
+import type { LevelCodeToolOutput } from '@levelcode/common/tools/list';
+import type { LevelCodeFileSystem } from '@levelcode/common/types/filesystem';
+export declare function listDirectory(params: {
+    directoryPath: string;
+    projectPath: string;
+    fs: LevelCodeFileSystem;
+}): Promise<LevelCodeToolOutput<'list_directory'>>;

package/dist/sdk/src/tools/read-files.d.ts

@@ -0,0 +1,16 @@
+import type { LevelCodeFileSystem } from '@levelcode/common/types/filesystem';
+export type FileFilterResult = {
+    status: 'blocked' | 'allow-example' | 'allow';
+};
+export type FileFilter = (filePath: string) => FileFilterResult;
+export declare function getFiles(params: {
+    filePaths: string[];
+    cwd: string;
+    fs: LevelCodeFileSystem;
+    /**
+     * Filter to classify files before reading.
+     * If provided, the caller takes full control of filtering (no gitignore check).
+     * If not provided, the SDK applies gitignore checking automatically.
+     */
+    fileFilter?: FileFilter;
+}): Promise<Record<string, string | null>>;

package/dist/sdk/src/tools/run-file-change-hooks.d.ts

@@ -0,0 +1,4 @@
+import type { LevelCodeToolOutput } from '../../../common/src/tools/list';
+export declare function runFileChangeHooks({ files, }: {
+    files: string[];
+}): Promise<LevelCodeToolOutput<'run_file_change_hooks'>>;

package/dist/sdk/src/tools/run-terminal-command.d.ts

@@ -0,0 +1,8 @@
+import type { LevelCodeToolOutput } from '../../../common/src/tools/list';
+export declare function runTerminalCommand({ command, process_type, cwd, timeout_seconds, env, }: {
+    command: string;
+    process_type: 'SYNC' | 'BACKGROUND';
+    cwd: string;
+    timeout_seconds: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<LevelCodeToolOutput<'run_terminal_command'>>;

package/dist/sdk/src/types/env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SDK-specific environment variable types.
+ *
+ * Extends base types from common with SDK-specific vars for:
+ * - Ripgrep binary path configuration
+ * - WASM module directory
+ */
+import type { BaseEnv, ClientEnv } from '@levelcode/common/types/contracts/env';
+/**
+ * SDK-specific env vars for binary paths and WASM.
+ */
+export type SdkEnv = BaseEnv & {
+    LEVELCODE_RG_PATH?: string;
+    LEVELCODE_WASM_DIR?: string;
+    VERBOSE?: string;
+    OVERRIDE_TARGET?: string;
+    OVERRIDE_PLATFORM?: string;
+    OVERRIDE_ARCH?: string;
+};
+/**
+ * Full SDK env deps combining client env and SDK env.
+ */
+export type SdkEnvDeps = {
+    clientEnv: ClientEnv;
+    env: SdkEnv;
+};
+/**
+ * Function type for getting SDK env values.
+ */
+export type GetSdkEnvFn = () => SdkEnv;

package/dist/sdk/src/validate-agents.d.ts

@@ -0,0 +1,45 @@
+import type { AgentDefinition } from '@levelcode/common/templates/initial-agents-dir/types/agent-definition';
+export interface ValidationResult {
+    success: boolean;
+    validationErrors: Array<{
+        id: string;
+        message: string;
+    }>;
+    errorCount: number;
+}
+export interface ValidateAgentsOptions {
+    /**
+     * Whether to perform remote validation via the web API.
+     * Remote validation checks spawnable agents against the database.
+     */
+    remote?: boolean;
+    /**
+     * The base URL of the LevelCode website API.
+     * Optional - defaults to NEXT_PUBLIC_LEVELCODE_APP_URL or environment-based URL.
+     * Example: 'https://levelcode.vercel.app'
+     */
+    websiteUrl?: string;
+}
+/**
+ * Validates an array of agent definitions.
+ *
+ * By default, performs local Zod schema validation.
+ * When `options.remote` is true, additionally validates spawnable agents via the web API.
+ *
+ * @param definitions - Array of agent definitions to validate
+ * @param options - Optional configuration for validation
+ * @returns Promise<ValidationResult> - Validation results with any errors
+ *
+ * @example
+ * ```typescript
+ * // Local validation only
+ * const result = await validateAgents(definitions)
+ *
+ * // Remote validation
+ * const result = await validateAgents(definitions, {
+ *   remote: true,
+ *   websiteUrl: 'https://levelcode.vercel.app'
+ * })
+ * ```
+ */
+export declare function validateAgents(definitions: AgentDefinition[], options?: ValidateAgentsOptions): Promise<ValidationResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@levelcode/sdk",
   "private": false,
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "Official SDK for LevelCode — AI coding agent & framework",
   "license": "Apache-2.0",
   "type": "module",