Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 5 additions & 14 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,14 @@ jobs:
- name: Checkout
uses: actions/checkout@v7

- name: Set up pnpm
uses: pnpm/action-setup@v6

- name: Set up Node.js
uses: actions/setup-node@v7
with:
node-version: latest
cache: 'pnpm'
- name: Set up Bun
uses: oven-sh/setup-bun@v2

- name: Install dependencies
run: pnpm install
run: bun install

- name: Run checks
run: pnpm check
run: bun check

- name: Run tests
run: pnpm test

- name: Test build
run: pnpm build
run: bun tests
17 changes: 5 additions & 12 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,14 @@ jobs:
- name: Checkout code
uses: actions/checkout@v7

- name: Set up pnpm
uses: pnpm/action-setup@v6

- name: Set up Node.js
uses: actions/setup-node@v7
with:
node-version: latest
cache: 'pnpm'
registry-url: 'https://registry.npmjs.org/'
- name: Set up Bun
uses: oven-sh/setup-bun@v2

- name: Install dependencies
run: pnpm install
run: bun install

- name: Build
run: pnpm build
run: bun compile

- name: Publish to npm
run: pnpm publish --no-git-checks
run: bunx npm@latest publish
9 changes: 6 additions & 3 deletions .oxlintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -87,18 +87,21 @@
"eslint/no-underscore-dangle": "off",
"typescript/no-this-alias": "off",
"vitest/require-top-level-describe": "off",
"typescript/no-unnecessary-type-parameters": "off"
"typescript/no-unnecessary-type-parameters": "off",
"eslint/one-var": "off",
"vitest/prefer-importing-vitest-globals": "off"
},
"env": {
"builtin": true,
"browser": true,
"node": true
},
"globals": {
"activeDocument": "readonly"
"Bun": "readonly"
},
"ignorePatterns": ["**/node_modules/**", "**/dist/**"],
"options": {
"typeAware": true
"typeAware": true,
"typeCheck": true
}
}
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ SynthKernel is an experimental TypeScript software architecture.

## Commands

- `pnpm lint`: format and fix fixable lint errors (always run before `pnpm check`)
- `pnpm check`: check types, lint and format (no fix)
- `pnpm build`: build package
- `pnpm test`: run tests
- `bun fix`: format and fix fixable lint errors (always run before `pnpm check`)
- `bun check`: check types, lint and format (no fix)
- `bun compile`: build package
- `bun test`: run tests
- `bun ./skill/example/main.ts`: run example
37 changes: 14 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<h1 align="center">
<img src="assets/logo.svg" alt="JSON Canvas Viewer logo" width="280px">
<img src="assets/logo.svg" alt="SynthKernel logo" width="280px">
<br />
SynthKernel
<br />
Expand Down Expand Up @@ -27,41 +27,33 @@
</a>
</p>

## ❓ What is SynthKernel?
## What is SynthKernel?

SynthKernel is a low-level TypeScript architecture for building structured [modular monoliths](https://www.geeksforgeeks.org/system-design/what-is-a-modular-monolith/?spm=a2ty_o01.29997173.0.0.4f2555fbU2saKo)
. It combines OOP, advanced generics, and the Facade Pattern to push Inversion of Control to its extremum.
. It combines OOP, advanced generics, and the Facade Pattern to push Inversion of Control through structural typing.

Unlike conventional loaders that expose APIs, SynthKernel’s loader strictly manages lifecycles and acts as a facade. **Modules are the true center**: they define APIs, execute logic, augment the loader, and wire dependencies. This results in an application structure clearly representable as a tree diagram. The philosophy is universally applicable across software, OS design, and robotics.
SynthKernel composes plain classes into a shared, type-safe context. The class that creates a context becomes a facade, exposing the composed APIs. Modules define APIs, execute logic, contribute to the context through their constructor and `root`, and read what they need from siblings. This results in an application structure clearly representable as a tree diagram. The philosophy is universally applicable across software, OS design, and robotics.

## 🔑 Core Problem It Solves
## Core Capability

SynthKernel eliminates the architectural friction of "God Objects" and manual registries by enforcing a type-safe, modular composition model. It leverages TypeScript’s type system to automatically orchestrate capabilities, ensuring that adding a feature instantly augments both runtime behavior and static types. This guarantees strict modularity, zero configuration drift, and inherent testability without sacrificing scalability.

## 📰 Whitepaper
## Whitepaper

SynthKernel provides a Jupyter Notebook whitepaper running TypeScript, you can find it here: [SynthKernel Whitepaper](https://github.com/hesprs/synthkernel/blob/main/whitepaper.ipynb).
The whitepaper is available as both a [Jupyter Notebook](https://github.com/hesprs/synthkernel/blob/main/whitepaper.ipynb) and a plain [Markdown file](https://github.com/hesprs/synthkernel/blob/main/whitepaper.md).

Prerequisites to correctly execute the whitepaper:

- Jupyter Lab
- Python 3
- Node.js & pnpm

After cloning the repository, run the following commands to set up the environment:
To read the notebook interactively, you need Jupyter Lab with a TypeScript kernel. After cloning the repository:

```sh
pnpm install
pnpm tslab install # register TS kernel
bun install
tslab install --user # register TS kernel
```

Then open `whitepaper.ipynb` in your viewer (Jupyter WebUI or VSCode), choose the TS kernel. Now you can read the notebook.
Then open `whitepaper.ipynb` in your viewer (Jupyter WebUI or VSCode), choose the TS kernel.

## 🤖 Agent Skill
## Agent Skill

SynthKernel is 100% AI-native, a skill is written to make agents more comfortable when navigating inside a SynthKernel repo.

WARNING: SynthKernel does enforce very strict and opinionated naming, architecture and file system conventions, and is still in experimental phase.
SynthKernel is AI-native, a skill is written to make agents more comfortable when navigating inside a SynthKernel repo.

**To install the skill**:

Expand All @@ -77,6 +69,5 @@ The command will scaffold and find 1 skill. Then select the coding agent, whethe

Copyright ©️ 2026 Hesprs (Hēsperus)

Architecture whitepaper and README licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)

Architecture whitepaper and README licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)<br>
Agent skill and `synthkernel` npm package licensed under the [MIT License](https://mit-license.org/)
Loading