@evo-dev/core 0.0.1-alpha

package/src/plugins/capabilities.ts

@@ -0,0 +1,347 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { CodeAgentCapabilities, CodeAgentPlugin, PluginDetectionResult } from "./types.ts";
+
+export type CapabilityState = "declared" | "unverified" | "verified" | "enabled" | "unsupported";
+
+export interface PluginCapabilityNegotiation {
+  pluginId: string;
+  skills: CapabilityState;
+  agents: CapabilityState;
+  hooks: CapabilityState;
+  canPlanWrites: boolean;
+  warnings: string[];
+  blockers: string[];
+}
+
+export interface CodexCapabilityVerificationArtifact {
+  version: 1;
+  pluginId: "codex";
+  status: "verified-readonly";
+  verifiedAt: string;
+  createdAt: string;
+  metadataOnly: true;
+  rawOutputStored: false;
+  sourceContentStored: false;
+  promptHistoryStored: false;
+  promptStored: false;
+  secretsStored: false;
+  externalUpload: false;
+  networkUsed: false;
+  toolSummary: {
+    tool: "codex";
+    detectionStatus: string;
+    version: string | null;
+  };
+  capabilities: {
+    skills: "unverified";
+    agents: "unverified";
+    hooks: "unverified";
+  };
+  writeBoundary: {
+    writesAllowed: false;
+    allowedPaths: [];
+    userLevelOnly: true;
+    noOverwrite: true;
+    projectWritesAllowed: false;
+    codeAgentWritesAllowed: false;
+  };
+  privacy: {
+    classification: "local-private";
+    metadataOnly: true;
+    rawOutputStored: false;
+    sourceContentStored: false;
+    promptHistoryStored: false;
+    secretsStored: false;
+    externalUpload: false;
+  };
+  blockers: string[];
+  diagnostics: string[];
+  evidenceRefs: string[];
+  evidence: {
+    detectionStatus: string;
+    detectionMessage: string;
+    writesAllowed: false;
+    notes: string[];
+  };
+}
+
+export function createUnknownNegotiatedCapabilities(pluginId: string): PluginCapabilityNegotiation {
+  return {
+    pluginId,
+    skills: "unsupported",
+    agents: "unsupported",
+    hooks: "unsupported",
+    canPlanWrites: false,
+    warnings: [],
+    blockers: [`Plugin ${pluginId} capabilities are unknown and unsupported.`],
+  };
+}
+
+export function isCapabilityUsable(state: CapabilityState): boolean {
+  return state === "enabled";
+}
+
+export function assertNoUnverifiedWrites(negotiation: PluginCapabilityNegotiation): void {
+  if (!negotiation.canPlanWrites) {
+    throw new Error(`Plugin ${negotiation.pluginId} has no verified enabled write capabilities.`);
+  }
+}
+
+export function negotiatePluginCapabilities(input: {
+  pluginId: string;
+  declared: CodeAgentCapabilities;
+  verified?: CodexCapabilityVerificationArtifact | null;
+  enabled: boolean;
+}): PluginCapabilityNegotiation {
+  if (input.pluginId === "codex") {
+    const declaredSupport = [
+      input.declared.skills.supported ? "skills" : null,
+      input.declared.agents.supported ? "agents" : null,
+      input.declared.hooks.supported ? "hooks" : null,
+    ].filter(Boolean);
+    const blockers = ["Codex capabilities are unverified; writes are unsupported in I10."];
+    const warnings = [
+      input.verified
+        ? "Codex readonly verification artifact exists; sync remains no-write until formats are verified."
+        : null,
+      declaredSupport.length > 0
+        ? `Codex declares ${declaredSupport.join(", ")} support, but declared support alone cannot authorize writes.`
+        : null,
+    ].filter((warning): warning is string => warning !== null);
+
+    return {
+      pluginId: input.pluginId,
+      skills: input.declared.skills.supported ? "unverified" : "unsupported",
+      agents: input.declared.agents.supported ? "unverified" : "unsupported",
+      hooks: input.declared.hooks.supported ? "unverified" : "unsupported",
+      canPlanWrites: false,
+      warnings,
+      blockers,
+    };
+  }
+  return {
+    pluginId: input.pluginId,
+    skills: resolveNonCodexCapabilityState(input.declared.skills.supported, input.enabled),
+    agents: resolveNonCodexCapabilityState(input.declared.agents.supported, input.enabled),
+    hooks: resolveNonCodexCapabilityState(input.declared.hooks.supported, input.enabled),
+    canPlanWrites:
+      input.enabled && input.declared.skills.supported && input.declared.agents.supported,
+    warnings: input.enabled
+      ? []
+      : [
+          `Plugin ${input.pluginId} has declared capabilities but is not enabled; writes are not authorized.`,
+        ],
+    blockers: [],
+  };
+}
+
+function resolveNonCodexCapabilityState(supported: boolean, enabled: boolean): CapabilityState {
+  if (!supported) return "unsupported";
+  return enabled ? "enabled" : "declared";
+}
+
+export async function createCodexCapabilityVerificationArtifact(input: {
+  detection: PluginDetectionResult;
+  createdAt?: string;
+}): Promise<CodexCapabilityVerificationArtifact> {
+  const timestamp = input.createdAt ?? new Date().toISOString();
+  const detectionMessage = sanitizeText(input.detection.message);
+  const diagnostics = [
+    "Codex remains no-write until concrete user-level paths and formats are verified.",
+  ];
+  return {
+    version: 1,
+    pluginId: "codex",
+    status: "verified-readonly",
+    verifiedAt: timestamp,
+    createdAt: timestamp,
+    metadataOnly: true,
+    rawOutputStored: false,
+    sourceContentStored: false,
+    promptHistoryStored: false,
+    promptStored: false,
+    secretsStored: false,
+    externalUpload: false,
+    networkUsed: false,
+    toolSummary: { tool: "codex", detectionStatus: input.detection.status, version: null },
+    capabilities: { skills: "unverified", agents: "unverified", hooks: "unverified" },
+    writeBoundary: {
+      writesAllowed: false,
+      allowedPaths: [],
+      userLevelOnly: true,
+      noOverwrite: true,
+      projectWritesAllowed: false,
+      codeAgentWritesAllowed: false,
+    },
+    privacy: {
+      classification: "local-private",
+      metadataOnly: true,
+      rawOutputStored: false,
+      sourceContentStored: false,
+      promptHistoryStored: false,
+      secretsStored: false,
+      externalUpload: false,
+    },
+    blockers: ["Codex asset capabilities are unverified and unsupported for writes in I10."],
+    diagnostics,
+    evidenceRefs: [],
+    evidence: {
+      detectionStatus: input.detection.status,
+      detectionMessage,
+      writesAllowed: false,
+      notes: [
+        "Metadata-only readonly artifact; no Codex paths, formats, hooks, or writes verified.",
+      ],
+    },
+  };
+}
+
+export function resolveCodexCapabilityArtifactPath(homeDir: string): string {
+  return join(homeDir, ".evodev", "STATE", "plugins", "codex", "capability-verification.json");
+}
+
+export async function writeCodexCapabilityVerificationArtifact(
+  homeDir: string,
+  artifact: CodexCapabilityVerificationArtifact,
+): Promise<string> {
+  validateCodexCapabilityVerificationArtifact(artifact);
+  const path = resolveCodexCapabilityArtifactPath(homeDir);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(artifact, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  return path;
+}
+
+export async function readCodexCapabilityVerificationArtifact(
+  homeDir: string,
+): Promise<CodexCapabilityVerificationArtifact | null> {
+  try {
+    const artifact = JSON.parse(
+      await readFile(resolveCodexCapabilityArtifactPath(homeDir), "utf8"),
+    );
+    validateCodexCapabilityVerificationArtifact(artifact);
+    return artifact;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export function validateCodexCapabilityVerificationArtifact(
+  artifact: CodexCapabilityVerificationArtifact,
+): void {
+  if (artifact.version !== 1 || artifact.pluginId !== "codex")
+    throw new Error("Invalid Codex artifact identity.");
+  if (
+    artifact.metadataOnly !== true ||
+    artifact.rawOutputStored !== false ||
+    artifact.sourceContentStored !== false ||
+    artifact.promptStored !== false ||
+    artifact.promptHistoryStored !== false ||
+    artifact.secretsStored !== false ||
+    artifact.externalUpload !== false ||
+    artifact.networkUsed !== false ||
+    artifact.privacy?.metadataOnly !== true ||
+    artifact.privacy.rawOutputStored !== false ||
+    artifact.privacy.sourceContentStored !== false ||
+    artifact.privacy.promptHistoryStored !== false ||
+    artifact.privacy.secretsStored !== false ||
+    artifact.privacy.externalUpload !== false ||
+    artifact.writeBoundary?.writesAllowed !== false ||
+    artifact.writeBoundary.allowedPaths.length !== 0 ||
+    artifact.writeBoundary.userLevelOnly !== true ||
+    artifact.writeBoundary.noOverwrite !== true ||
+    artifact.writeBoundary.projectWritesAllowed !== false ||
+    artifact.writeBoundary.codeAgentWritesAllowed !== false
+  ) {
+    throw new Error("Codex artifact must be metadata-only and local-only.");
+  }
+  assertNoSensitiveContent(artifact);
+}
+
+export function formatCodexCapabilityVerificationArtifact(
+  artifact: CodexCapabilityVerificationArtifact,
+  path?: string,
+): string {
+  return [
+    "EvoDev Codex capability verification",
+    "",
+    `Status: ${artifact.status}`,
+    `Artifact: ${path ?? "dry-run only"}`,
+    `Verified at: ${artifact.verifiedAt}`,
+    "Capabilities: skills=unverified agents=unverified hooks=unverified",
+    "Writes allowed: false",
+    "Allowed paths: none",
+    "User-level write paths verified: false",
+    "Project writes allowed: false",
+    "No-overwrite verified: false",
+    `External upload: ${artifact.externalUpload}`,
+    `Detection: ${artifact.evidence.detectionStatus}`,
+    ...artifact.evidence.notes.map((note) => `Note: ${note}`),
+  ].join("\n");
+}
+
+export async function runPluginConformance(
+  plugin: CodeAgentPlugin,
+): Promise<{ ok: boolean; findings: string[] }> {
+  const findings: string[] = [];
+  try {
+    await plugin.detect();
+    await plugin.getCapabilities();
+  } catch (error) {
+    findings.push(
+      `Plugin ${plugin.id} threw during detect/capabilities: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (plugin.id === "codex") {
+    const capabilities = await plugin.getCapabilities();
+    if (
+      capabilities.skills.supported ||
+      capabilities.agents.supported ||
+      capabilities.hooks.supported
+    ) {
+      findings.push("Codex must not declare verified runtime support in I10.");
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+function sanitizeText(value: string): string {
+  return value
+    .replace(
+      /https?:\/\/\S+|\b(secret|token|password|private|internal|api[_-]?key)\b/gi,
+      "[redacted]",
+    )
+    .slice(0, 300);
+}
+
+function assertNoSensitiveContent(value: unknown): void {
+  if (typeof value === "string") {
+    if (value === "local-private") return;
+    if (
+      /https?:\/\/\S+|\b(secret|token|password|private|internal|api[_-]?key|raw output|raw source|raw prompt)\b/i.test(
+        value,
+      )
+    ) {
+      throw new Error("Codex artifact contains sensitive content.");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoSensitiveContent(item);
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (/raw|prompt|source|secret|token|password|memorybody/i.test(key) && child !== false) {
+      throw new Error(`Codex artifact contains forbidden field: ${key}`);
+    }
+    assertNoSensitiveContent(child);
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,41 @@
+export {
+  type CapabilityState,
+  type CodexCapabilityVerificationArtifact,
+  type PluginCapabilityNegotiation,
+  assertNoUnverifiedWrites,
+  createCodexCapabilityVerificationArtifact,
+  createUnknownNegotiatedCapabilities,
+  formatCodexCapabilityVerificationArtifact,
+  isCapabilityUsable,
+  negotiatePluginCapabilities,
+  readCodexCapabilityVerificationArtifact,
+  resolveCodexCapabilityArtifactPath,
+  runPluginConformance,
+  validateCodexCapabilityVerificationArtifact,
+  writeCodexCapabilityVerificationArtifact,
+} from "./capabilities.ts";
+export {
+  PluginRegistry,
+  PluginRegistryError,
+  createPluginRegistry,
+  getEnabledPluginIds,
+} from "./registry.ts";
+export type {
+  CodeAgentCapabilities,
+  CodeAgentPlugin,
+  DoctorCheck,
+  DoctorCheckStatus,
+  DoctorContext,
+  HookEvent,
+  HookEventType,
+  PluginDetectionResult,
+  PluginDetectionStatus,
+  PluginId,
+  PluginInstallInput,
+  PluginInstallResult,
+  PluginInstallStatus,
+  SyncAgentsInput,
+  SyncPlan,
+  SyncResult,
+  SyncSkillsInput,
+} from "./types.ts";

package/src/plugins/registry.ts

@@ -0,0 +1,60 @@
+import type { EvoDevSettings } from "../config/index.ts";
+import type { CodeAgentPlugin, PluginId } from "./types.ts";
+
+export class PluginRegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PluginRegistryError";
+  }
+}
+
+export class PluginRegistry {
+  readonly #plugins = new Map<PluginId, CodeAgentPlugin>();
+
+  register(plugin: CodeAgentPlugin): void {
+    if (this.#plugins.has(plugin.id)) {
+      throw new PluginRegistryError(`Plugin already registered: ${plugin.id}`);
+    }
+
+    this.#plugins.set(plugin.id, plugin);
+  }
+
+  get(pluginId: PluginId): CodeAgentPlugin | undefined {
+    return this.#plugins.get(pluginId);
+  }
+
+  require(pluginId: PluginId): CodeAgentPlugin {
+    const plugin = this.get(pluginId);
+
+    if (plugin === undefined) {
+      throw new PluginRegistryError(`Plugin not registered: ${pluginId}`);
+    }
+
+    return plugin;
+  }
+
+  list(): CodeAgentPlugin[] {
+    return [...this.#plugins.values()].sort((left, right) => left.id.localeCompare(right.id));
+  }
+
+  getEnabled(settings: EvoDevSettings): CodeAgentPlugin[] {
+    return getEnabledPluginIds(settings).map((pluginId) => this.require(pluginId));
+  }
+}
+
+export function createPluginRegistry(plugins: CodeAgentPlugin[] = []): PluginRegistry {
+  const registry = new PluginRegistry();
+
+  for (const plugin of plugins) {
+    registry.register(plugin);
+  }
+
+  return registry;
+}
+
+export function getEnabledPluginIds(settings: EvoDevSettings): PluginId[] {
+  return Object.entries(settings.plugins)
+    .filter(([, pluginSettings]) => pluginSettings.enabled)
+    .map(([pluginId]) => pluginId)
+    .sort((left, right) => left.localeCompare(right));
+}

package/src/plugins/types.ts

@@ -0,0 +1,123 @@
+import type { ScannedAsset } from "../assets/index.ts";
+import type { AgentManifest, SkillManifest } from "../assets/manifest.ts";
+import type { EvoDevSettings } from "../config/index.ts";
+
+export type PluginId = string;
+
+export type PluginDetectionStatus = "installed" | "missing" | "unknown" | "reserved";
+
+export interface PluginDetectionResult {
+  status: PluginDetectionStatus;
+  message: string;
+}
+
+export type HookEventType =
+  | "SessionStart"
+  | "UserPromptSubmit"
+  | "UserPromptExpansion"
+  | "PreToolUse"
+  | "PermissionRequest"
+  | "PostToolUse"
+  | "PostToolUseFailure"
+  | "PostToolBatch"
+  | "PermissionDenied"
+  | "SubagentStart"
+  | "Stop"
+  | "StopFailure"
+  | "TeammateIdle"
+  | "SubagentStop"
+  | "AgentStop"
+  | "TaskCreated"
+  | "TaskCompleted"
+  | "PreCompact"
+  | "PostCompact"
+  | "SessionEnd";
+
+export interface HookEvent {
+  type: HookEventType;
+  payload: Record<string, unknown>;
+}
+
+export interface CodeAgentCapabilities {
+  skills: {
+    supported: boolean;
+    format: "claude-skill" | "codex-skill" | "markdown";
+  };
+  agents: {
+    supported: boolean;
+    format: "claude-agent" | "codex-agent" | "prompt-md";
+  };
+  hooks: {
+    supported: boolean;
+    events: HookEventType[];
+  };
+}
+
+export type DoctorCheckStatus = "pass" | "warn" | "fail" | "skip";
+
+export interface DoctorContext {
+  settings: EvoDevSettings;
+  homeDir: string;
+}
+
+export interface DoctorCheck {
+  id: string;
+  status: DoctorCheckStatus;
+  message: string;
+}
+
+export interface SyncSkillsInput {
+  targetPlugin: PluginId;
+  skills: ScannedAsset<SkillManifest>[];
+  dryRun: boolean;
+}
+
+export interface SyncAgentsInput {
+  targetPlugin: PluginId;
+  agents: ScannedAsset<AgentManifest>[];
+  dryRun: boolean;
+}
+
+export interface PluginInstallInput {
+  targetPlugin: PluginId;
+}
+
+export type PluginInstallStatus = "installed" | "already-installed" | "skipped" | "failed";
+
+export interface PluginInstallResult {
+  targetPlugin: PluginId;
+  status: PluginInstallStatus;
+  command: string;
+  args: string[];
+  message: string;
+  warnings: string[];
+  errors: string[];
+}
+
+export interface SyncResult {
+  targetPlugin: PluginId;
+  syncedSkills: string[];
+  syncedAgents: string[];
+  skipped: string[];
+  warnings: string[];
+  errors: string[];
+}
+
+export interface SyncPlan {
+  targetPlugin: PluginId;
+  skills: ScannedAsset<SkillManifest>[];
+  agents: ScannedAsset<AgentManifest>[];
+  dryRun: boolean;
+}
+
+export interface CodeAgentPlugin {
+  id: PluginId;
+  name: string;
+  detect(): Promise<PluginDetectionResult>;
+  getCapabilities(): Promise<CodeAgentCapabilities>;
+  doctor(context: DoctorContext): Promise<DoctorCheck[]>;
+  syncSkills(input: SyncSkillsInput): Promise<SyncResult>;
+  syncAgents(input: SyncAgentsInput): Promise<SyncResult>;
+  installPlugin?(input: PluginInstallInput): Promise<PluginInstallResult>;
+  handleHookEvent?(event: HookEvent): Promise<void>;
+}