@lorion-org/surface-activation 1.0.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,70 @@
+# @lorion-org/surface-activation
+
+Framework-free **surface activation**: given a capability that lives as an on-disk
+package, decide _which module and exported symbol_ provides a named "surface" (for
+example `web` or `server`), and build the import specifier to reach it — by
+file-layout convention, with no surface config in the descriptor.
+
+It is pure: no filesystem access, no framework, no runtime. The same seam is shared
+by build-time hosts (which code-generate static imports) and runtime hosts (which
+dynamically `import()`), so the addressing rule lives in exactly one place instead
+of being reinvented per host.
+
+## Concepts
+
+- **`SurfaceConvention`** — how a host detects a surface (`marker`), names its
+  export (`exportName(id)`), and where it is exported from (`exportSubpath`).
+- **`conventionActivation(surfaces)`** — builds an `ActivationResolver` from
+  per-surface conventions.
+- **`fileSurfaceConvention(options)`** — a ready-made `SurfaceConvention` for the
+  common file-layout case: the surface exists when one of `files` is present, and its
+  export is `camelCase(id) + exportSuffix`. It bakes the marker and naming so a host
+  stops repeating them per surface; existence is injected (`exists`) so this package
+  stays I/O-free.
+- **`capabilitySpecifier(packageName, exportSubpath)`** — the one rule for a
+  capability's import specifier (`@acme/shops` + `./web` → `@acme/shops/web`).
+- **`resolveSurfaceModules(active, surface, activation)`** — for each active
+  capability that provides the surface, the specifier and export name to import.
+
+## Usage
+
+```ts
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  conventionActivation,
+  fileSurfaceConvention,
+  resolveSurfaceModules,
+} from '@lorion-org/surface-activation';
+
+const activation = conventionActivation({
+  web: fileSurfaceConvention({
+    files: ['src/web.ts'], // surface present when any listed file exists
+    exportSuffix: 'WebPlugin', // exportName = camelCase(id) + suffix
+    exportSubpath: './web',
+    exists: existsSync, // injected — the package itself touches no filesystem
+    join, // optional; defaults to a POSIX join
+  }),
+});
+
+// `active` is any list of { id, directory, packageName } items.
+const modules = resolveSurfaceModules(active, 'web', activation);
+// -> [{ capability, specifier: '@acme/shops/web', exportName: 'shopsWebPlugin' }, ...]
+```
+
+The convention is the only surface-specific part: swap `exportSuffix`/`exportSubpath`
+(and `files`) for a `server` surface, an `api` surface, or any other. The raw
+`SurfaceConvention` object stays available for cases the preset does not cover.
+
+A build-time host emits a static `import` per entry; a runtime host feeds each
+`specifier` to a dynamic `import()`. Both use the identical list.
+
+## Consumers in this repo
+
+- `@lorion-org/capability-composition` — feeds the specifiers to its runtime
+  `composeCapabilities` loop, and re-exports the convention builders
+  (`conventionActivation`, `fileSurfaceConvention`) and their types for callers of
+  that loop. The build-time addressing tools (`resolveSurfaceModules`,
+  `capabilitySpecifier`) are imported from this package directly.
+- `@lorion-org/react` — uses `capabilitySpecifier` when code-generating static
+  capability imports at build time.

package/dist/index.cjs

