plugistry 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plugistry contributors
+
+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

@@ -0,0 +1,77 @@
+# plugistry
+
+Type-safe plugin composition primitives for TypeScript.
+
+This is intentionally small: it provides the base pieces for building a typed plugin/composition layer without tying the package to any application domain.
+
+## Install
+
+```bash
+npm install plugistry
+```
+
+## Example
+
+```ts
+import {
+  createPlatform,
+  definePlugin,
+  definePort,
+} from 'plugistry';
+
+interface DocumentRepository {
+  get(id: string): Promise<{ id: string; title: string } | null>;
+}
+
+const DocumentRepositoryPort =
+  definePort<DocumentRepository>('example/DocumentRepository');
+
+const documentMemoryPlugin = definePlugin({
+  name: 'document-memory',
+
+  register(ctx) {
+    ctx.provide(DocumentRepositoryPort, {
+      async get(id) {
+        return { id, title: 'Example' };
+      },
+    });
+  },
+});
+
+const platform = createPlatform()
+  .use(documentMemoryPlugin)
+  .build();
+
+const documents = platform.resolve(DocumentRepositoryPort);
+const document = await documents.get('doc-1');
+```
+
+## Included primitives
+
+- `createPlatform()`
+- `definePlugin()`
+- `definePort<T>()`
+- `defineConcept<T>()`
+- type-level plugin contribution accumulation
+- runtime provider registration and resolution
+- duplicate/missing provider validation
+
+## Publish
+
+Before publishing, verify the package name is still available:
+
+```bash
+npm view plugistry
+```
+
+Then:
+
+```bash
+npm login
+npm pack --dry-run
+npm publish
+```
+
+## Status
+
+`0.0.1` is a minimal bootstrap release. The intended next step is a typed concept registry with plugin-driven registry transformations, scoped providers, decorators, contributors, and validation.

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+export interface Port<T> {
+  readonly key: symbol;
+  readonly name: string;
+  readonly __type?: T;
+}
+
+export declare function definePort<T>(name: string): Port<T>;
+
+export interface Concept<T> {
+  readonly __type?: T;
+}
+
+export declare function defineConcept<T>(): Concept<T>;
+
+export interface Plugin<Contribution extends object = {}> {
+  readonly name: string;
+  readonly contribution?: Contribution;
+  register?(context: PluginContext): void;
+}
+
+export interface PluginContext {
+  provide<T>(port: Port<T>, value: T): void;
+  resolve<T>(port: Port<T>): T;
+}
+
+export declare function definePlugin<const C extends object>(
+  plugin: Plugin<C>,
+): Plugin<C>;
+
+type ContributionOf<P> =
+  P extends Plugin<infer C> ? C : {};
+
+export type Merge<A, B> = A & B;
+
+export interface Platform<C extends object> {
+  readonly capabilities: C;
+  resolve<T>(port: Port<T>): T;
+}
+
+export interface PlatformBuilder<C extends object = {}> {
+  use<P extends Plugin<any>>(
+    plugin: P,
+  ): PlatformBuilder<Merge<C, ContributionOf<P>>>;
+
+  build(): Platform<C>;
+}
+
+export declare function createPlatform(): PlatformBuilder<{}>;

package/dist/index.js

@@ -0,0 +1,58 @@
+export function definePort(name) {
+  return {
+    key: Symbol.for(name),
+    name,
+  };
+}
+
+export function defineConcept() {
+  return {};
+}
+
+export function definePlugin(plugin) {
+  return plugin;
+}
+
+export function createPlatform() {
+  const plugins = [];
+
+  const builder = {
+    use(plugin) {
+      plugins.push(plugin);
+      return builder;
+    },
+
+    build() {
+      const providers = new Map();
+
+      const context = {
+        provide(port, value) {
+          if (providers.has(port.key)) {
+            throw new Error(`Provider already registered: ${port.name}`);
+          }
+
+          providers.set(port.key, value);
+        },
+
+        resolve(port) {
+          if (!providers.has(port.key)) {
+            throw new Error(`Missing provider: ${port.name}`);
+          }
+
+          return providers.get(port.key);
+        },
+      };
+
+      for (const plugin of plugins) {
+        plugin.register?.(context);
+      }
+
+      return {
+        capabilities: {},
+        resolve: context.resolve,
+      };
+    },
+  };
+
+  return builder;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "plugistry",
+  "version": "0.0.1",
+  "description": "Type-safe plugin composition primitives for TypeScript.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node ./test.mjs",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "typescript",
+    "plugin",
+    "composition",
+    "dependency-injection",
+    "architecture"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}