@evo-dev/core 0.0.1-alpha

package/src/assets/scanner.ts

@@ -0,0 +1,189 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { EvoDevAssetError } from "./errors.ts";
+import {
+  type AgentManifest,
+  type SkillManifest,
+  parseAgentManifest,
+  parseSkillManifest,
+} from "./manifest.ts";
+
+export interface AssetScannerPaths {
+  skillsDir: string;
+  agentsDir: string;
+}
+
+export interface ScannedAsset<TManifest extends SkillManifest | AgentManifest> {
+  manifest: TManifest;
+  manifestPath: string;
+  entryPath: string;
+  assetDir: string;
+  registryKey: string;
+}
+
+export interface AssetScanResult {
+  skills: ScannedAsset<SkillManifest>[];
+  agents: ScannedAsset<AgentManifest>[];
+}
+
+export async function scanAssets(paths: AssetScannerPaths): Promise<AssetScanResult> {
+  const [skills, agents] = await Promise.all([
+    scanSkillAssets(paths.skillsDir),
+    scanAgentAssets(paths.agentsDir),
+  ]);
+
+  return { skills, agents };
+}
+
+export async function scanSkillAssets(skillsDir: string): Promise<ScannedAsset<SkillManifest>[]> {
+  return scanAssetKind(skillsDir, parseSkillManifest);
+}
+
+export async function scanAgentAssets(agentsDir: string): Promise<ScannedAsset<AgentManifest>[]> {
+  return scanAssetKind(agentsDir, parseAgentManifest);
+}
+
+async function scanAssetKind<TManifest extends SkillManifest | AgentManifest>(
+  rootDir: string,
+  parseManifest: (value: unknown) => TManifest,
+): Promise<ScannedAsset<TManifest>[]> {
+  if (!(await pathExists(rootDir))) {
+    return [];
+  }
+
+  const manifestPaths = await findManifestFiles(rootDir);
+  const assets = await Promise.all(
+    manifestPaths.map((manifestPath) => readScannedAsset(rootDir, manifestPath, parseManifest)),
+  );
+
+  return assets.sort((left, right) => left.registryKey.localeCompare(right.registryKey));
+}
+
+async function findManifestFiles(rootDir: string): Promise<string[]> {
+  const entries = await readdir(rootDir, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const entryPath = join(rootDir, entry.name);
+
+      if (entry.isDirectory()) {
+        return findManifestFiles(entryPath);
+      }
+
+      if (entry.isFile() && entry.name === "manifest.json") {
+        return [entryPath];
+      }
+
+      return [];
+    }),
+  );
+
+  return nested.flat();
+}
+
+async function readScannedAsset<TManifest extends SkillManifest | AgentManifest>(
+  rootDir: string,
+  manifestPath: string,
+  parseManifest: (value: unknown) => TManifest,
+): Promise<ScannedAsset<TManifest>> {
+  const json = await readManifestJson(manifestPath);
+  const manifest = parseManifestWithPath(json, manifestPath, parseManifest);
+  const assetDir = manifestPath.slice(0, -"/manifest.json".length);
+  const entryPath = join(assetDir, manifest.entry);
+
+  if (!(await isFile(entryPath))) {
+    throw new EvoDevAssetError(`Asset entry file not found for ${manifest.id}`, entryPath);
+  }
+
+  const registryKey = createRegistryKey(rootDir, assetDir, manifest);
+  return {
+    manifest,
+    manifestPath,
+    entryPath,
+    assetDir,
+    registryKey,
+  };
+}
+
+async function readManifestJson(manifestPath: string): Promise<unknown> {
+  let raw: string;
+
+  try {
+    raw = await readFile(manifestPath, "utf8");
+  } catch (error) {
+    throw new EvoDevAssetError(`Cannot read manifest (${describeFileError(error)})`, manifestPath);
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new EvoDevAssetError(`Invalid manifest JSON (${describeFileError(error)})`, manifestPath);
+  }
+}
+
+function parseManifestWithPath<TManifest extends SkillManifest | AgentManifest>(
+  json: unknown,
+  manifestPath: string,
+  parseManifest: (value: unknown) => TManifest,
+): TManifest {
+  try {
+    return parseManifest(json);
+  } catch (error) {
+    if (error instanceof EvoDevAssetError) {
+      throw new EvoDevAssetError(error.message, manifestPath);
+    }
+
+    throw error;
+  }
+}
+
+function createRegistryKey(
+  rootDir: string,
+  assetDir: string,
+  manifest: SkillManifest | AgentManifest,
+): string {
+  const relativeDir = relative(rootDir, assetDir).replaceAll("\\", "/");
+
+  if (relativeDir === "" || relativeDir === manifest.id) {
+    return manifest.id;
+  }
+
+  return relativeDir;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    const fileStat = await stat(path);
+    return fileStat.isFile();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function describeFileError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/config/errors.ts

@@ -0,0 +1,21 @@
+export class EvoDevConfigError extends Error {
+  constructor(
+    message: string,
+    readonly filePath?: string,
+  ) {
+    super(filePath ? `${message}: ${filePath}` : message);
+    this.name = "EvoDevConfigError";
+  }
+}
+
+export function describeType(value: unknown): string {
+  if (value === null) {
+    return "null";
+  }
+
+  if (Array.isArray(value)) {
+    return "array";
+  }
+
+  return typeof value;
+}

package/src/config/index.ts

@@ -0,0 +1,26 @@
+export { EvoDevConfigError } from "./errors.ts";
+export { type EvoDevPaths, resolveEvoDevPaths } from "./paths.ts";
+export {
+  type EvoDevRegistry,
+  type RegisteredAsset,
+  createDefaultRegistry,
+  parseRegistry,
+} from "./registry.ts";
+export {
+  type EvoDevSettings,
+  type PluginSettings,
+  type SettingsInput,
+  createDefaultSettings,
+  mergeSettings,
+  parseSettings,
+} from "./settings.ts";
+export {
+  type InstallState,
+  type PluginSyncState,
+  type SyncState,
+  createDefaultInstallState,
+  createDefaultSyncState,
+  parseInstallState,
+  parseSyncState,
+} from "./state.ts";
+export { type CoreConfigStore, createCoreConfigStore, initializeCoreConfig } from "./store.ts";

package/src/config/paths.ts

@@ -0,0 +1,43 @@
+export interface EvoDevPaths {
+  homeDir: string;
+  rootDir: string;
+  settingsPath: string;
+  registryPath: string;
+  stateDir: string;
+  installStatePath: string;
+  syncStatePath: string;
+}
+
+export function resolveEvoDevPaths(homeDir: string = getHomeDir()): EvoDevPaths {
+  const normalizedHome = stripTrailingSlash(homeDir);
+  const rootDir = `${normalizedHome}/.evodev`;
+  const stateDir = `${rootDir}/state`;
+
+  return {
+    homeDir: normalizedHome,
+    rootDir,
+    settingsPath: `${rootDir}/settings.json`,
+    registryPath: `${rootDir}/registry.json`,
+    stateDir,
+    installStatePath: `${stateDir}/install.json`,
+    syncStatePath: `${stateDir}/sync.json`,
+  };
+}
+
+function getHomeDir(): string {
+  const home = process.env.HOME;
+
+  if (home === undefined || home.trim() === "") {
+    throw new Error("Cannot resolve home directory: HOME is not set");
+  }
+
+  return home;
+}
+
+function stripTrailingSlash(path: string): string {
+  if (path === "/") {
+    return path;
+  }
+
+  return path.replace(/\/+$/, "");
+}

package/src/config/registry.ts

@@ -0,0 +1,84 @@
+import { EvoDevConfigError, describeType } from "./errors.ts";
+
+export interface RegisteredAsset {
+  version: string;
+  source: "builtin" | "user";
+  targets: string[];
+}
+
+export interface EvoDevRegistry {
+  version: 1;
+  skills: Record<string, RegisteredAsset>;
+  agents: Record<string, RegisteredAsset>;
+}
+
+export function createDefaultRegistry(): EvoDevRegistry {
+  return {
+    version: 1,
+    skills: {},
+    agents: {},
+  };
+}
+
+export function parseRegistry(value: unknown): EvoDevRegistry {
+  const root = expectRecord(value, "registry");
+
+  if (root.version !== 1) {
+    throw new EvoDevConfigError("Invalid registry.version; expected 1");
+  }
+
+  return {
+    version: 1,
+    skills: parseAssetMap(root.skills, "registry.skills"),
+    agents: parseAssetMap(root.agents, "registry.agents"),
+  };
+}
+
+function parseAssetMap(value: unknown, path: string): Record<string, RegisteredAsset> {
+  const input = expectRecord(value, path);
+  const output: Record<string, RegisteredAsset> = {};
+
+  for (const [assetId, asset] of Object.entries(input)) {
+    output[assetId] = parseRegisteredAsset(asset, `${path}.${assetId}`);
+  }
+
+  return output;
+}
+
+function parseRegisteredAsset(value: unknown, path: string): RegisteredAsset {
+  const input = expectRecord(value, path);
+  const source = input.source;
+
+  if (source !== "builtin" && source !== "user") {
+    throw new EvoDevConfigError(`Invalid ${path}.source; expected builtin or user`);
+  }
+
+  if (
+    !Array.isArray(input.targets) ||
+    !input.targets.every((target) => typeof target === "string")
+  ) {
+    throw new EvoDevConfigError(`Invalid ${path}.targets; expected string array`);
+  }
+
+  return {
+    version: expectString(input.version, `${path}.version`),
+    source,
+    targets: [...input.targets],
+  };
+}
+
+function expectRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected object, got ${describeType(value)}`);
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function expectString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected non-empty string`);
+  }
+
+  return value;
+}

