cmx-core 0.2.0

package/README.md

@@ -0,0 +1,66 @@
+# cmx-core (TypeScript)
+
+Native Bun/TypeScript port of the `cmx-core` skill-install surface. Published to
+npm as `cmx-core`; the source lives in the `cmx-core-ts/` directory of the
+[context-mixer2](https://github.com/svetzal/context-mixer2) repo, alongside the
+Rust reference and the shared conformance fixtures.
+
+It exposes the same embeddable shape as the Rust library:
+
+- `ToolIdentity`
+- `BundledSkill`
+- `SkillInstaller`
+- `ConfigPaths`
+- `NodeFilesystem`
+- `SystemClock`
+
+The library scope is bundled skill installation only. It implements:
+
+- `plan`
+- `apply`
+- `status`
+- `remove`
+
+Example:
+
+```ts
+import {
+  BundledSkill,
+  ConfigPaths,
+  NodeFilesystem,
+  SkillInstaller,
+  SystemClock,
+  ToolIdentity,
+} from "cmx-core";
+
+const installer = new SkillInstaller(new ToolIdentity("mytool", "1.2.0"));
+const skill = BundledSkill.singleMd("---\nname: mytool\n---\n# My skill\n");
+const context = {
+  fs: new NodeFilesystem(),
+  clock: new SystemClock(),
+  paths: ConfigPaths.fromEnv("claude"),
+};
+
+const plan = await installer.plan(skill, "global", false, context);
+const report = await installer.apply(skill, plan, context);
+```
+
+## Conformance
+
+Run the full fixture suite from this package directory:
+
+```bash
+bun install
+bun test
+bunx tsc --noEmit
+bunx biome check .
+```
+
+The test harness consumes the committed fixtures in `../cmx-core/conformance/` and checks:
+
+- checksum parity
+- byte-exact frontmatter reconciliation
+- version-guard decisions
+- platform paths and lock names
+- target resolution
+- end-to-end install behavior, tree snapshots, lock JSON values, and normalized reports

package/dist/checksum.d.ts

@@ -0,0 +1,14 @@
+import type { Filesystem } from "./gateway.js";
+export interface ChecksumEntry {
+    relPath: string;
+    bytes: Uint8Array;
+}
+export declare const normalizeRelPath: (relPath: string) => string;
+export declare const relPathComponents: (relPath: string) => string[];
+export declare const relPathKey: (relPath: string) => string;
+export declare const isCanonicalRelPath: (relPath: string) => boolean;
+export declare const checksumInMemory: (entries: Iterable<{
+    relPath: string;
+    bytes: Uint8Array;
+}>) => string;
+export declare const checksumDir: (rootDir: string, fs: Filesystem) => Promise<string>;

package/dist/checksum.js

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import path from "node:path/posix";
+const transientNames = new Set(["node_modules", "__pycache__", ".git", ".DS_Store"]);
+const comparePathKeys = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export const normalizeRelPath = (relPath) => relPath.replaceAll("\\", "/").replace(/^\.\/+/u, "");
+export const relPathComponents = (relPath) => normalizeRelPath(relPath)
+    .split("/")
+    .filter((component) => component.length > 0);
+export const relPathKey = (relPath) => relPathComponents(relPath).join("/");
+export const isCanonicalRelPath = (relPath) => relPathComponents(relPath).every((component) => {
+    if (component.startsWith(".")) {
+        return false;
+    }
+    if (transientNames.has(component)) {
+        return false;
+    }
+    return !component.toLowerCase().endsWith(".pyc");
+});
+export const checksumInMemory = (entries) => {
+    const hasher = createHash("sha256");
+    for (const entry of entries) {
+        hasher.update(relPathKey(entry.relPath), "utf8");
+        hasher.update(entry.bytes);
+    }
+    return `sha256:${hasher.digest("hex")}`;
+};
+const collectFilesRecursive = async (rootDir, currentDir, fs) => {
+    if (!(await fs.exists(currentDir))) {
+        return [];
+    }
+    const entries = await fs.listDir(currentDir);
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(currentDir, entry.fileName);
+        if (entry.isDirectory) {
+            files.push(...(await collectFilesRecursive(rootDir, absolutePath, fs)));
+            continue;
+        }
+        const relPath = path.relative(rootDir, absolutePath);
+        files.push({
+            relPath,
+            bytes: await fs.read(absolutePath),
+        });
+    }
+    return files;
+};
+export const checksumDir = async (rootDir, fs) => {
+    const entries = await collectFilesRecursive(rootDir, rootDir, fs);
+    const canonicalEntries = entries
+        .filter((entry) => isCanonicalRelPath(entry.relPath))
+        .sort((left, right) => comparePathKeys(relPathKey(left.relPath), relPathKey(right.relPath)));
+    return checksumInMemory(canonicalEntries);
+};

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+import type { Filesystem } from "./gateway.js";
+import type { ConfigPaths } from "./paths.js";
+import { type Platform } from "./platform.js";
+import { type CmxConfig, type SourceEntry, type SourcesFile } from "./types.js";
+export declare const loadSources: (fs: Filesystem, paths: ConfigPaths) => Promise<SourcesFile>;
+export declare const saveSources: (sources: SourcesFile, fs: Filesystem, paths: ConfigPaths) => Promise<void>;
+export declare const mutateSources: <T>(fs: Filesystem, paths: ConfigPaths, mutator: (sources: SourcesFile) => T | Promise<T>) => Promise<T>;
+export declare const loadConfig: (fs: Filesystem, paths: ConfigPaths) => Promise<CmxConfig>;
+export declare const saveConfig: (config: CmxConfig, fs: Filesystem, paths: ConfigPaths) => Promise<void>;
+export declare const managedPlatforms: (fs: Filesystem, paths: ConfigPaths) => Promise<Platform[] | undefined>;
+export declare const managedOrAllPlatforms: (fs: Filesystem, paths: ConfigPaths) => Promise<Platform[]>;
+export declare const resolveArtifactHome: (config: CmxConfig, paths: ConfigPaths) => string;
+export declare const resolveLocalPath: (entry: SourceEntry) => string;