@@ -0,0 +1,73 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  capabilitySpecifier: () => capabilitySpecifier,
+  conventionActivation: () => conventionActivation,
+  fileSurfaceConvention: () => fileSurfaceConvention,
+  resolveSurfaceModules: () => resolveSurfaceModules
+});
+module.exports = __toCommonJS(index_exports);
+function conventionActivation(surfaces) {
+  return (surface, capability) => {
+    const convention = surfaces[surface];
+    if (!convention || !convention.marker(capability.directory)) return void 0;
+    return {
+      exportSubpath: convention.exportSubpath,
+      exportName: convention.exportName(capability.id)
+    };
+  };
+}
+function camelCaseId(id) {
+  return id.replace(/^-+|-+$/g, "").replace(/-+([a-z0-9])/gi, (_match, char) => char.toUpperCase());
+}
+function fileSurfaceConvention(options) {
+  const { files, exportSubpath, exportSuffix = "", exists } = options;
+  const join = options.join ?? ((directory, file) => `${directory}/${file}`);
+  return {
+    marker: (directory) => files.some((file) => exists(join(directory, file))),
+    exportName: (id) => `${camelCaseId(id)}${exportSuffix}`,
+    exportSubpath
+  };
+}
+function capabilitySpecifier(packageName, exportSubpath) {
+  return `${packageName}${exportSubpath.replace(/^\./, "")}`;
+}
+function resolveSurfaceModules(active, surface, activation) {
+  return active.flatMap((capability) => {
+    const entry = activation(surface, { directory: capability.directory, id: capability.id });
+    if (!entry) return [];
+    return [
+      {
+        capability,
+        specifier: capabilitySpecifier(capability.packageName, entry.exportSubpath),
+        exportName: entry.exportName
+      }
+    ];
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  capabilitySpecifier,
+  conventionActivation,
+  fileSurfaceConvention,
+  resolveSurfaceModules
+});

package/dist/index.d.cts

@@ -0,0 +1,36 @@
+interface SurfaceActivation {
+    exportSubpath: string;
+    exportName: string;
+}
+interface SurfaceConvention {
+    marker: (directory: string) => boolean;
+    exportName: (id: string) => string;
+    exportSubpath: string;
+}
+type ActivationResolver = (surface: string, capability: {
+    directory: string;
+    id: string;
+}) => SurfaceActivation | undefined;
+declare function conventionActivation(surfaces: Record<string, SurfaceConvention>): ActivationResolver;
+interface FileSurfaceConventionOptions {
+    files: readonly string[];
+    exportSubpath: string;
+    exportSuffix?: string;
+    exists: (path: string) => boolean;
+    join?: (directory: string, file: string) => string;
+}
+declare function fileSurfaceConvention(options: FileSurfaceConventionOptions): SurfaceConvention;
+declare function capabilitySpecifier(packageName: string, exportSubpath: string): string;
+interface SurfaceCapability {
+    id: string;
+    directory: string;
+    packageName: string;
+}
+interface CapabilitySurfaceModule<T extends SurfaceCapability = SurfaceCapability> {
+    capability: T;
+    specifier: string;
+    exportName: string;
+}
+declare function resolveSurfaceModules<T extends SurfaceCapability>(active: readonly T[], surface: string, activation: ActivationResolver): CapabilitySurfaceModule<T>[];
+
+export { type ActivationResolver, type CapabilitySurfaceModule, type FileSurfaceConventionOptions, type SurfaceActivation, type SurfaceCapability, type SurfaceConvention, capabilitySpecifier, conventionActivation, fileSurfaceConvention, resolveSurfaceModules };

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+interface SurfaceActivation {
+    exportSubpath: string;
+    exportName: string;
+}
+interface SurfaceConvention {
+    marker: (directory: string) => boolean;
+    exportName: (id: string) => string;
+    exportSubpath: string;
+}
+type ActivationResolver = (surface: string, capability: {
+    directory: string;
+    id: string;
+}) => SurfaceActivation | undefined;
+declare function conventionActivation(surfaces: Record<string, SurfaceConvention>): ActivationResolver;
+interface FileSurfaceConventionOptions {
+    files: readonly string[];
+    exportSubpath: string;
+    exportSuffix?: string;
+    exists: (path: string) => boolean;
+    join?: (directory: string, file: string) => string;
+}
+declare function fileSurfaceConvention(options: FileSurfaceConventionOptions): SurfaceConvention;
+declare function capabilitySpecifier(packageName: string, exportSubpath: string): string;
+interface SurfaceCapability {
+    id: string;
+    directory: string;
+    packageName: string;
+}
+interface CapabilitySurfaceModule<T extends SurfaceCapability = SurfaceCapability> {
+    capability: T;
+    specifier: string;
+    exportName: string;
+}
+declare function resolveSurfaceModules<T extends SurfaceCapability>(active: readonly T[], surface: string, activation: ActivationResolver): CapabilitySurfaceModule<T>[];
+
+export { type ActivationResolver, type CapabilitySurfaceModule, type FileSurfaceConventionOptions, type SurfaceActivation, type SurfaceCapability, type SurfaceConvention, capabilitySpecifier, conventionActivation, fileSurfaceConvention, resolveSurfaceModules };

package/dist/index.js

@@ -0,0 +1,45 @@
+// src/index.ts
+function conventionActivation(surfaces) {
+  return (surface, capability) => {
+    const convention = surfaces[surface];
+    if (!convention || !convention.marker(capability.directory)) return void 0;
+    return {
+      exportSubpath: convention.exportSubpath,
+      exportName: convention.exportName(capability.id)
+    };
+  };
+}
+function camelCaseId(id) {
+  return id.replace(/^-+|-+$/g, "").replace(/-+([a-z0-9])/gi, (_match, char) => char.toUpperCase());
+}
+function fileSurfaceConvention(options) {
+  const { files, exportSubpath, exportSuffix = "", exists } = options;
+  const join = options.join ?? ((directory, file) => `${directory}/${file}`);
+  return {
+    marker: (directory) => files.some((file) => exists(join(directory, file))),
+    exportName: (id) => `${camelCaseId(id)}${exportSuffix}`,
+    exportSubpath
+  };
+}
+function capabilitySpecifier(packageName, exportSubpath) {
+  return `${packageName}${exportSubpath.replace(/^\./, "")}`;
+}
+function resolveSurfaceModules(active, surface, activation) {
+  return active.flatMap((capability) => {
+    const entry = activation(surface, { directory: capability.directory, id: capability.id });
+    if (!entry) return [];
+    return [
+      {
+        capability,
+        specifier: capabilitySpecifier(capability.packageName, entry.exportSubpath),
+        exportName: entry.exportName
+      }
+    ];
+  });
+}
+export {
+  capabilitySpecifier,
+  conventionActivation,
+  fileSurfaceConvention,
+  resolveSurfaceModules
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@lorion-org/surface-activation",
+  "version": "1.0.0-beta.3",
+  "description": "Framework-free surface-activation convention: which module and export provides a capability's surface, and the import specifier to reach it.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/surface-activation"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/surface-activation#readme",
+  "bugs": {
+    "url": "https://github.com/lorion-org/lorion/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
+    "lint": "eslint src --ext .ts",
+    "prepack": "pnpm build",
+    "test": "vitest run --root ../.. --config vitest.config.mts packages/surface-activation/src/index.spec.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('../../coverage/.tmp', { recursive: true })\" && vitest run --coverage --coverage.include=packages/surface-activation/src/**/*.ts --root ../.. --config vitest.config.mts packages/surface-activation/src/index.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "package:check": "pnpm build && pnpm pack --dry-run && publint"
+  },
+  "keywords": [
+    "surface",
+    "activation",
+    "capability",
+    "composition",
+    "typescript"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,131 @@
+// Surface activation: a framework-free, file-layout convention for deciding which
+// module (and which exported symbol) provides a given "surface" of a capability,
+// and the import specifier to reach it. Pure — no filesystem, no framework. The
+// same seam is shared by build-time hosts (which code-generate static imports) and
+// runtime hosts (which dynamically import), so the addressing rule lives in exactly
+// one place.
+
+export interface SurfaceActivation {
+  exportSubpath: string;
+  exportName: string;
+}
+
+export interface SurfaceConvention {
+  // True when the capability provides this surface (a file-layout marker).
+  marker: (directory: string) => boolean;
+  // Derives the exported symbol name from the capability id.
+  exportName: (id: string) => string;
+  // The package export subpath the symbol is imported from (for example `./web`).
+  exportSubpath: string;
+}
+
+export type ActivationResolver = (
+  surface: string,
+  capability: { directory: string; id: string },
+) => SurfaceActivation | undefined;
+
+// Builds an activation resolver from per-surface conventions. A host declares how a
+// surface is detected (marker) and named (exportName); the descriptor carries no
+// surface config.
+export function conventionActivation(
+  surfaces: Record<string, SurfaceConvention>,
+): ActivationResolver {
+  return (surface, capability) => {
+    const convention = surfaces[surface];
+    if (!convention || !convention.marker(capability.directory)) return undefined;
+    return {
+      exportSubpath: convention.exportSubpath,
+      exportName: convention.exportName(capability.id),
+    };
+  };
+}
+
+export interface FileSurfaceConventionOptions {
+  // Relative marker files; the surface exists when the capability ships any of them
+  // (for example `['src/web.ts']`, or several accepted layouts). An empty list means
+  // the surface never activates — pass at least one marker.
+  files: readonly string[];
+  // Export subpath the symbol is imported from (for example `./web`).
+  exportSubpath: string;
+  // Suffix appended to the camelCased id to form the export name
+  // (`'WebPlugin'` turns `auth-oidc` into `authOidcWebPlugin`). Defaults to `''`.
+  exportSuffix?: string;
+  // Existence check for a marker path, injected by the host. Kept out of this module
+  // so the package stays I/O-free — a Node host passes `existsSync`.
+  exists: (path: string) => boolean;
+  // Joins a capability directory with a relative marker file. Defaults to a POSIX
+  // join (`${directory}/${file}`), which Node's fs accepts on every platform; pass
+  // `node:path`'s `join` for native separators.
+  join?: (directory: string, file: string) => string;
+}
+
+// Converts a kebab-case id to a camelCase identifier fragment (`auth-oidc` ->
+// `authOidc`). The shared naming rule so every host derives export names the same
+// way. Hyphen runs are collapsed and the following character is uppercased
+// (letters and digits alike), and leading/trailing hyphens are dropped, so
+// non-strict ids (`auth-2fa`, `foo--bar`, `foo-`) still yield a valid identifier
+// fragment. An id that starts with a digit cannot be a valid identifier on its own —
+// constrain ids at the descriptor level if that matters.
+function camelCaseId(id: string): string {
+  return id
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+([a-z0-9])/gi, (_match, char: string) => char.toUpperCase());
+}
+
+// A ready-made `SurfaceConvention` for the common file-layout case: the surface is
+// present when one of `files` exists, and its export is `camelCase(id) + exportSuffix`
+// from `exportSubpath`. Hand the result to `conventionActivation`. This is the whole
+// marker/naming boilerplate a host would otherwise repeat per surface; the raw
+// `SurfaceConvention` object stays available for anything this preset does not cover.
+export function fileSurfaceConvention(options: FileSurfaceConventionOptions): SurfaceConvention {
+  const { files, exportSubpath, exportSuffix = '', exists } = options;
+  const join = options.join ?? ((directory, file) => `${directory}/${file}`);
+  return {
+    marker: (directory) => files.some((file) => exists(join(directory, file))),
+    exportName: (id) => `${camelCaseId(id)}${exportSuffix}`,
+    exportSubpath,
+  };
+}
+
+// The import specifier for a capability's surface module: the package name joined
+// with the export subpath, with a leading `.` dropped (`./web` becomes `/web`). One
+// rule, shared by every host style.
+export function capabilitySpecifier(packageName: string, exportSubpath: string): string {
+  return `${packageName}${exportSubpath.replace(/^\./, '')}`;
+}
+
+// The minimal capability shape surface addressing needs: an id, its on-disk
+// directory, and the package name the specifier is built from.
+export interface SurfaceCapability {
+  id: string;
+  directory: string;
+  packageName: string;
+}
+
+export interface CapabilitySurfaceModule<T extends SurfaceCapability = SurfaceCapability> {
+  capability: T;
+  specifier: string;
+  exportName: string;
+}
+
+// For each active capability that provides the surface, the module specifier and
+// export name to import. The seam shared by both host styles: a runtime loop feeds
+// each specifier to a dynamic import, while a build-time host code-generates static
+// imports from the same list.
+export function resolveSurfaceModules<T extends SurfaceCapability>(
+  active: readonly T[],
+  surface: string,
+  activation: ActivationResolver,
+): CapabilitySurfaceModule<T>[] {
+  return active.flatMap((capability) => {
+    const entry = activation(surface, { directory: capability.directory, id: capability.id });
+    if (!entry) return [];
+    return [
+      {
+        capability,
+        specifier: capabilitySpecifier(capability.packageName, entry.exportSubpath),
+        exportName: entry.exportName,
+      },
+    ];
+  });
+}