package/src/config/settings.ts

@@ -0,0 +1,212 @@
+import { type HookSettings, createDefaultHookSettings, parseHookSettings } from "../hooks/index.ts";
+import { EvoDevConfigError, describeType } from "./errors.ts";
+
+export interface PluginSettings {
+  enabled: boolean;
+  autoSyncSkills?: boolean;
+  autoSyncAgents?: boolean;
+}
+
+export interface EvoDevSettings {
+  version: 1;
+  platform: {
+    os: string;
+  };
+  plugins: {
+    claude: PluginSettings;
+    codex: PluginSettings;
+  };
+  assets: {
+    skills: {
+      enabled: boolean;
+    };
+    agents: {
+      enabled: boolean;
+    };
+  };
+  doctor: {
+    lastRunAt: string | null;
+  };
+  hooks: HookSettings;
+}
+
+export type SettingsInput = Partial<{
+  version: number;
+  platform: Partial<EvoDevSettings["platform"]>;
+  plugins: Partial<{
+    claude: Partial<PluginSettings>;
+    codex: Partial<PluginSettings>;
+  }>;
+  assets: Partial<{
+    skills: Partial<EvoDevSettings["assets"]["skills"]>;
+    agents: Partial<EvoDevSettings["assets"]["agents"]>;
+  }>;
+  doctor: Partial<EvoDevSettings["doctor"]>;
+  hooks: unknown;
+}>;
+
+export function createDefaultSettings(os: string = process.platform): EvoDevSettings {
+  return {
+    version: 1,
+    platform: {
+      os,
+    },
+    plugins: {
+      claude: {
+        enabled: true,
+        autoSyncSkills: true,
+        autoSyncAgents: true,
+      },
+      codex: {
+        enabled: false,
+      },
+    },
+    assets: {
+      skills: {
+        enabled: true,
+      },
+      agents: {
+        enabled: true,
+      },
+    },
+    doctor: {
+      lastRunAt: null,
+    },
+    hooks: createDefaultHookSettings(),
+  };
+}
+
+export function mergeSettings(
+  existing: SettingsInput,
+  defaults: EvoDevSettings = createDefaultSettings(),
+): EvoDevSettings {
+  const merged = {
+    ...defaults,
+    ...existing,
+    platform: {
+      ...defaults.platform,
+      ...existing.platform,
+    },
+    plugins: {
+      claude: {
+        ...defaults.plugins.claude,
+        ...existing.plugins?.claude,
+      },
+      codex: {
+        ...defaults.plugins.codex,
+        ...existing.plugins?.codex,
+      },
+    },
+    assets: {
+      skills: {
+        ...defaults.assets.skills,
+        ...existing.assets?.skills,
+      },
+      agents: {
+        ...defaults.assets.agents,
+        ...existing.assets?.agents,
+      },
+    },
+    doctor: {
+      ...defaults.doctor,
+      ...existing.doctor,
+    },
+    hooks: existing.hooks ?? defaults.hooks,
+  };
+
+  return parseSettings(merged);
+}
+
+export function parseSettings(value: unknown): EvoDevSettings {
+  const root = expectRecord(value, "settings");
+  const version = root.version;
+
+  if (version !== 1) {
+    throw new EvoDevConfigError("Invalid settings.version; expected 1");
+  }
+
+  const platform = expectRecord(root.platform, "settings.platform");
+  const plugins = expectRecord(root.plugins, "settings.plugins");
+  const assets = expectRecord(root.assets, "settings.assets");
+  const doctor = expectRecord(root.doctor, "settings.doctor");
+
+  const parsed: EvoDevSettings = {
+    version: 1,
+    platform: {
+      os: expectString(platform.os, "settings.platform.os"),
+    },
+    plugins: {
+      claude: parsePluginSettings(plugins.claude, "settings.plugins.claude"),
+      codex: parsePluginSettings(plugins.codex, "settings.plugins.codex"),
+    },
+    assets: {
+      skills: {
+        enabled: expectBoolean(
+          expectRecord(assets.skills, "settings.assets.skills").enabled,
+          "settings.assets.skills.enabled",
+        ),
+      },
+      agents: {
+        enabled: expectBoolean(
+          expectRecord(assets.agents, "settings.assets.agents").enabled,
+          "settings.assets.agents.enabled",
+        ),
+      },
+    },
+    doctor: {
+      lastRunAt: expectNullableString(doctor.lastRunAt, "settings.doctor.lastRunAt"),
+    },
+    hooks: parseHookSettings(root.hooks),
+  };
+
+  return parsed;
+}
+
+function parsePluginSettings(value: unknown, path: string): PluginSettings {
+  const input = expectRecord(value, path);
+  const parsed: PluginSettings = {
+    enabled: expectBoolean(input.enabled, `${path}.enabled`),
+  };
+
+  if (input.autoSyncSkills !== undefined) {
+    parsed.autoSyncSkills = expectBoolean(input.autoSyncSkills, `${path}.autoSyncSkills`);
+  }
+
+  if (input.autoSyncAgents !== undefined) {
+    parsed.autoSyncAgents = expectBoolean(input.autoSyncAgents, `${path}.autoSyncAgents`);
+  }
+
+  return parsed;
+}
+
+function expectRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected object, got ${describeType(value)}`);
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function expectString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected non-empty string`);
+  }
+
+  return value;
+}
+
+function expectNullableString(value: unknown, path: string): string | null {
+  if (value === null || typeof value === "string") {
+    return value;
+  }
+
+  throw new EvoDevConfigError(`Invalid ${path}; expected string or null`);
+}
+
+function expectBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== "boolean") {
+    throw new EvoDevConfigError(`Invalid ${path}; expected boolean`);
+  }
+
+  return value;
+}