package/dist/config.js

@@ -0,0 +1,45 @@
+import { loadJson, saveJson } from "./json-file.js";
+import { isPlatform, PLATFORM_VALUES } from "./platform.js";
+import { defaultCmxConfig, defaultSourcesFile, } from "./types.js";
+const normalizeConfig = (config) => ({
+    version: config.version ?? 1,
+    llm: config.llm ?? defaultCmxConfig().llm,
+    home: config.home,
+    external: config.external ?? [],
+    platforms: (config.platforms ?? []).filter(isPlatform),
+});
+const normalizeSources = (sources) => ({
+    version: sources.version ?? 1,
+    sources: sources.sources ?? {},
+});
+export const loadSources = async (fs, paths) => normalizeSources(await loadJson(paths.sourcesPath(), fs, defaultSourcesFile));
+export const saveSources = async (sources, fs, paths) => {
+    await saveJson(normalizeSources(sources), paths.sourcesPath(), fs);
+};
+export const mutateSources = async (fs, paths, mutator) => {
+    const sources = await loadSources(fs, paths);
+    const result = await mutator(sources);
+    await saveSources(sources, fs, paths);
+    return result;
+};
+export const loadConfig = async (fs, paths) => normalizeConfig(await loadJson(paths.configPath(), fs, defaultCmxConfig));
+export const saveConfig = async (config, fs, paths) => {
+    await saveJson(normalizeConfig(config), paths.configPath(), fs);
+};
+export const managedPlatforms = async (fs, paths) => {
+    const config = await loadConfig(fs, paths);
+    return config.platforms.length > 0 ? [...config.platforms] : undefined;
+};
+export const managedOrAllPlatforms = async (fs, paths) => (await managedPlatforms(fs, paths)) ?? [...PLATFORM_VALUES];
+export const resolveArtifactHome = (config, paths) => config.home ?? paths.defaultArtifactHome();
+export const resolveLocalPath = (entry) => {
+    if (entry.type === "local" && entry.path !== undefined) {
+        return entry.path;
+    }
+    if (entry.type === "git" && entry.local_clone !== undefined) {
+        return entry.local_clone;
+    }
+    throw new Error(entry.type === "local"
+        ? "Local source has no path configured"
+        : "Git source has no local clone path configured");
+};

