@michaelfromyeg/loom-adapter-kit 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,186 @@
+import { Owner, Target, Plugin, Marketplace, Scope, Component } from '@michaelfromyeg/loom-schema';
+export { homedir } from 'node:os';
+
+/**
+ * Classifies an artifact for the trust summary and lockfile grouping. This is
+ * metadata only -- it never decides placement (relPath does that).
+ */
+type ArtifactKind = "skill" | "mcp" | "agent" | "command" | "hook" | "manifest" | "catalog" | "other";
+/**
+ * One file an adapter emits. `relPath` is relative to the native plugin/output
+ * root the adapter targets (e.g. "skills/greet/SKILL.md",
+ * ".claude-plugin/plugin.json"). Core decides the absolute base per build mode
+ * and scope; the adapter never hard-codes absolute paths.
+ */
+interface CompiledArtifact {
+    relPath: string;
+    contents: string | Buffer;
+    kind?: ArtifactKind;
+    /** Passthrough executables. Placed DISABLED; activation is a separate opt-in (spec §11). */
+    executable?: boolean;
+}
+/** Convenience builder so adapters read declaratively. */
+declare function artifact(relPath: string, contents: string | Buffer, opts?: {
+    kind?: ArtifactKind;
+    executable?: boolean;
+}): CompiledArtifact;
+
+/**
+ * One plugin's resolved metadata for a catalog entry. Core resolves each
+ * marketplace entry (loads the referenced plugin to learn its name/description)
+ * so the adapter just formats -- it never re-resolves sources itself.
+ */
+interface CatalogEntry {
+    name: string;
+    /** Where the catalog points for this plugin (e.g. "./plugins/<name>"). */
+    source: string;
+    description?: string;
+    version?: string;
+    category?: string;
+    tags?: string[];
+}
+/** A marketplace with every entry already resolved to concrete metadata. */
+interface ResolvedMarketplace {
+    name: string;
+    owner: Owner;
+    description?: string;
+    entries: CatalogEntry[];
+}
+
+interface ToolCall {
+    name: string;
+    args: unknown;
+    result?: unknown;
+    ts: number;
+}
+/** Normalized result of one headless harness run. */
+interface Transcript {
+    finalText: string;
+    toolCalls: ToolCall[];
+    exitCode: number;
+    /** Raw stdout/json for debugging + baselines. */
+    raw: string;
+    /**
+     * True when this harness exposes no structured tool-call trace, so `toolCalls`
+     * is empty by limitation rather than because none happened. `trace` assertions
+     * degrade to `output` assertions in this case (spec §14).
+     */
+    traceUnavailable?: boolean;
+}
+interface RunOptions {
+    prompt: string;
+    cwd: string;
+    config?: Record<string, string>;
+    timeoutMs?: number;
+}
+interface HarnessDriver {
+    readonly target: Target;
+    /** CLI installed AND headless-capable on this machine. Never throws. */
+    available(): Promise<boolean>;
+    run(opts: RunOptions): Promise<Transcript>;
+}
+
+interface ImportOptions {
+    /** Reverse-DNS namespace to assign (native plugins have no Loom namespace). */
+    namespace?: string;
+}
+/** An existing native plugin reverse-compiled into a Loom plugin + its files. */
+interface ImportedPlugin {
+    kind: "plugin";
+    plugin: Plugin;
+    /** Component files to write under the output root (relPath relative to it). */
+    files: CompiledArtifact[];
+}
+/** An existing native marketplace reverse-compiled into a Loom marketplace. */
+interface ImportedMarketplace {
+    kind: "marketplace";
+    marketplace: Marketplace;
+}
+type ImportResult = ImportedPlugin | ImportedMarketplace;
+
+/**
+ * Resolved install directories for one harness at one scope. Category dirs serve
+ * adapters that scatter components into convention dirs; `plugins` serves adapters
+ * that drop a whole compiled plugin tree. `root` is the scope base.
+ */
+interface InstallPaths {
+    root: string;
+    plugins: string;
+    skills: string;
+    mcp: string;
+    agents: string;
+    commands: string;
+    hooks: string;
+    /** Where the per-harness marketplace catalog goes. */
+    catalog: string;
+}
+/** Expand a leading `~` to the user's home directory. */
+declare function expandTilde(p: string): string;
+/** Resolve a path that may be tilde-prefixed or relative to a base. */
+declare function resolveUnder(base: string, p: string): string;
+
+/**
+ * Read-only view of the fetched plugin passed to every adapter call. `read`
+ * returns file bytes from the plugin so adapters can store standards verbatim;
+ * `aliasFor` resolves a component's bare invocation name (spec §9.4).
+ */
+interface PluginCtx {
+    plugin: Plugin;
+    read(relPath: string): Buffer;
+    /** Recursively list files under a plugin directory, as paths relative to the plugin root. */
+    list(relDir: string): string[];
+    aliasFor(componentId: string): string;
+}
+/**
+ * The seam between Loom's canonical model and one harness's native format
+ * (spec §7). Every harness-specific fact lives behind `targetSchema`, so an
+ * upstream schema change is a version bump here, not a change to any plugin.
+ *
+ * A community adapter implements this interface and is registered by its consumer
+ * (the CLI or an embedding app) -- it depends only on @michaelfromyeg/loom-adapter-kit + @michaelfromyeg/loom-schema.
+ */
+interface HarnessAdapter {
+    readonly target: Target;
+    /** This adapter package's own version (versioning axis 3, spec §5). */
+    readonly version: string;
+    /** The harness manifest schema version this adapter emits against. */
+    readonly targetSchema: string;
+    /** Resolve install directories for a scope on this machine. */
+    detect(scope: Scope, cwd: string): InstallPaths;
+    /** Compile one canonical component to its native artifacts. */
+    transform(component: Component, ctx: PluginCtx): CompiledArtifact[];
+    /**
+     * Emit the plugin-level native manifest(s) (e.g. Claude `plugin.json`).
+     * Returns `[]` for directory-convention harnesses that need none.
+     */
+    emitManifest(plugin: Plugin, ctx: PluginCtx): CompiledArtifact[];
+    /**
+     * Emit the harness's native marketplace catalog from a fully-resolved
+     * marketplace. Used for both a curated `marketplace.yaml` (many plugins) and
+     * the single-plugin build (a synthetic one-entry marketplace).
+     */
+    emitCatalog(marketplace: ResolvedMarketplace): CompiledArtifact[];
+    /** Present iff headless eval is supported on this harness. */
+    driver?: HarnessDriver;
+    /**
+     * Reverse-compile an existing native plugin or marketplace in `dir` into the
+     * canonical Loom model, so it can be cross-compiled to the other harnesses
+     * ("federate, don't wall off" applied to assets you already maintain). Returns
+     * null when `dir` is not this harness's format. Present iff the harness supports it.
+     */
+    importNative?(dir: string, opts?: ImportOptions): ImportResult | null;
+}
+
+interface Frontmatter {
+    data: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Split a Markdown document (SKILL.md, agent .md, rules .mdc) into its YAML
+ * frontmatter and body. Returns empty data when there is no frontmatter block.
+ */
+declare function parseFrontmatter(md: string): Frontmatter;
+/** Re-emit a Markdown document with the given frontmatter data and body. */
+declare function withFrontmatter(data: Record<string, unknown>, body: string): string;
+
+export { type ArtifactKind, type CatalogEntry, type CompiledArtifact, type Frontmatter, type HarnessAdapter, type HarnessDriver, type ImportOptions, type ImportResult, type ImportedMarketplace, type ImportedPlugin, type InstallPaths, type PluginCtx, type ResolvedMarketplace, type RunOptions, type ToolCall, type Transcript, artifact, expandTilde, parseFrontmatter, resolveUnder, withFrontmatter };

package/dist/index.js

@@ -0,0 +1,37 @@
+import * as YAML from 'yaml';
+import { homedir } from 'os';
+export { homedir } from 'os';
+import { join, isAbsolute } from 'path';
+
+// src/artifact.ts
+function artifact(relPath, contents, opts = {}) {
+  return { relPath, contents, ...opts };
+}
+var FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function parseFrontmatter(md) {
+  const m = FM_RE.exec(md);
+  if (!m) return { data: {}, body: md };
+  const data = YAML.parse(m[1], { version: "1.2", schema: "core" }) ?? {};
+  return { data, body: md.slice(m[0].length) };
+}
+function withFrontmatter(data, body) {
+  const yaml = YAML.stringify(data, { version: "1.2" }).trimEnd();
+  const cleanBody = body.startsWith("\n") ? body.slice(1) : body;
+  return `---
+${yaml}
+---
+${cleanBody}`;
+}
+function expandTilde(p) {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+function resolveUnder(base, p) {
+  const expanded = expandTilde(p);
+  return isAbsolute(expanded) ? expanded : join(base, expanded);
+}
+
+export { artifact, expandTilde, parseFrontmatter, resolveUnder, withFrontmatter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/artifact.ts","../src/frontmatter.ts","../src/paths.ts"],"names":[],"mappings":";;;;;;AA6BO,SAAS,QAAA,CACd,OAAA,EACA,QAAA,EACA,IAAA,GAAsD,EAAC,EACrC;AAClB,EAAA,OAAO,EAAE,OAAA,EAAS,QAAA,EAAU,GAAG,IAAA,EAAK;AACtC;AC5BA,IAAM,KAAA,GAAQ,mCAAA;AAMP,SAAS,iBAAiB,EAAA,EAAyB;AACxD,EAAA,MAAM,CAAA,GAAI,KAAA,CAAM,IAAA,CAAK,EAAE,CAAA;AACvB,EAAA,IAAI,CAAC,GAAG,OAAO,EAAE,MAAM,EAAC,EAAG,MAAM,EAAA,EAAG;AACpC,EAAA,MAAM,IAAA,GAAa,IAAA,CAAA,KAAA,CAAM,CAAA,CAAE,CAAC,CAAA,EAAG,EAAE,OAAA,EAAS,KAAA,EAAO,MAAA,EAAQ,MAAA,EAAQ,CAAA,IAAK,EAAC;AAIvE,EAAA,OAAO,EAAE,MAAM,IAAA,EAAM,EAAA,CAAG,MAAM,CAAA,CAAE,CAAC,CAAA,CAAE,MAAM,CAAA,EAAE;AAC7C;AAGO,SAAS,eAAA,CAAgB,MAA+B,IAAA,EAAsB;AACnF,EAAA,MAAM,IAAA,GAAY,eAAU,IAAA,EAAM,EAAE,SAAS,KAAA,EAAO,EAAE,OAAA,EAAQ;AAC9D,EAAA,MAAM,SAAA,GAAY,KAAK,UAAA,CAAW,IAAI,IAAI,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA,GAAI,IAAA;AAC1D,EAAA,OAAO,CAAA;AAAA,EAAQ,IAAI;AAAA;AAAA,EAAU,SAAS,CAAA,CAAA;AACxC;ACPO,SAAS,YAAY,CAAA,EAAmB;AAC7C,EAAA,IAAI,CAAA,KAAM,GAAA,EAAK,OAAO,OAAA,EAAQ;AAC9B,EAAA,IAAI,CAAA,CAAE,UAAA,CAAW,IAAI,CAAA,EAAG,OAAO,IAAA,CAAK,OAAA,EAAQ,EAAG,CAAA,CAAE,KAAA,CAAM,CAAC,CAAC,CAAA;AACzD,EAAA,OAAO,CAAA;AACT;AAGO,SAAS,YAAA,CAAa,MAAc,CAAA,EAAmB;AAC5D,EAAA,MAAM,QAAA,GAAW,YAAY,CAAC,CAAA;AAC9B,EAAA,OAAO,WAAW,QAAQ,CAAA,GAAI,QAAA,GAAW,IAAA,CAAK,MAAM,QAAQ,CAAA;AAC9D","file":"index.js","sourcesContent":["/**\n * Classifies an artifact for the trust summary and lockfile grouping. This is\n * metadata only -- it never decides placement (relPath does that).\n */\nexport type ArtifactKind =\n  | \"skill\"\n  | \"mcp\"\n  | \"agent\"\n  | \"command\"\n  | \"hook\"\n  | \"manifest\"\n  | \"catalog\"\n  | \"other\";\n\n/**\n * One file an adapter emits. `relPath` is relative to the native plugin/output\n * root the adapter targets (e.g. \"skills/greet/SKILL.md\",\n * \".claude-plugin/plugin.json\"). Core decides the absolute base per build mode\n * and scope; the adapter never hard-codes absolute paths.\n */\nexport interface CompiledArtifact {\n  relPath: string;\n  contents: string | Buffer;\n  kind?: ArtifactKind;\n  /** Passthrough executables. Placed DISABLED; activation is a separate opt-in (spec §11). */\n  executable?: boolean;\n}\n\n/** Convenience builder so adapters read declaratively. */\nexport function artifact(\n  relPath: string,\n  contents: string | Buffer,\n  opts: { kind?: ArtifactKind; executable?: boolean } = {},\n): CompiledArtifact {\n  return { relPath, contents, ...opts };\n}\n","import * as YAML from \"yaml\";\n\nexport interface Frontmatter {\n  data: Record<string, unknown>;\n  body: string;\n}\n\nconst FM_RE = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n?/;\n\n/**\n * Split a Markdown document (SKILL.md, agent .md, rules .mdc) into its YAML\n * frontmatter and body. Returns empty data when there is no frontmatter block.\n */\nexport function parseFrontmatter(md: string): Frontmatter {\n  const m = FM_RE.exec(md);\n  if (!m) return { data: {}, body: md };\n  const data = (YAML.parse(m[1], { version: \"1.2\", schema: \"core\" }) ?? {}) as Record<\n    string,\n    unknown\n  >;\n  return { data, body: md.slice(m[0].length) };\n}\n\n/** Re-emit a Markdown document with the given frontmatter data and body. */\nexport function withFrontmatter(data: Record<string, unknown>, body: string): string {\n  const yaml = YAML.stringify(data, { version: \"1.2\" }).trimEnd();\n  const cleanBody = body.startsWith(\"\\n\") ? body.slice(1) : body;\n  return `---\\n${yaml}\\n---\\n${cleanBody}`;\n}\n","import { homedir } from \"node:os\";\nimport { isAbsolute, join } from \"node:path\";\n\n/**\n * Resolved install directories for one harness at one scope. Category dirs serve\n * adapters that scatter components into convention dirs; `plugins` serves adapters\n * that drop a whole compiled plugin tree. `root` is the scope base.\n */\nexport interface InstallPaths {\n  root: string;\n  plugins: string;\n  skills: string;\n  mcp: string;\n  agents: string;\n  commands: string;\n  hooks: string;\n  /** Where the per-harness marketplace catalog goes. */\n  catalog: string;\n}\n\n/** Expand a leading `~` to the user's home directory. */\nexport function expandTilde(p: string): string {\n  if (p === \"~\") return homedir();\n  if (p.startsWith(\"~/\")) return join(homedir(), p.slice(2));\n  return p;\n}\n\n/** Resolve a path that may be tilde-prefixed or relative to a base. */\nexport function resolveUnder(base: string, p: string): string {\n  const expanded = expandTilde(p);\n  return isAbsolute(expanded) ? expanded : join(base, expanded);\n}\n\nexport { homedir };\n"]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@michaelfromyeg/loom-adapter-kit",
+  "version": "0.1.0",
+  "description": "Public HarnessAdapter / HarnessDriver interfaces and helpers. The contract a community adapter implements.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "yaml": "^2.6.1",
+    "@michaelfromyeg/loom-schema": "0.1.0"
+  },
+  "license": "MIT",
+  "author": "Michael DeMarco",
+  "homepage": "https://github.com/michaelfromyeg/loom#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelfromyeg/loom.git",
+    "directory": "packages/adapter-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/michaelfromyeg/loom/issues"
+  },
+  "keywords": [
+    "loom",
+    "coding-agent",
+    "ai-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "copilot",
+    "opencode",
+    "mcp",
+    "plugin",
+    "skill",
+    "compiler"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}