@qilin-agent/kylin 0.0.0-stage → 4.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# Cordis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cordis is a TypeScript plugin framework for applications that need explicit
+dependency injection, scoped services, lifecycle-managed cleanup, and optional
+configuration-driven loading. The core package is published as `cordis`; the
+official packages in this repository add a loader, config-file includes, HMR,
+console logging, timers, and project scaffolding.
+
+## Install
+
+```sh
+yarn add cordis
+```
+
+Cordis is ESM-first. The repository is tested on current Node releases, and the
+scaffolder requires Node 22 or newer.
+
+## Quick Start
+
+```ts
+import { Context, Service } from 'cordis'
+
+declare module 'cordis' {
+  interface Context {
+    counter: Counter
+  }
+
+  interface Events {
+    'app/ready'(message: string): void
+  }
+}
+
+class Counter extends Service {
+  value = 0
+
+  constructor(ctx: Context) {
+    super(ctx, 'counter')
+  }
+
+  next() {
+    return ++this.value
+  }
+}
+
+const greeter = Object.assign((ctx: Context) => {
+  ctx.on('app/ready', (message) => {
+    ctx.logger.info('%s #%d', message, ctx.counter.next())
+  })
+}, {
+  inject: ['counter'],
+})
+
+const root = new Context()
+await root.plugin(Counter)
+await root.plugin(greeter)
+
+root.emit('app/ready', 'started')
+await root.fiber.dispose()
+```
+
+The important pieces are:
+
+- `new Context()` creates the root dependency container.
+- `ctx.plugin()` starts a plugin and returns a `Fiber`.
+- `inject` tells Cordis which services must exist before the plugin runs.
+- Effects, event listeners, and services are removed when their owning fiber is
+  disposed.
+
+## Documentation
+
+- [Tutorial: build a plugin](../../docs/tutorials/build-a-plugin.md)
+- [Guide: plugin lifecycle](../../docs/guides/plugin-lifecycle.md)
+- [Guide: loader configuration](../../docs/guides/loader-config.md)
+- [API reference](../../docs/api/core.md)
+
+## Packages
+
+| Package | Purpose |
+| --- | --- |
+| `cordis` | Core context, plugin registry, fiber lifecycle, events, services, and logger. |
+| `create-cordis` | Interactive project scaffolder. |
+| `@cordisjs/plugin-loader` | Runtime plugin tree and loader service. |
+| `@cordisjs/plugin-include` | YAML/JSON config-file include support for the loader. |
+| `@cordisjs/plugin-group` | Nested plugin groups for loader configs. |
+| `@cordisjs/plugin-hmr` | Hot module replacement for loader-managed plugins. |
+| `@cordisjs/plugin-logger-console` | Console exporter for the built-in logger. |
+| `@cordisjs/plugin-timer` | Disposal-aware timeout, interval, throttle, and debounce helpers. |
+| `@cordisjs/utils` | Shared utilities used by Cordis packages. |
+
+## Development
+
+```sh
+yarn install
+yarn build
+yarn test
+yarn lint
+```
+
+The monorepo uses Yakumo to build and test all packages. Most examples in the
+docs use public APIs from `cordis`; loader examples additionally use
+`@cordisjs/plugin-loader` and `@cordisjs/plugin-include`.
+
+## Volatile configuration
+
+Schemas may return `Volatile<T>` references, whose values are read through `.get()`. Cordis exports the consumer types; Loader commits volatile-only changes into the running references without restarting and notifies the owning fiber through `loader/volatile-update`. Direct `fiber.update()` retains its existing update waterfall and default restart.

package/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { Context } from '@qilin-agent/kylin'
+import { pathToFileURL } from 'node:url'
+import Loader from '@qilin-agent/kylin-plugin-loader'
+
+const ctx = new Context()
+ctx.baseUrl = pathToFileURL(process.cwd()).href + '/'
+
+await ctx.plugin(Loader)
+await ctx.loader.create({
+  name: '@qilin-agent/kylin-plugin-include',
+  config: {
+    path: './cordis.yml',
+  },
+})