package/src/config/state.ts

@@ -0,0 +1,130 @@
+import { EvoDevConfigError, describeType } from "./errors.ts";
+
+export interface InstallState {
+  version: 1;
+  initializedAt: string | null;
+  initializedBy: "evodev";
+  selectedPlugins: string[];
+}
+
+export interface PluginSyncState {
+  skills: number;
+  agents: number;
+  status: "success" | "partial" | "failed" | "never-run";
+}
+
+export interface SyncState {
+  version: 1;
+  lastSyncAt: string | null;
+  targets: Record<string, PluginSyncState>;
+}
+
+export function createDefaultInstallState(): InstallState {
+  return {
+    version: 1,
+    initializedAt: null,
+    initializedBy: "evodev",
+    selectedPlugins: [],
+  };
+}
+
+export function createDefaultSyncState(): SyncState {
+  return {
+    version: 1,
+    lastSyncAt: null,
+    targets: {},
+  };
+}
+
+export function parseInstallState(value: unknown): InstallState {
+  const root = expectRecord(value, "install state");
+
+  if (root.version !== 1) {
+    throw new EvoDevConfigError("Invalid install state.version; expected 1");
+  }
+
+  if (root.initializedBy !== "evodev") {
+    throw new EvoDevConfigError("Invalid install state.initializedBy; expected evodev");
+  }
+
+  if (
+    !Array.isArray(root.selectedPlugins) ||
+    !root.selectedPlugins.every((plugin) => typeof plugin === "string")
+  ) {
+    throw new EvoDevConfigError("Invalid install state.selectedPlugins; expected string array");
+  }
+
+  return {
+    version: 1,
+    initializedAt: expectNullableString(root.initializedAt, "install state.initializedAt"),
+    initializedBy: "evodev",
+    selectedPlugins: [...root.selectedPlugins],
+  };
+}
+
+export function parseSyncState(value: unknown): SyncState {
+  const root = expectRecord(value, "sync state");
+
+  if (root.version !== 1) {
+    throw new EvoDevConfigError("Invalid sync state.version; expected 1");
+  }
+
+  const targets = expectRecord(root.targets, "sync state.targets");
+  const parsedTargets: Record<string, PluginSyncState> = {};
+
+  for (const [pluginId, state] of Object.entries(targets)) {
+    parsedTargets[pluginId] = parsePluginSyncState(state, `sync state.targets.${pluginId}`);
+  }
+
+  return {
+    version: 1,
+    lastSyncAt: expectNullableString(root.lastSyncAt, "sync state.lastSyncAt"),
+    targets: parsedTargets,
+  };
+}
+
+function parsePluginSyncState(value: unknown, path: string): PluginSyncState {
+  const root = expectRecord(value, path);
+  const status = root.status;
+
+  if (
+    status !== "success" &&
+    status !== "partial" &&
+    status !== "failed" &&
+    status !== "never-run"
+  ) {
+    throw new EvoDevConfigError(
+      `Invalid ${path}.status; expected success, partial, failed, or never-run`,
+    );
+  }
+
+  return {
+    skills: expectNonNegativeInteger(root.skills, `${path}.skills`),
+    agents: expectNonNegativeInteger(root.agents, `${path}.agents`),
+    status,
+  };
+}
+
+function expectRecord(value: unknown, path: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected object, got ${describeType(value)}`);
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function expectNullableString(value: unknown, path: string): string | null {
+  if (value === null || typeof value === "string") {
+    return value;
+  }
+
+  throw new EvoDevConfigError(`Invalid ${path}; expected string or null`);
+}
+
+function expectNonNegativeInteger(value: unknown, path: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new EvoDevConfigError(`Invalid ${path}; expected non-negative integer`);
+  }
+
+  return value;
+}