{"id":47962985,"url":"https://github.com/effectorhq/effector-core","last_synced_at":"2026-04-04T10:03:39.718Z","repository":{"id":344808889,"uuid":"1181985986","full_name":"effectorHQ/effector-core","owner":"effectorHQ","description":"The standard toolkit for typed AI agent tool interoperability — npm install @effectorhq/core","archived":false,"fork":false,"pushed_at":"2026-03-16T21:05:25.000Z","size":79,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-17T00:10:37.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/effectorHQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T22:18:52.000Z","updated_at":"2026-03-16T21:05:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/effectorHQ/effector-core","commit_stats":null,"previous_names":["effectorhq/effector-core"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/effectorHQ/effector-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/effectorHQ","download_url":"https://codeload.github.com/effectorHQ/effector-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/effectorHQ%2Feffector-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31395450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T09:13:02.600Z","status":"ssl_error","status_checked_at":"2026-04-04T09:13:01.683Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T10:03:38.977Z","updated_at":"2026-04-04T10:03:39.707Z","avatar_url":"https://github.com/effectorHQ.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **📦 Consolidated.** This package is now part of [`effectorHQ/effector`](https://github.com/OpenClawHQ/effectorhq) → `packages/core/`.\n\u003e All active development continues in the monorepo. This repository remains available for reference.\n\u003e\n\u003e Install: `npm install @effectorhq/core` (published from the monorepo)\n\n---\n\n# @effectorhq/core\n\n[![npm version](https://img.shields.io/npm/v/@effectorhq/core.svg)](https://www.npmjs.com/package/@effectorhq/core)\n\n\u003ca href=\"https://awesome.re\"\u003e\u003cimg src=\"https://awesome.re/badge.svg\" alt=\"Awesome\"\u003e\u003c/a\u003e\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies)\n[![Tests](https://img.shields.io/badge/tests-102%20passing-brightgreen.svg)](#)\n\n**The standard toolkit for typed AI agent tool interoperability.**\n\n**Shared kernel for [effectorHQ](https://github.com/effectorHQ) — TOML/SKILL parser, type checker, schema validator; one impl for compose, graph, skill-lint, MCP**\n\nParse, validate, type-check, and compile AI agent tool definitions.\n\nZero dependencies, 40 built-in types, 4+ compile targets.\n\n---\n\n## Install\n\n```bash\nnpm install @effectorhq/core\n```\n\nYou can also use the CLI directly without installing globally:\n\n```bash\nnpx @effectorhq/core types\nnpx @effectorhq/core init\n```\n\nSee the published package on npm: https://www.npmjs.com/package/@effectorhq/core\n\n## Quick Start\n\n### Fluent API\n\n```js\nimport { Effector } from '@effectorhq/core';\n\nconst result = Effector\n  .fromDir('./my-skill')\n  .validate()\n  .checkTypes()\n  .compile('mcp');\n\nconsole.log(result); // MCP tool schema, ready to use\n```\n\n### CLI\n\n```bash\n# Scaffold a new skill\nnpx @effectorhq/core init\n\n# Validate\nnpx @effectorhq/core validate .\n\n# Compile to MCP\nnpx @effectorhq/core compile . -t mcp\n\n# List all 40 standard types\nnpx @effectorhq/core types\n```\n\n### Individual Modules\n\n```js\n// Tree-shakeable subpath imports\nimport { parseEffectorToml } from '@effectorhq/core/toml';\nimport { parseSkillFile } from '@effectorhq/core/skill';\nimport { checkTypeCompatibility } from '@effectorhq/core/types';\nimport { validateManifest } from '@effectorhq/core/schema';\nimport { compile, registerTarget } from '@effectorhq/core/compile';\n```\n\n---\n\n## What It Does\n\n**Effector** adds a typed interface layer to AI agent tools. It's a sidecar manifest — your tool keeps running exactly as before.\n\n```\n┌───────────────┐     ┌──────────────┐     ┌──────────────┐\n│ effector.toml │────▶│   validate   │────▶│   compile    │\n│   SKILL.md    │     │  type-check  │     │  mcp/openai/ │\n└───────────────┘     └──────────────┘     │  langchain   │\n                                           └──────────────┘\n```\n\n### The Problem\n\nEvery AI framework defines capabilities differently. MCP tools accept untyped JSON. LangChain tools only work in Python. There's no way to answer _\"Can these two tools compose?\"_ until something breaks at runtime.\n\n### The Solution\n\nDrop an `effector.toml` next to your tool:\n\n```toml\n[effector]\nname = \"code-review\"\nversion = \"0.1.0\"\ntype = \"skill\"\ndescription = \"Automated code review on pull request diffs\"\n\n[effector.interface]\ninput = \"CodeDiff\"\noutput = \"ReviewReport\"\ncontext = [\"Repository\"]\n\n[effector.permissions]\nnetwork = false\nsubprocess = false\n```\n\nNow your tool has:\n- **Type-safe interfaces** — input/output/context from 40 standard types\n- **Static composition checking** — verify tool chains before execution\n- **Cross-runtime portability** — compile to MCP, OpenAI, LangChain, or JSON\n- **Security auditing** — declared permissions vs actual behavior\n\n---\n\n## API Reference\n\n### `@effectorhq/core` (barrel)\n\n| Export | Description |\n|--------|-------------|\n| `Effector` | Fluent builder: `.fromDir()` → `.validate()` → `.compile()` |\n| `parseEffectorToml(content)` | Parse effector.toml → `EffectorDef` |\n| `parseSkillFile(content, filePath?)` | Parse SKILL.md → `ParsedSkill` |\n| `checkTypeCompatibility(out, in)` | Check type compatibility → `TypeCheckResult` |\n| `isTypeCompatible(out, in)` | Graph adapter → `{ precision }` or `null` |\n| `isKnownType(name)` | Check if type exists in catalog |\n| `validateManifest(def)` | Validate manifest → `{ valid, errors, warnings }` |\n| `compile(def, target)` | Compile to runtime target → string |\n| `registerTarget(name, fn)` | Register a custom compile target |\n| `EffectorError` | Structured error with `code`, `context`, `suggestion` |\n\n### Subpath Imports\n\n| Path | Exports |\n|------|---------|\n| `@effectorhq/core/toml` | `parseEffectorToml`, `loadRegistryAsMap`, `loadRegistryAsArray` |\n| `@effectorhq/core/skill` | `parseSkillFile`, `parseYaml`, `extractMetadata` |\n| `@effectorhq/core/types` | `checkTypeCompatibility`, `isTypeCompatible`, `isKnownType`, `resolveAlias`, `getSupertypes`, `getSubtypes`, `setCatalog` |\n| `@effectorhq/core/schema` | `validateManifest`, `validateTypeNames` |\n| `@effectorhq/core/compile` | `compile`, `listTargets`, `registerTarget`, `unregisterTarget` |\n| `@effectorhq/core/errors` | `EffectorError`, error code constants |\n\n---\n\n## Type System\n\n40 standard types across three roles, grounded in real-world usage from 13,000+ analyzed tools:\n\n| Role | Types | Examples |\n|------|-------|----------|\n| **Input** (15) | What tools accept | `String`, `CodeDiff`, `URL`, `JSON`, `ImageRef` |\n| **Output** (14) | What tools return | `Markdown`, `ReviewReport`, `TestResult`, `LintReport` |\n| **Context** (11) | What tools need | `GitHubCredentials`, `Repository`, `Docker`, `Kubernetes` |\n\n### Compatibility Rules\n\n```\n1. Exact match           → precision 1.0\n2. Alias resolution      → precision 0.95  (PlainText → String)\n3. Subtype relation      → precision 0.9   (SecurityReport → ReviewReport)\n4. Wildcard matching     → precision 0.8   (*Report matches ReviewReport)\n5. Structural subtyping  → precision varies\n6. Otherwise             → incompatible\n```\n\n---\n\n## Compile Targets\n\n| Target | Format | Description |\n|--------|--------|-------------|\n| `mcp` | JSON | MCP tool schema (JSON-RPC 2.0) |\n| `openai-agents` | JSON | OpenAI Agents FunctionTool definition |\n| `langchain` | Python | LangChain StructuredTool class |\n| `json` | JSON | Raw Effector IR (passthrough) |\n\n### Custom Targets\n\n```js\nimport { registerTarget, compile } from '@effectorhq/core';\n\nregisterTarget('crewai', (def) =\u003e {\n  return JSON.stringify({\n    name: def.name,\n    description: def.description,\n    expected_output: `A ${def.interface?.output} from ${def.interface?.input}`,\n  }, null, 2);\n}, { description: 'CrewAI agent tool', format: 'json' });\n\ncompile(myDef, 'crewai'); // works!\n```\n\n---\n\n## CLI\n\n```\n@effectorhq/core v1.0.0\n\nUSAGE\n  effector-core \u003ccommand\u003e [dir] [options]\n\nCOMMANDS\n  validate [dir]           Parse and validate effector.toml + SKILL.md\n  compile  [dir] -t \u003ctgt\u003e  Compile to a runtime target\n  check-types [dir]        Validate types against the 40-type catalog\n  types                    List all standard types\n  init                     Scaffold effector.toml + SKILL.md\n\nOPTIONS\n  -t, --target \u003ctarget\u003e    Compile target: mcp, openai-agents, langchain, json\n  -h, --help               Show help\n  -v, --version            Show version\n```\n\n---\n\n## Zero Dependencies\n\nThis package uses only Node.js built-ins (`fs`, `path`, `url`, `util`). Every parser, validator, and compiler is implemented from scratch in ~1200 lines of code.\n\nWhy?\n- **No supply chain risk** — nothing to audit\n- **Fast installs** — no dependency tree\n- **No version conflicts** — works everywhere Node 18+ runs\n- **Small footprint** — the entire package is under 50KB\n\n---\n\n## TypeScript\n\nFull TypeScript support via handwritten `.d.ts` declarations:\n\n```ts\nimport { Effector } from '@effectorhq/core';\nimport type { EffectorDef, TypeCheckResult, CompileTarget } from '@effectorhq/core';\n\nconst e: Effector = Effector.fromDir('./my-skill');\nconst result: TypeCheckResult = checkTypeCompatibility('CodeDiff', 'CodeDiff');\n```\n\nAll subpath imports have proper type declarations.\n\n---\n\n## Examples\n\nSee the [`examples/`](./examples) directory:\n\n- **[basic-validate](./examples/basic-validate)** — Parse and validate an effector.toml\n- **[compile-mcp](./examples/compile-mcp)** — Compile a skill to MCP + OpenAI formats\n- **[type-checking](./examples/type-checking)** — Check type compatibility between tools\n- **[custom-target](./examples/custom-target)** — Register a custom CrewAI compile target\n\n---\n\n## Architecture\n\n```\n                     ┌─────────────────────┐\n                     │     Effector API    │  ← Fluent builder\n                     └──────────┬──────────┘\n                                │\n        ┌───────────┬───────────┼───────────┬────────────┐\n        │           │           │           │            │\n   ┌────▼───┐  ┌────▼───┐  ┌───▼────┐  ┌───▼────┐  ┌───▼────┐\n   │  TOML  │  │ SKILL  │  │ Types  │  │ Schema │  │Compile │\n   │ Parser │  │ Parser │  │ Checker│  │ Valid  │  │Targets │\n   └────────┘  └────────┘  └───┬────┘  └────────┘  └────────┘\n                               │\n                    ┌──────────▼──────────┐\n                    │  types-catalog.json │  ← 40 bundled types\n                    └─────────────────────┘\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is currently licensed under the [Apache License, Version 2.0](LICENSE.md) 。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feffectorhq%2Feffector-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feffectorhq%2Feffector-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feffectorhq%2Feffector-core/lists"}