@antelopejs/interface-core 0.0.6 → 0.0.8

package/docs/7.configuration.md

@@ -0,0 +1,182 @@
+# Configuration
+
+## Overview
+
+The `@antelopejs/interface-core/config` module exports TypeScript types and the `defineConfig` helper for defining AntelopeJS project configurations. These types describe module sources, logging settings, environment overrides, and test configurations.
+
+## Import
+
+```ts
+import { defineConfig } from "@antelopejs/interface-core/config";
+import type {
+  AntelopeConfig,
+  AntelopeModuleConfig,
+  AntelopeLogging,
+  ModuleSource,
+  ModuleSourceLocal,
+  ModuleSourceGit,
+  ModuleSourcePackage,
+  ModuleSourceLocalFolder,
+} from "@antelopejs/interface-core/config";
+```
+
+## `defineConfig`
+
+The `defineConfig` function provides type-safe configuration definition. It accepts either a static configuration object or a function that receives a context and returns a configuration.
+
+```ts
+import { defineConfig } from "@antelopejs/interface-core/config";
+
+// Static configuration
+export default defineConfig({
+  name: "my-project",
+  modules: {
+    database: "@antelopejs/database",
+    auth: {
+      version: "1.0.0",
+      source: { type: "package", package: "@antelopejs/auth", version: "1.0.0" },
+      config: { secret: "my-secret" },
+    },
+  },
+});
+```
+
+```ts
+// Dynamic configuration based on environment
+export default defineConfig((ctx) => {
+  return {
+    name: "my-project",
+    modules: {
+      database: {
+        source: { type: "package", package: "@antelopejs/database", version: "1.0.0" },
+        config: {
+          host: ctx.env === "production" ? "db.prod.internal" : "localhost",
+        },
+      },
+    },
+  };
+});
+```
+
+## `AntelopeConfig`
+
+The root configuration object for an AntelopeJS project.
+
+| Property         | Type                                            | Description                                 |
+| ---------------- | ----------------------------------------------- | ------------------------------------------- |
+| `name`           | `string`                                        | Project name                                |
+| `cacheFolder`    | `string`                                        | Optional custom cache directory              |
+| `modules`        | `Record<string, string \| AntelopeModuleConfig>` | Module definitions (shorthand or full)       |
+| `logging`        | `AntelopeLogging`                               | Optional logging configuration              |
+| `envOverrides`   | `Record<string, string \| string[]>`            | Optional environment variable overrides      |
+| `environments`   | `Record<string, Partial<AntelopeConfig>>`        | Optional per-environment config overrides    |
+| `test`           | `AntelopeTestConfig`                            | Optional test configuration                 |
+
+## Module sources
+
+Each module source type specifies how to locate and load the module code.
+
+### Local source
+
+Load a module from a local file path:
+
+```ts
+const config: AntelopeModuleConfig = {
+  source: {
+    type: "local",
+    path: "./modules/my-module",
+    main: "index.ts",
+    watchDir: "src",
+    installCommand: "pnpm install",
+    reloadCommand: "pnpm build",
+  },
+};
+```
+
+The optional `reloadCommand` runs instead of `installCommand` on hot reload, letting you configure a faster command chain (for example, skipping `pnpm install`).
+
+### Git source
+
+Load a module from a Git repository:
+
+```ts
+const config: AntelopeModuleConfig = {
+  source: {
+    type: "git",
+    remote: "https://github.com/org/module.git",
+    branch: "main",
+    installCommand: "pnpm install",
+  },
+};
+```
+
+### Package source
+
+Load a module from an npm package:
+
+```ts
+const config: AntelopeModuleConfig = {
+  source: {
+    type: "package",
+    package: "@antelopejs/database",
+    version: "1.0.0",
+  },
+};
+```
+
+### Local folder source
+
+Load a module from a local folder with optional file watching:
+
+```ts
+const config: AntelopeModuleConfig = {
+  source: {
+    type: "local-folder",
+    path: "./packages/shared",
+    watchDir: ["src", "lib"],
+    installCommand: ["pnpm install", "pnpm build"],
+    reloadCommand: "pnpm build",
+  },
+};
+```
+
+Like the local source, `local-folder` also accepts an optional `reloadCommand` that runs in place of `installCommand` on hot reload.
+
+## `AntelopeModuleConfig`
+
+Full module configuration within the project config.
+
+| Property          | Type                                              | Description                              |
+| ----------------- | ------------------------------------------------- | ---------------------------------------- |
+| `version`         | `string`                                          | Optional version constraint              |
+| `source`          | `ModuleSource*`                                   | Source definition (local, git, package, local-folder) |
+| `config`          | `unknown`                                         | Optional runtime configuration           |
+| `importOverrides` | `ImportOverride[] \| Record<string, string>`       | Optional import path redirections        |
+| `disabledExports` | `string[]`                                        | Optional list of exports to disable      |
+
+## `AntelopeLogging`
+
+Logging configuration within the project config.
+
+| Property          | Type                              | Description                                |
+| ----------------- | --------------------------------- | ------------------------------------------ |
+| `enabled`         | `boolean`                         | Enable or disable logging                  |
+| `moduleTracking`  | `object`                          | Track module-level logging with includes/excludes |
+| `channelFilter`   | `Record<string, number \| string>` | Filter log output by channel and level     |
+| `formatter`       | `Record<string, string>`          | Custom formatters per channel              |
+| `dateFormat`      | `string`                          | Date format string for log timestamps      |
+
+## `AntelopeTestConfig`
+
+Test configuration for the project.
+
+| Property  | Type         | Description                                         |
+| --------- | ------------ | --------------------------------------------------- |
+| `folder`  | `string`     | Optional test folder path                           |
+| `setup`   | `Function`   | Optional async setup function returning partial config |
+| `cleanup` | `Function`   | Optional async cleanup function                     |
+
+## Next steps
+
+- [Introduction](./1.introduction.md) - Return to the overview
+- [Modules](./5.modules.md) - Module lifecycle management