package/dist/frontmatter.d.ts

@@ -0,0 +1,3 @@
+import type { SkillFile } from "./skill-fs.js";
+export declare const reconcileSkillVersion: (files: readonly SkillFile[], version: string) => SkillFile[];
+export declare const setMetadataVersion: (content: string, version: string) => string;

package/dist/frontmatter.js

@@ -0,0 +1,105 @@
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+export const reconcileSkillVersion = (files, version) => files.map((file) => {
+    if (file.relPath !== "SKILL.md") {
+        return { ...file, bytes: new Uint8Array(file.bytes) };
+    }
+    const content = textDecoder.decode(file.bytes);
+    const reconciled = setMetadataVersion(content, version);
+    return {
+        relPath: file.relPath,
+        bytes: textEncoder.encode(reconciled),
+    };
+});
+export const setMetadataVersion = (content, version) => {
+    const value = `"${version}"`;
+    const open = content.startsWith("---\n")
+        ? "---\n"
+        : content.startsWith("---\r\n")
+            ? "---\r\n"
+            : undefined;
+    if (open === undefined) {
+        return content;
+    }
+    const afterOpen = content.slice(open.length);
+    const fenceStart = findClosingFence(afterOpen);
+    if (fenceStart === undefined) {
+        return content;
+    }
+    const inner = afterOpen.slice(0, fenceStart);
+    const closingAndRest = afterOpen.slice(fenceStart);
+    return `${open}${reconcileInner(inner, value)}${closingAndRest}`;
+};
+const findClosingFence = (afterOpen) => {
+    let lineStart = 0;
+    while (lineStart <= afterOpen.length) {
+        const rest = afterOpen.slice(lineStart);
+        const newlineIndex = rest.indexOf("\n");
+        const hasNewline = newlineIndex !== -1;
+        const line = hasNewline ? rest.slice(0, newlineIndex) : rest;
+        if (line.replace(/\r$/u, "") === "---") {
+            return lineStart;
+        }
+        if (!hasNewline) {
+            return undefined;
+        }
+        lineStart += line.length + 1;
+    }
+    return undefined;
+};
+const reconcileInner = (inner, value) => {
+    const lines = inner.match(/[^\n]*\n|[^\n]+/gu) ?? [];
+    const withoutTopLevelVersion = lines.filter((line) => !isTopLevelKey(line, "version"));
+    const metadataIndex = withoutTopLevelVersion.findIndex((line) => isTopLevelKey(line, "metadata"));
+    if (metadataIndex === -1) {
+        ensureTrailingNewline(withoutTopLevelVersion);
+        withoutTopLevelVersion.push("metadata:\n");
+        withoutTopLevelVersion.push(`  version: ${value}\n`);
+        return withoutTopLevelVersion.join("");
+    }
+    setVersionInMetadataBlock(withoutTopLevelVersion, metadataIndex, value);
+    return withoutTopLevelVersion.join("");
+};
+const setVersionInMetadataBlock = (lines, metadataIndex, value) => {
+    let firstChildIndent;
+    let versionIndex;
+    for (let index = metadataIndex + 1; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const trimmed = line.replace(/[\n\r]+$/u, "");
+        if (trimmed.trim().length === 0) {
+            continue;
+        }
+        const indent = leadingWhitespace(trimmed);
+        if (indent.length === 0) {
+            break;
+        }
+        firstChildIndent ??= indent;
+        if (trimmed.trimStart().startsWith("version:")) {
+            versionIndex = index;
+            break;
+        }
+    }
+    if (versionIndex !== undefined) {
+        const indent = leadingWhitespace(lines[versionIndex] ?? "");
+        lines[versionIndex] = `${indent}version: ${value}\n`;
+        return;
+    }
+    lines.splice(metadataIndex + 1, 0, `${firstChildIndent ?? "  "}version: ${value}\n`);
+};
+const isTopLevelKey = (line, key) => {
+    const trimmed = line.replace(/[\n\r]+$/u, "");
+    return (!line.startsWith(" ") &&
+        !line.startsWith("\t") &&
+        trimmed.startsWith(key) &&
+        trimmed.slice(key.length).startsWith(":"));
+};
+const leadingWhitespace = (value) => value.match(/^[ \t]*/u)?.[0] ?? "";
+const ensureTrailingNewline = (lines) => {
+    if (lines.length === 0) {
+        return;
+    }
+    const lastIndex = lines.length - 1;
+    if (!lines[lastIndex]?.endsWith("\n")) {
+        lines[lastIndex] = `${lines[lastIndex] ?? ""}\n`;
+    }
+};

