@michaelfromyeg/loom-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael DeMarco
+
+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/dist/index.d.ts

@@ -0,0 +1,449 @@
+import { Plugin, Marketplace, ParseResult, Target, ComponentKind, Component, Badge, ArtifactRecord, Scope, Lockfile, Dependency } from '@michaelfromyeg/loom-schema';
+import { HarnessAdapter, CompiledArtifact, ResolvedMarketplace, ArtifactKind } from '@michaelfromyeg/loom-adapter-kit';
+import { KeyObject } from 'node:crypto';
+
+type Severity = "error" | "warning" | "info";
+interface Diagnostic {
+    severity: Severity;
+    /** Path-precise location: "components[1].mcp", "owner.namespace", or a file path. */
+    where: string;
+    message: string;
+}
+/** Accumulates diagnostics during compile; fails closed when any error is present. */
+declare class Diagnostics {
+    readonly items: Diagnostic[];
+    error(where: string, message: string): void;
+    warn(where: string, message: string): void;
+    info(where: string, message: string): void;
+    get hasErrors(): boolean;
+    get errors(): Diagnostic[];
+}
+declare class CompileError extends Error {
+    readonly diagnostics: Diagnostic[];
+    constructor(message: string, diagnostics: Diagnostic[]);
+}
+
+/** A plugin whose files are available on disk under `root`. */
+interface FetchedPlugin {
+    plugin: Plugin;
+    root: string;
+    manifestPath: string;
+    /** Read a file from the plugin, relative to `root`. */
+    read(relPath: string): Buffer;
+    /** Recursively list files under a plugin dir, as paths relative to `root` (sorted). */
+    list(relDir: string): string[];
+}
+/** A loaded marketplace manifest and its directory. */
+interface FetchedMarketplace {
+    marketplace: Marketplace;
+    root: string;
+    manifestPath: string;
+}
+/** Build `read`/`list` accessors rooted at a directory (used for merged plugins too). */
+declare function fileAccessors(root: string): Pick<FetchedPlugin, "read" | "list">;
+/** Load and validate the plugin manifest in `dir`, exposing its files for adapters. */
+declare function loadPluginDir(dir: string): ParseResult<FetchedPlugin>;
+/** True when `dir` is a marketplace (a catalog of plugins) rather than a plugin. */
+declare function hasMarketplaceManifest(dir: string): boolean;
+/** Load and validate the marketplace manifest in `dir`. */
+declare function loadMarketplaceDir(dir: string): ParseResult<FetchedMarketplace>;
+
+/**
+ * Adapters registered by Target (spec §7). Core depends only on the adapter-kit
+ * interface; the CLI (or an embedding app) registers concrete adapters, keeping
+ * the dependency direction one-way and letting community adapters slot in.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    register(adapter: HarnessAdapter): this;
+    get(target: Target): HarnessAdapter | undefined;
+    has(target: Target): boolean;
+    get targets(): Target[];
+}
+
+/** An emitted artifact tagged with the canonical component it came from. */
+interface TaggedArtifact {
+    componentId: string;
+    artifact: CompiledArtifact;
+}
+/** Everything one adapter produced for one plugin. */
+interface TargetOutput {
+    target: Target;
+    adapter: HarnessAdapter;
+    /** Plugin-root-relative artifacts: components + the plugin manifest. */
+    artifacts: TaggedArtifact[];
+}
+interface CompileResult {
+    fb: FetchedPlugin;
+    /** Plugin id: `{namespace}/{name}`. */
+    id: string;
+    /** The components actually compiled (the piecemeal selection, or all). */
+    components: ResolvedComponent[];
+    aliases: Record<string, string>;
+    diagnostics: Diagnostics;
+    targets: TargetOutput[];
+}
+interface CompileOptions {
+    registry: AdapterRegistry;
+    /** Restrict to these targets; default = every target with a registered adapter. */
+    targets?: Target[];
+    /** Piecemeal: include only these component leaf names; default = all (spec §9.2). */
+    only?: string[];
+}
+/** A synthetic one-entry marketplace wrapping a single plugin (spec §9.1 build). */
+declare function synthMarketplace(plugin: Plugin): ResolvedMarketplace;
+interface ResolvedComponent {
+    id: string;
+    leaf: string;
+    kind: ComponentKind;
+    component: Component;
+}
+interface StaticPass {
+    id: string;
+    diagnostics: Diagnostics;
+    aliases: Record<string, string>;
+    resolved: ResolvedComponent[];
+}
+/**
+ * Steps 1-4 of the pipeline shared by `compile` and `lint`: min-version,
+ * static validation, fully-qualified ids, and alias resolution. No adapters run,
+ * so it is the deterministic "is this plugin valid?" pass behind the valid badge.
+ */
+declare function staticPass(fb: FetchedPlugin): StaticPass;
+/**
+ * Steps 1-5 of the compile pipeline (spec §9.1): load is done by the caller;
+ * here we enforce min-version, validate statically, resolve aliases, and run each
+ * adapter's transform + emitManifest. Catalog emission (a marketplace concern) and
+ * placement are separate so `build` can inspect without installing and `install`
+ * can pull components piecemeal.
+ *
+ * Never throws on plugin problems -- it accumulates diagnostics so the caller can
+ * render them. `build`/`install` fail closed when `diagnostics.hasErrors`.
+ */
+declare function compile(fb: FetchedPlugin, opts: CompileOptions): CompileResult;
+
+interface ConfigResolution {
+    env: string;
+    /** Where the value came from -- never the value itself. */
+    source: "env" | "default" | "missing";
+    secret: boolean;
+}
+interface SecretsResult {
+    resolved: ConfigResolution[];
+    /** Path to the gitignored local config the values were written to (or null). */
+    path: string | null;
+}
+/**
+ * Resolve declared `ConfigVar`s (spec §9.1 step 7, §11 rule 4: declare-not-store).
+ * Values come from the environment or a declared default and are written ONLY to a
+ * local, gitignored config -- never to the lockfile, the plugin, the index, or
+ * telemetry. The returned summary records where each value came from, not the value.
+ */
+declare function resolveConfig(plugin: Plugin, cwd: string, env?: Record<string, string | undefined>): SecretsResult;
+
+/**
+ * A managed-mode install policy (spec §11 rule 5): the same install mechanism as
+ * a solo dev, restricted by scope + policy. An enterprise pins an allowlist of
+ * namespaces and/or required badges; only scope and policy differ, never mechanism.
+ */
+interface ManagedPolicy {
+    /** Only these reverse-DNS namespaces may be installed. */
+    allowNamespaces?: string[];
+    /** Each installed plugin must carry all of these badges. */
+    requireBadges?: Badge[];
+}
+interface PolicyContext {
+    namespace: string;
+    badges?: Badge[];
+}
+/** A blocking reason when the policy forbids the install, or null when permitted. */
+declare function checkManagedPolicy(policy: ManagedPolicy | undefined, ctx: PolicyContext): string | null;
+
+interface WrittenArtifact {
+    target: Target;
+    /** Relative to the per-target output base. */
+    relPath: string;
+    abs: string;
+    hash: string;
+    kind?: ArtifactKind;
+}
+/** Write one plugin's artifacts under `<baseDir>/plugins/<pluginName>/`. */
+declare function placePluginArtifacts(target: TargetOutput, baseDir: string, pluginName: string): WrittenArtifact[];
+/** Emit and write a harness's native catalog at `<baseDir>/`. */
+declare function placeCatalog(adapter: HarnessAdapter, marketplace: ResolvedMarketplace, baseDir: string): WrittenArtifact[];
+/**
+ * `loom build` placement for a single plugin (spec §9.1 step 6, inspect-only):
+ * writes the plugin tree at `outDir/<target>/plugins/<plugin>/` plus a synthetic
+ * one-entry catalog at the target root, leaving harness install dirs untouched.
+ */
+declare function buildToDir(result: CompileResult, outDir: string): WrittenArtifact[];
+interface PlannedArtifact {
+    record: ArtifactRecord;
+    contents: Buffer;
+}
+/**
+ * Compute (without writing) where each target's plugin tree would land in the
+ * scope, with content hashes. Drives both install (write all) and update (write
+ * only what changed). Executable/passthrough artifacts are recorded DISABLED (§11).
+ */
+declare function planScopeArtifacts(result: CompileResult, scope: Scope, cwd: string): PlannedArtifact[];
+/** `loom install` placement (spec §9.1 step 6): write every artifact, record each. */
+declare function installToScope(result: CompileResult, scope: Scope, cwd: string): ArtifactRecord[];
+
+interface LintResult {
+    id: string;
+    plugin: Plugin;
+    aliases: Record<string, string>;
+    diagnostics: Diagnostics;
+}
+/** Load + statically validate a plugin without running any adapter (the valid badge). */
+declare function lint(pluginDir: string): LintResult;
+interface BuildOptions {
+    pluginDir: string;
+    outDir: string;
+    registry: AdapterRegistry;
+    targets?: Target[];
+}
+interface BuildResult {
+    result: CompileResult;
+    written: WrittenArtifact[];
+}
+/** Compile a plugin and write its marketplace + plugin layout into `outDir` (no install). */
+declare function build(opts: BuildOptions): Promise<BuildResult>;
+interface BuildMarketplaceOptions {
+    marketplaceDir: string;
+    outDir: string;
+    registry: AdapterRegistry;
+    targets?: Target[];
+}
+interface BuildMarketplaceResult {
+    marketplace: Marketplace;
+    plugins: CompileResult[];
+    written: WrittenArtifact[];
+}
+/**
+ * Compile a curated `marketplace.yaml` of many plugins: resolve and compile each
+ * referenced plugin, place every plugin tree under `outDir/<target>/plugins/`,
+ * and emit ONE native catalog per target listing them all (spec §6.2). This is
+ * the company-marketplace workflow.
+ */
+declare function buildMarketplace(opts: BuildMarketplaceOptions): Promise<BuildMarketplaceResult>;
+interface InstallOptions {
+    pluginDir: string;
+    scope: Scope;
+    cwd: string;
+    registry: AdapterRegistry;
+    targets?: Target[];
+    /** Piecemeal: install only these component leaf names (spec §9.2). */
+    only?: string[];
+    /** Managed-mode policy: namespace allowlist / required badges (spec §11). */
+    managed?: ManagedPolicy;
+    /** Badges known for this plugin (for managed `requireBadges`). */
+    badges?: Badge[];
+    /** Where to write `loom.lock` (default: the plugin dir). Eval points this at a scratch dir. */
+    lockDir?: string;
+    /** Inject the lockfile timestamp for deterministic tests. */
+    now?: string;
+}
+interface InstallResult {
+    result: CompileResult;
+    lockfile: Lockfile;
+    lockPath: string;
+    /** Declared config resolution summary (never the values) -- spec §11. */
+    secrets: SecretsResult;
+}
+/** Compile a plugin, place it into the scope's dirs, resolve config, write `loom.lock`. */
+declare function install(opts: InstallOptions): Promise<InstallResult>;
+interface UninstallOptions {
+    /** Where loom.lock lives (also the default place uninstall reads from). */
+    pluginDir: string;
+    lockDir?: string;
+}
+interface UninstallResult {
+    removed: string[];
+}
+/**
+ * Remove everything `install` placed, using the paths recorded in `loom.lock`,
+ * then delete the lockfile (spec §6.3). Errors are defined out of existence:
+ * a missing artifact is simply skipped.
+ */
+declare function uninstall(opts: UninstallOptions): UninstallResult;
+interface UpdateResult {
+    lockfile: Lockfile;
+    lockPath: string;
+    /** Artifacts whose content hash changed (or are new) since the prior lockfile. */
+    changed: string[];
+}
+/**
+ * Re-resolve refs, recompile, diff artifact content hashes against `loom.lock`,
+ * and re-place ONLY changed artifacts (spec §5, §9.3). Content addressing makes
+ * "is there really a new version?" exact: an unchanged artifact is never rewritten.
+ */
+declare function update(opts: InstallOptions): Promise<UpdateResult>;
+
+interface DependencyRecord {
+    id: string;
+    range: string;
+    resolvedSha: string;
+}
+interface ResolvedDeps {
+    fb: FetchedPlugin;
+    dependencies: DependencyRecord[];
+}
+/**
+ * Resolve a plugin's `depends` (spec §9.1 step 2). Each dependency is fetched
+ * (locally or git-cloned and pinned to a SHA), then its selected components are
+ * vendored into a merged temp tree under `_deps/<name>/` and registered under the
+ * consuming plugin's namespace. Piecemeal `components:[…]` selects which to
+ * register, but the whole dep tree is copied so shared assets travel (drift-aware).
+ * Direct cycles are detected by id.
+ */
+declare function resolveDependencies(fb: FetchedPlugin, tmpRoot?: string): Promise<ResolvedDeps>;
+
+/** sha256 of compiled output, used for content-addressed update + the signed badge. */
+declare function sha256(contents: string | Buffer): string;
+
+interface ImportPluginOptions {
+    /** Directory holding an existing native plugin or marketplace. */
+    dir: string;
+    adapter: HarnessAdapter;
+    /** Where to write the generated Loom plugin/marketplace. */
+    outDir: string;
+    /** Reverse-DNS namespace to assign (native assets lack one). */
+    namespace?: string;
+}
+interface ImportOutput {
+    kind: "plugin" | "marketplace";
+    name: string;
+    outDir: string;
+    manifestPath: string;
+    fileCount: number;
+    id?: string;
+}
+/**
+ * Reverse-compile an existing native plugin/marketplace into the Loom model and
+ * write it to `outDir`, ready for `loom build` to cross-compile to every other
+ * harness. This is "federate, don't wall off" applied to assets you already have.
+ */
+declare function importNativePlugin(opts: ImportPluginOptions): ImportOutput;
+
+interface LockInput {
+    result: CompileResult;
+    artifacts: ArtifactRecord[];
+    ref: string;
+    sha: string;
+    generatedAt: string;
+    dependencies?: Lockfile["dependencies"];
+}
+/** Assemble the `loom.lock` object (spec §6.3) from an install. */
+declare function buildLockfile(input: LockInput): Lockfile;
+declare function serializeLock(lock: Lockfile): string;
+declare function writeLock(dir: string, lock: Lockfile): string;
+/** Read and validate an existing lockfile; null when absent or malformed. */
+declare function readLock(dir: string): Lockfile | null;
+
+/** One component identified for aliasing: its bare leaf name and full id. */
+interface AliasInput {
+    id: string;
+    leaf: string;
+}
+interface AliasResult {
+    /** Bare leaf name -> fully-qualified id. */
+    aliases: Record<string, string>;
+    /** True same-scope collisions: one leaf claimed by multiple ids. */
+    collisions: Array<{
+        leaf: string;
+        ids: string[];
+    }>;
+}
+/**
+ * Bare name when unambiguous (spec §9.4). A leaf used by exactly one component
+ * gets the bare alias; a leaf shared by several is surfaced as a collision for
+ * the caller to resolve (prompt interactively, or error non-interactively).
+ * Never silently last-wins.
+ */
+declare function resolveAliases(components: AliasInput[]): AliasResult;
+
+type Source = {
+    kind: "local";
+    path: string;
+} | {
+    kind: "github";
+    repo: string;
+    ref?: string;
+} | {
+    kind: "git";
+    url: string;
+    ref?: string;
+} | {
+    kind: "npm";
+    pkg: string;
+    version?: string;
+};
+/** Where cloned/fetched remote plugins are cached. */
+declare const CACHE_DIR: string;
+/** Parse a plugin/dependency source string into a structured form (spec §6.1). */
+declare function parseSource(src: string): Source;
+/** A fetched plugin plus the ref/SHA it resolved to (for the lockfile). */
+interface ResolvedPlugin {
+    fb: FetchedPlugin;
+    ref: string;
+    sha: string;
+}
+/**
+ * Resolve a plugin source to a fetched plugin on disk (spec §5, §9.1 step 2).
+ * Local `./path` sources resolve relative to `fromRoot`; `github:`/git sources are
+ * git-cloned into the cache and pinned to a resolved SHA; `npm:` is a clear stub.
+ */
+declare function resolvePluginRefFull(source: string, fromRoot: string): Promise<ResolvedPlugin>;
+/** Convenience: resolve and return only the fetched plugin. */
+declare function resolvePluginRef(source: string, fromRoot: string): Promise<FetchedPlugin>;
+/** Resolve a `depends` entry to a fetched plugin (relative to the depending plugin root). */
+declare function resolveDependency(dep: Dependency, fromRoot: string): Promise<ResolvedPlugin>;
+/** Best-effort git ref + SHA for the lockfile. Returns sentinels outside a repo. */
+declare function gitInfo(dir: string): Promise<{
+    ref: string;
+    sha: string;
+}>;
+
+/**
+ * A digest over the lockfile's artifact set (component + target + content hash).
+ * Signing this binds a signature to exactly the compiled artifacts (spec §10
+ * `signed` badge). Sorting makes it order-independent and deterministic.
+ */
+declare function artifactDigest(lock: Lockfile): Buffer;
+/** Ed25519 keypair. Production would use sigstore/cosign keyless signing instead. */
+declare function generateSigningKeys(): {
+    publicKey: KeyObject;
+    privateKey: KeyObject;
+};
+declare function signLock(lock: Lockfile, privateKey: KeyObject): string;
+declare function verifyLockSignature(lock: Lockfile, publicKey: KeyObject, signature: string): boolean;
+interface VerifyResult {
+    signatureValid: boolean;
+    /** Recorded artifact paths whose on-disk bytes no longer match the lock hash. */
+    tampered: string[];
+}
+/**
+ * Verify a signature AND that every recorded artifact on disk still matches its
+ * lockfile hash. The `signed` badge requires both: a valid signature over the
+ * digest and no tampered artifacts.
+ */
+declare function verifyArtifacts(lock: Lockfile, publicKey: KeyObject, signature: string): VerifyResult;
+
+/**
+ * Static validation (spec §9.1 step 3, the `valid` badge): every referenced file
+ * exists, skill/agent frontmatter is well-formed, `server.json` parses, and
+ * descriptions clear a basic quality bar. Errors fail the compile closed.
+ */
+declare function validatePlugin(fb: FetchedPlugin, diags: Diagnostics): void;
+
+/** The Loom/CLI version (versioning axis 2, spec §5). */
+declare const LOOM_VERSION = "0.1.0";
+/**
+ * Check a plugin's `loom_min_version` against the running Loom. Returns an error
+ * message when unmet, or null when satisfied / unspecified.
+ */
+declare function checkMinVersion(min: string | undefined): string | null;
+
+export { AdapterRegistry, type AliasInput, type AliasResult, type BuildMarketplaceOptions, type BuildMarketplaceResult, type BuildOptions, type BuildResult, CACHE_DIR, CompileError, type CompileOptions, type CompileResult, type ConfigResolution, type DependencyRecord, type Diagnostic, Diagnostics, type FetchedMarketplace, type FetchedPlugin, type ImportOutput, type ImportPluginOptions, type InstallOptions, type InstallResult, LOOM_VERSION, type LintResult, type LockInput, type ManagedPolicy, type PlannedArtifact, type PolicyContext, type ResolvedComponent, type ResolvedDeps, type ResolvedPlugin, type SecretsResult, type Severity, type Source, type StaticPass, type TaggedArtifact, type TargetOutput, type UninstallOptions, type UninstallResult, type UpdateResult, type VerifyResult, type WrittenArtifact, artifactDigest, build, buildLockfile, buildMarketplace, buildToDir, checkManagedPolicy, checkMinVersion, compile, fileAccessors, generateSigningKeys, gitInfo, hasMarketplaceManifest, importNativePlugin, install, installToScope, lint, loadMarketplaceDir, loadPluginDir, parseSource, placeCatalog, placePluginArtifacts, planScopeArtifacts, readLock, resolveAliases, resolveConfig, resolveDependencies, resolveDependency, resolvePluginRef, resolvePluginRefFull, serializeLock, sha256, signLock, staticPass, synthMarketplace, uninstall, update, validatePlugin, verifyArtifacts, verifyLockSignature, writeLock };