package/docs/8.runtime.md

@@ -0,0 +1,60 @@
+# Runtime
+
+## Overview
+
+The `@antelopejs/interface-core/runtime` module exposes information about the runtime environment of the running project and a registry for development servers. The implementation is provided by the AntelopeJS core: `ajs project dev` reports development mode, while `ajs project start` and `ajs project run` report production mode.
+
+## Import
+
+```ts
+import {
+  GetRuntimeInfo,
+  RegisterDevServer,
+  DEV_REGISTRY_PATH,
+} from "@antelopejs/interface-core/runtime";
+```
+
+## `GetRuntimeInfo`
+
+Retrieves information about the runtime environment of the running project.
+
+```ts
+const info = await GetRuntimeInfo();
+// { dev: true, projectPath: "/path/to/project", env: "default" }
+```
+
+| Field         | Description                                                       |
+| ------------- | ----------------------------------------------------------------- |
+| `dev`         | `true` when running under `ajs project dev`, `false` otherwise    |
+| `projectPath` | Absolute path to the root of the running project                  |
+| `env`         | Name of the active configuration environment                      |
+
+## `RegisterDevServer`
+
+Registers a development server and the endpoints it is listening on. Modules that bind network ports (such as an HTTP API) call this after a successful `listen()` so external tooling can discover the actual endpoints.
+
+```ts
+await RegisterDevServer("api", [
+  { protocol: "http", host: "localhost", port: 5011 },
+]);
+```
+
+In development mode, the core merges the registration into the dev registry file and removes the file on shutdown. Outside development mode, the call is a no-op.
+
+## Dev registry file
+
+The dev registry file lives at `DEV_REGISTRY_PATH` (`.antelope/dev.json`) relative to the project root. Its shape is described by the `DevServerRegistry` type:
+
+```json
+{
+  "pid": 12345,
+  "startedAt": "2026-06-12T10:00:00Z",
+  "servers": {
+    "api": {
+      "endpoints": [{ "protocol": "http", "host": "localhost", "port": 5011 }]
+    }
+  }
+}
+```
+
+The file is only valid while the process identified by `pid` exists. If that process is gone, the file is orphaned and must be ignored or overwritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-core",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "AntelopeJS core interface primitives - proxies, decorators, interface functions, and logging",
   "keywords": [
     "antelopejs",
@@ -16,7 +16,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -79,7 +81,10 @@
     "test": "pnpm run build && ajs module test ."
   },
   "antelopeJs": {
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2"

package/skills/core-interface/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: core-interface
+description: Provides the AntelopeJS core interface primitives - AsyncProxy/EventProxy/RegisteringProxy, InterfaceFunction, ImplementInterface, GetMetadata, decorator factories, module lifecycle events, structured Logging, and defineConfig. Use when importing from "@antelopejs/interface-core" (or its /decorators, /modules, /proxies, /runtime, /config, /logging subpaths), when declaring or implementing an AntelopeJS interface, wiring cross-module calls or events, building custom decorators, subscribing to ModuleStarted/ModuleDestroyed, writing logs via Logging.Info/Error, or authoring antelope.config with defineConfig.
+category: antelopejs-interface
+tags: [antelopejs, interface, proxy, decorators, logging]
+---
+
+# @antelopejs/interface-core
+
+Foundational primitives of the AntelopeJS interface system. An interface is a plain module of proxy
+objects (the declaration); a provider attaches concrete behavior with `ImplementInterface`; consumers
+call the declaration directly. All proxy calls cross module boundaries: they queue while no
+implementation is attached and auto-detach when the providing module is unloaded. Decorator
+factories, `GetMetadata`, and config types are ordinary consumer-side helpers (no proxy crossing).
+
+## Import paths
+
+```ts
+import { InterfaceFunction, ImplementInterface, GetMetadata, GetInterfaceInstances, GetInterfaceInstance, AsyncProxy, EventProxy, RegisteringProxy, GetResponsibleModule } from "@antelopejs/interface-core";
+import { MakeClassDecorator, MakeMethodDecorator, MakePropertyDecorator, MakeParameterDecorator } from "@antelopejs/interface-core/decorators"; // + many combined variants
+import { Events, ListModules, GetModuleInfo, LoadModule, StartModule, StopModule, DestroyModule, ReloadModule } from "@antelopejs/interface-core/modules";
+import { AsyncProxy, EventProxy, RegisteringProxy } from "@antelopejs/interface-core/proxies"; // same classes the root entry re-exports; pick one import site
+import { GetRuntimeInfo, RegisterDevServer, DEV_REGISTRY_PATH } from "@antelopejs/interface-core/runtime";
+import { defineConfig, type AntelopeConfig, type AntelopeModuleConfig } from "@antelopejs/interface-core/config";
+import { Logging } from "@antelopejs/interface-core/logging";
+```
+
+## Declaring and implementing an interface
+
+```ts
+// declaration.ts - the interface contract
+import { InterfaceFunction, EventProxy } from "@antelopejs/interface-core";
+
+export const GetUser = InterfaceFunction<(id: string) => { name: string }>();
+export const OnUserCreated = new EventProxy<(userId: string) => void>();
+```
+
+```ts
+// provider module - attach the implementation
+import { ImplementInterface } from "@antelopejs/interface-core";
+import * as UserInterface from "./declaration";
+
+ImplementInterface(UserInterface, {
+  GetUser(id) {
+    return { name: "Alice" };
+  },
+});
+```
+
+```ts
+// consumer - call the declaration; always returns a Promise
+import { Logging } from "@antelopejs/interface-core/logging";
+import { GetUser, OnUserCreated } from "./declaration";
+
+const user = await GetUser("42");
+OnUserCreated.register((userId) => Logging.Info("created", userId));
+```
+
+For a `RegisteringProxy` field, the implementation entry is an object:
+`{ register: (id, ...args) => void, unregister: (id) => void }`. `EventProxy` fields are never
+implemented; providers `emit` on them, consumers `register`/`unregister` handlers.
+
+## Logging
+
+```ts
+import { Logging } from "@antelopejs/interface-core/logging";
+
+Logging.Info("hello");                       // main channel; also Error/Warn/Debug/Trace
+const ch = new Logging.Channel("database");  // named channel
+ch.Debug("query", { ms: 12 });
+```
+
+## Gotchas
+
+- `InterfaceFunction` calls always return a `Promise`, even for sync implementations. Unimplemented
+  calls queue indefinitely (no timeout); an `await` before any provider attaches simply waits. In
+  `ajs module test` stub mode they reject instead with "Interface function called without
+  implementation in test environment. Ensure the required module is loaded in your test config.".
+- Prefer the synchronous `ImplementInterface(decl, impl)`; the Promise-accepting overload is
+  deprecated. Implementations may be partial - unmatched keys keep queuing.
+- Module attribution (`GetResponsibleModule`) works by call-stack analysis. Attach implementations
+  and register handlers synchronously during module load; doing it from a setTimeout/setInterval
+  callback logs "this will break hot reloading!", and other async contexts break attribution
+  silently - both defeat automatic cleanup on module unload.
+- `RegisteringProxy` replays existing registrations to a newly attached provider (hot reload safe);
+  `EventProxy.register` deduplicates by function identity; both auto-clean handlers of destroyed
+  modules via `Events.ModuleDestroyed`.
+- `GetMetadata` needs a metadata class with a static `key: symbol`; it inherits from the prototype
+  chain by default (pass `inherit = false` to disable). `reflect-metadata` is loaded by the main
+  entry point.
+- Decorator factory callbacks split their arguments: decorator targets first (class / target+key /
+  target+key+descriptor), then the factory's own parameters.
+
+## Deeper reference
+
+See the shipped `.d.ts` files under `dist/` for exact signatures, and this package's `docs/`
+chapters — Introduction, Proxies, Decorators, Metadata, Modules, Logging, Configuration,
+Runtime — for the prose guides. Do not duplicate them here.