package/dist/gateway.d.ts

@@ -0,0 +1,34 @@
+export interface DirEntry {
+    fileName: string;
+    isDirectory: boolean;
+}
+export interface Filesystem {
+    exists(path: string): Promise<boolean>;
+    read(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    writeBytes(path: string, content: Uint8Array): Promise<void>;
+    createDirAll(path: string): Promise<void>;
+    removeDirAll(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    listDir(path: string): Promise<DirEntry[]>;
+    isDirectory(path: string): Promise<boolean>;
+}
+export interface Clock {
+    now(): Date;
+}
+export declare class SystemClock implements Clock {
+    now(): Date;
+}
+export declare class NodeFilesystem implements Filesystem {
+    exists(targetPath: string): Promise<boolean>;
+    read(targetPath: string): Promise<Uint8Array>;
+    readText(targetPath: string): Promise<string>;
+    write(targetPath: string, content: string): Promise<void>;
+    writeBytes(targetPath: string, content: Uint8Array): Promise<void>;
+    createDirAll(targetPath: string): Promise<void>;
+    removeDirAll(targetPath: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    listDir(targetPath: string): Promise<DirEntry[]>;
+    isDirectory(targetPath: string): Promise<boolean>;
+}

package/dist/gateway.js

@@ -0,0 +1,53 @@
+import { access, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+export class SystemClock {
+    now() {
+        return new Date();
+    }
+}
+export class NodeFilesystem {
+    async exists(targetPath) {
+        try {
+            await access(targetPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async read(targetPath) {
+        return await readFile(targetPath);
+    }
+    async readText(targetPath) {
+        return await readFile(targetPath, "utf8");
+    }
+    async write(targetPath, content) {
+        await writeFile(targetPath, content, "utf8");
+    }
+    async writeBytes(targetPath, content) {
+        await writeFile(targetPath, content);
+    }
+    async createDirAll(targetPath) {
+        await mkdir(targetPath, { recursive: true });
+    }
+    async removeDirAll(targetPath) {
+        await rm(targetPath, { recursive: true, force: true });
+    }
+    async rename(from, to) {
+        await rename(from, to);
+    }
+    async listDir(targetPath) {
+        const entries = await readdir(targetPath, { withFileTypes: true });
+        return entries.map((entry) => ({
+            fileName: entry.name,
+            isDirectory: entry.isDirectory(),
+        }));
+    }
+    async isDirectory(targetPath) {
+        try {
+            return (await stat(targetPath)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./checksum.js";
+export * from "./config.js";
+export * from "./frontmatter.js";
+export * from "./gateway.js";
+export * from "./json-file.js";
+export * from "./lockfile.js";
+export * from "./paths.js";
+export * from "./platform.js";
+export * from "./skill-fs.js";
+export * from "./skill-installer.js";
+export * from "./targets.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./checksum.js";
+export * from "./config.js";
+export * from "./frontmatter.js";
+export * from "./gateway.js";
+export * from "./json-file.js";
+export * from "./lockfile.js";
+export * from "./paths.js";
+export * from "./platform.js";
+export * from "./skill-fs.js";
+export * from "./skill-installer.js";
+export * from "./targets.js";
+export * from "./types.js";

package/dist/json-file.d.ts

@@ -0,0 +1,4 @@
+import type { Filesystem } from "./gateway.js";
+export declare const tmpPath: (targetPath: string) => string;
+export declare const loadJson: <T>(targetPath: string, fs: Filesystem, defaultValue: () => T) => Promise<T>;
+export declare const saveJson: <T>(value: T, targetPath: string, fs: Filesystem) => Promise<void>;

package/dist/json-file.js

@@ -0,0 +1,33 @@
+import path from "node:path/posix";
+const sortJsonValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(sortJsonValue);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => [key, sortJsonValue(nested)]));
+    }
+    return value;
+};
+export const tmpPath = (targetPath) => path.join(path.dirname(targetPath), `${path.basename(targetPath)}.tmp`);
+export const loadJson = async (targetPath, fs, defaultValue) => {
+    if (!(await fs.exists(targetPath))) {
+        return defaultValue();
+    }
+    const content = await fs.readText(targetPath);
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${targetPath}`, { cause: error });
+    }
+};
+export const saveJson = async (value, targetPath, fs) => {
+    const parent = path.dirname(targetPath);
+    await fs.createDirAll(parent);
+    const content = `${JSON.stringify(sortJsonValue(value), null, 2)}\n`;
+    const tempPath = tmpPath(targetPath);
+    await fs.write(tempPath, content);
+    await fs.rename(tempPath, targetPath);
+};

package/dist/lockfile.d.ts

@@ -0,0 +1,8 @@
+import type { Filesystem } from "./gateway.js";
+import type { ConfigPaths } from "./paths.js";
+import { type InstallScope, type LockFile } from "./types.js";
+export declare const loadLockFileFrom: (targetPath: string, fs: Filesystem) => Promise<LockFile>;
+export declare const saveLockFileTo: (lockFile: LockFile, targetPath: string, fs: Filesystem) => Promise<void>;
+export declare const loadLockFile: (scope: InstallScope, fs: Filesystem, paths: ConfigPaths) => Promise<LockFile>;
+export declare const saveLockFile: (lockFile: LockFile, scope: InstallScope, fs: Filesystem, paths: ConfigPaths) => Promise<void>;
+export declare const mutateLockFile: <T>(scope: InstallScope, fs: Filesystem, paths: ConfigPaths, mutator: (lockFile: LockFile) => T | Promise<T>) => Promise<T>;

package/dist/lockfile.js

@@ -0,0 +1,33 @@
+import { loadJson, saveJson } from "./json-file.js";
+import { defaultLockFile } from "./types.js";
+const normalizeLockEntry = (entry) => ({
+    type: entry.type,
+    version: entry.version,
+    installed_at: entry.installed_at,
+    source: {
+        repo: entry.source.repo,
+        path: entry.source.path,
+    },
+    source_checksum: entry.source_checksum,
+    installed_checksum: entry.installed_checksum,
+});
+const normalizeLockFile = (lockFile) => ({
+    version: lockFile.version ?? 1,
+    packages: Object.fromEntries(Object.entries(lockFile.packages ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, entry]) => [name, normalizeLockEntry(entry)])),
+});
+export const loadLockFileFrom = async (targetPath, fs) => normalizeLockFile(await loadJson(targetPath, fs, defaultLockFile));
+export const saveLockFileTo = async (lockFile, targetPath, fs) => {
+    await saveJson(normalizeLockFile(lockFile), targetPath, fs);
+};
+export const loadLockFile = async (scope, fs, paths) => await loadLockFileFrom(paths.lockPath(scope), fs);
+export const saveLockFile = async (lockFile, scope, fs, paths) => {
+    await saveLockFileTo(lockFile, paths.lockPath(scope), fs);
+};
+export const mutateLockFile = async (scope, fs, paths, mutator) => {
+    const lockFile = await loadLockFile(scope, fs, paths);
+    const result = await mutator(lockFile);
+    await saveLockFile(lockFile, scope, fs, paths);
+    return result;
+};

package/dist/paths.d.ts

@@ -0,0 +1,26 @@
+import { type Platform } from "./platform.js";
+import { type ArtifactKind, type InstallScope } from "./types.js";
+export declare class ConfigPaths {
+    readonly configDir: string;
+    readonly homeDir: string;
+    readonly platform: Platform;
+    readonly projectRoot: string;
+    constructor(args: {
+        configDir: string;
+        homeDir: string;
+        platform: Platform;
+        projectRoot: string;
+    });
+    static fromEnv(platform: Platform, projectRoot?: string): ConfigPaths;
+    withPlatform(platform: Platform): ConfigPaths;
+    sourcesPath(): string;
+    gitClonesDir(): string;
+    configPath(): string;
+    defaultArtifactHome(): string;
+    setsPath(scope: InstallScope): string;
+    lockPath(scope: InstallScope): string;
+    installDir(kind: ArtifactKind, scope: InstallScope): string | null;
+    installedArtifactPath(kind: ArtifactKind, name: string, scope: InstallScope): string | null;
+    requireInstallDir(kind: ArtifactKind, scope: InstallScope): string;
+    ensureSupports(kind: ArtifactKind): void;
+}

package/dist/paths.js

@@ -0,0 +1,84 @@
+import os from "node:os";
+import path from "node:path/posix";
+import { agentExtension, lockFileName, platformInstallSubpath, supportsArtifact, } from "./platform.js";
+import { installedArtifactPath } from "./types.js";
+export class ConfigPaths {
+    configDir;
+    homeDir;
+    platform;
+    projectRoot;
+    constructor(args) {
+        this.configDir = args.configDir;
+        this.homeDir = args.homeDir;
+        this.platform = args.platform;
+        this.projectRoot = args.projectRoot;
+    }
+    static fromEnv(platform, projectRoot = process.cwd()) {
+        const homeDir = os.homedir().replaceAll("\\", "/");
+        return new ConfigPaths({
+            configDir: path.join(homeDir, ".config", "context-mixer"),
+            homeDir,
+            platform,
+            projectRoot: projectRoot.replaceAll("\\", "/"),
+        });
+    }
+    withPlatform(platform) {
+        return new ConfigPaths({
+            configDir: this.configDir,
+            homeDir: this.homeDir,
+            platform,
+            projectRoot: this.projectRoot,
+        });
+    }
+    sourcesPath() {
+        return path.join(this.configDir, "sources.json");
+    }
+    gitClonesDir() {
+        return path.join(this.configDir, "sources");
+    }
+    configPath() {
+        return path.join(this.configDir, "config.json");
+    }
+    defaultArtifactHome() {
+        return path.join(this.configDir, "home");
+    }
+    setsPath(scope) {
+        return scope === "local"
+            ? path.join(this.projectRoot, ".context-mixer", "sets.json")
+            : path.join(this.configDir, "sets.json");
+    }
+    lockPath(scope) {
+        const fileName = lockFileName(this.platform);
+        return scope === "local"
+            ? path.join(this.projectRoot, ".context-mixer", fileName)
+            : path.join(this.configDir, fileName);
+    }
+    installDir(kind, scope) {
+        const subpath = platformInstallSubpath(this.platform, kind, scope);
+        if (subpath === null) {
+            return null;
+        }
+        return scope === "local"
+            ? path.join(this.projectRoot, subpath)
+            : path.join(this.homeDir, subpath);
+    }
+    installedArtifactPath(kind, name, scope) {
+        const installDir = this.installDir(kind, scope);
+        if (installDir === null) {
+            return null;
+        }
+        return installedArtifactPath(kind, name, installDir, agentExtension(this.platform));
+    }
+    requireInstallDir(kind, scope) {
+        const installDir = this.installDir(kind, scope);
+        if (installDir === null) {
+            throw new Error(`The ${this.platform} platform does not support ${kind}s. ${this.platform} has no native ${kind} concept.`);
+        }
+        return installDir;
+    }
+    ensureSupports(kind) {
+        if (!supportsArtifact(this.platform, kind)) {
+            throw new Error(`The ${this.platform} platform does not support ${kind}s. ${this.platform} has no native ${kind} concept.`);
+        }
+    }
+}

package/dist/platform.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactKind, InstallScope } from "./types.js";
+export declare const PLATFORM_VALUES: readonly ["claude", "copilot", "cursor", "windsurf", "gemini", "opencode", "codex", "pi", "crush", "amp", "zed", "openhands", "hermes", "devin"];
+export type Platform = (typeof PLATFORM_VALUES)[number];
+export declare const isPlatform: (value: string) => value is Platform;
+export declare const platformSlug: (platform: Platform) => string;
+export declare const platformInstallSubpath: (platform: Platform, kind: ArtifactKind, scope: InstallScope) => string | null;
+export declare const supportsArtifact: (platform: Platform, kind: ArtifactKind) => boolean;
+export declare const agentExtension: (platform: Platform) => "md" | "toml";
+export declare const lockFileName: (platform: Platform) => string;
+export declare const platformsLabel: (platforms: readonly Platform[]) => string;