@michaelfromyeg/weft-core 1.0.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,520 @@
+import { Plugin, Marketplace, ParseResult, Target, ComponentKind, Component, PluginLock, ArtifactRecord, Lockfile, Scope, Badge, Dependency } from '@michaelfromyeg/weft-schema';
+import { HarnessAdapter, CompiledArtifact, ResolvedMarketplace, ArtifactKind } from '@michaelfromyeg/weft-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;
+
+/** One plugin's contribution to a lockfile: its record, placed artifacts, and adapters used. */
+interface LockEntry {
+    pluginLock: PluginLock;
+    artifacts: ArtifactRecord[];
+    adapters: Lockfile["adapters"];
+}
+interface LockEntryInput {
+    result: CompileResult;
+    artifacts: ArtifactRecord[];
+    ref: string;
+    sha: string;
+    dependencies?: PluginLock["dependencies"];
+}
+/** Build one plugin's lock entry from its compiled result and placement (spec §6.3). */
+declare function buildLockEntry(input: LockEntryInput): LockEntry;
+/**
+ * Merge install entries into an existing target lockfile (or a fresh one),
+ * upserting by plugin id: a re-installed plugin replaces its prior record and
+ * artifacts, leaving every other installed plugin in the ledger untouched.
+ */
+declare function mergeLock(existing: Lockfile | null, entries: LockEntry[], generatedAt: string): Lockfile;
+/**
+ * Where a target's `weft.lock` lives: the project root for project scope, a
+ * per-user dir for user scope. The lock travels with the install target, not the
+ * (possibly remote, read-only) source.
+ */
+declare function lockDirForScope(scope: Scope, cwd: string): string;
+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;
+
+/**
+ * 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[];
+/**
+ * `weft 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[];
+/** `weft 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 `weft.lock` (default: the plugin dir). Eval points this at a scratch dir. */
+    lockDir?: string;
+    /** Inject the lockfile timestamp for deterministic tests. */
+    now?: string;
+}
+/** One plugin's install output: its compiled result, lock entry, and config summary. */
+interface PluginInstall {
+    result: CompileResult;
+    entry: LockEntry;
+    /** Declared config resolution summary (never the values) -- spec §11. */
+    secrets: SecretsResult;
+}
+interface InstallResult extends PluginInstall {
+    /** The merged target lockfile (every plugin installed into this target). */
+    lockfile: Lockfile;
+    lockPath: string;
+}
+/** Compile a plugin, place it into the scope, resolve config, write the target `weft.lock`. */
+declare function install(opts: InstallOptions): Promise<InstallResult>;
+interface InstallMarketplaceOptions {
+    marketplaceDir: string;
+    scope: Scope;
+    cwd: string;
+    registry: AdapterRegistry;
+    targets?: Target[];
+    managed?: ManagedPolicy;
+    lockDir?: string;
+    now?: string;
+}
+interface InstallMarketplaceResult {
+    marketplace: Marketplace;
+    /** The merged target lockfile recording every installed plugin. */
+    lockfile: Lockfile;
+    lockPath: string;
+    /** One install per marketplace plugin, in catalog order. */
+    installs: PluginInstall[];
+}
+/**
+ * Install every plugin in a marketplace into the scope in one pass (the
+ * company-marketplace install). Each plugin is resolved (local or remote),
+ * compiled, and placed; all of them land in a single target `weft.lock`,
+ * mirroring a single-plugin install at marketplace scale (same primitives).
+ */
+declare function installMarketplace(opts: InstallMarketplaceOptions): Promise<InstallMarketplaceResult>;
+interface UninstallOptions {
+    /** The install target that holds weft.lock (project root for project scope). */
+    dir: string;
+    /** Optionally remove just one plugin (by id or bare name); default removes all. */
+    plugin?: string;
+}
+interface UninstallResult {
+    removed: string[];
+    /** Plugin ids removed from the lock. */
+    plugins: string[];
+}
+/**
+ * Remove what `install` placed into a target, using the paths recorded in the
+ * target's `weft.lock` (spec §6.3). Removes one plugin (by id or bare name) or
+ * all of them; deletes the lock when nothing is left, else rewrites the rest.
+ * Errors are defined out of existence: a missing artifact is simply skipped.
+ */
+declare function uninstall(opts: UninstallOptions): UninstallResult;
+interface UpdateResult {
+    /** The recompiled plugin's id. */
+    id: string;
+    lockfile: Lockfile;
+    lockPath: string;
+    /** Artifacts whose content hash changed (or are new) since the prior lockfile. */
+    changed: string[];
+}
+/**
+ * Re-resolve refs, recompile a plugin source, diff its artifact content hashes
+ * against the target `weft.lock`, and re-place ONLY changed artifacts (spec §5,
+ * §9.3); its entry is then merged back into the target lock. Content addressing
+ * makes "is there really a new version?" exact: unchanged artifacts are not 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 Weft 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 Weft model and
+ * write it to `outDir`, ready for `weft 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;
+
+/** 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;
+    subdir?: string;
+} | {
+    kind: "git";
+    url: string;
+    ref?: string;
+    subdir?: string;
+} | {
+    kind: "npm";
+    pkg: string;
+    version?: string;
+    subdir?: 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;
+}
+/** A resolved source directory on disk, plus the ref/SHA it came from. */
+interface ResolvedSource {
+    dir: string;
+    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 and pinned to a SHA; `npm:` packages are fetched via `npm pack`. A
+ * trailing `//subdir` selects a plugin nested in the source.
+ */
+declare function resolvePluginRefFull(source: string, fromRoot: string): Promise<ResolvedPlugin>;
+/**
+ * Resolve an install/build target (a plugin OR a marketplace) to a directory on
+ * disk: a local path is returned as-is; a remote ref (optionally with a `//subdir`)
+ * is fetched into the cache. Unlike `resolvePluginRefFull` this does not load a
+ * plugin, so it works for a `marketplace.yaml` target too.
+ */
+declare function resolveSourceDir(source: string, fromRoot: string): Promise<ResolvedSource>;
+/** 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 Weft/CLI version (versioning axis 2, spec §5). */
+declare const WEFT_VERSION = "1.0.0";
+/**
+ * Check a plugin's `weft_min_version` against the running Weft. 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 InstallMarketplaceOptions, type InstallMarketplaceResult, type InstallOptions, type InstallResult, type LintResult, type LockEntry, type LockEntryInput, type ManagedPolicy, type PlannedArtifact, type PolicyContext, type ResolvedComponent, type ResolvedDeps, type ResolvedPlugin, type ResolvedSource, type SecretsResult, type Severity, type Source, type StaticPass, type TaggedArtifact, type TargetOutput, type UninstallOptions, type UninstallResult, type UpdateResult, type VerifyResult, WEFT_VERSION, type WrittenArtifact, artifactDigest, build, buildLockEntry, buildMarketplace, buildToDir, checkManagedPolicy, checkMinVersion, compile, fileAccessors, generateSigningKeys, gitInfo, hasMarketplaceManifest, importNativePlugin, install, installMarketplace, installToScope, lint, loadMarketplaceDir, loadPluginDir, lockDirForScope, mergeLock, parseSource, placeCatalog, placePluginArtifacts, planScopeArtifacts, readLock, resolveAliases, resolveConfig, resolveDependencies, resolveDependency, resolvePluginRef, resolvePluginRefFull, resolveSourceDir, serializeLock, sha256, signLock, staticPass, synthMarketplace, uninstall, update, validatePlugin, verifyArtifacts, verifyLockSignature, writeLock };