@shahmarasy/prodo 0.1.5 → 0.1.6

package/src/skill-engine/discovery.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { prodoPath } from "../core/paths";
+import { fileExists } from "../core/utils";
+import type { Skill, SkillManifest } from "./types";
+
+function isValidManifest(obj: unknown): obj is SkillManifest {
+  if (!obj || typeof obj !== "object") return false;
+  const m = obj as Record<string, unknown>;
+  return (
+    typeof m.name === "string" &&
+    typeof m.version === "string" &&
+    typeof m.description === "string" &&
+    Array.isArray(m.depends_on) &&
+    Array.isArray(m.inputs) &&
+    Array.isArray(m.outputs)
+  );
+}
+
+export async function discoverSkills(
+  cwd: string,
+  log?: (message: string) => void
+): Promise<Skill[]> {
+  const skillsDir = path.join(prodoPath(cwd), "skills");
+  if (!(await fileExists(skillsDir))) return [];
+
+  const entries = await fs.readdir(skillsDir);
+  const jsFiles = entries.filter((e) => e.endsWith(".js"));
+  const skills: Skill[] = [];
+
+  for (const file of jsFiles) {
+    const fullPath = path.resolve(skillsDir, file);
+    try {
+      const mod = require(fullPath) as Record<string, unknown>;
+      const manifest = mod.manifest;
+      const execute = mod.execute;
+
+      if (!isValidManifest(manifest)) {
+        log?.(`[Skill Discovery] Skipping ${file}: invalid or missing manifest`);
+        continue;
+      }
+
+      if (typeof execute !== "function") {
+        log?.(`[Skill Discovery] Skipping ${file}: missing execute function`);
+        continue;
+      }
+
+      skills.push({ manifest, execute: execute as Skill["execute"] });
+      log?.(`[Skill Discovery] Loaded plugin: ${manifest.name} v${manifest.version}`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log?.(`[Skill Discovery] Failed to load ${file}: ${message}`);
+    }
+  }
+
+  return skills;
+}

package/src/skill-engine/graph.ts

@@ -0,0 +1,136 @@
+import { UserError } from "../core/errors";
+import type { ExecutionTier, SkillManifest } from "./types";
+
+export function detectCycles(manifests: Map<string, SkillManifest>): string[][] | null {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  const cycles: string[][] = [];
+
+  for (const name of manifests.keys()) {
+    color.set(name, WHITE);
+  }
+
+  function dfs(node: string, path: string[]): void {
+    color.set(node, GRAY);
+    path.push(node);
+
+    const manifest = manifests.get(node);
+    if (manifest) {
+      for (const dep of manifest.depends_on) {
+        if (!manifests.has(dep)) continue;
+        const c = color.get(dep) ?? WHITE;
+        if (c === GRAY) {
+          const cycleStart = path.indexOf(dep);
+          cycles.push([...path.slice(cycleStart), dep]);
+        } else if (c === WHITE) {
+          dfs(dep, path);
+        }
+      }
+    }
+
+    path.pop();
+    color.set(node, BLACK);
+  }
+
+  for (const name of manifests.keys()) {
+    if (color.get(name) === WHITE) {
+      dfs(name, []);
+    }
+  }
+
+  return cycles.length > 0 ? cycles : null;
+}
+
+function collectTransitiveDeps(
+  target: string,
+  manifests: Map<string, SkillManifest>,
+  collected: Set<string>
+): void {
+  if (collected.has(target)) return;
+  collected.add(target);
+  const manifest = manifests.get(target);
+  if (!manifest) return;
+  for (const dep of manifest.depends_on) {
+    if (manifests.has(dep)) {
+      collectTransitiveDeps(dep, manifests, collected);
+    }
+  }
+}
+
+export function buildExecutionPlan(
+  manifests: Map<string, SkillManifest>,
+  targetSkills: string[]
+): ExecutionTier[] {
+  const needed = new Set<string>();
+  for (const target of targetSkills) {
+    collectTransitiveDeps(target, manifests, needed);
+  }
+
+  const filteredManifests = new Map<string, SkillManifest>();
+  for (const name of needed) {
+    const m = manifests.get(name);
+    if (m) filteredManifests.set(name, m);
+  }
+
+  const cycles = detectCycles(filteredManifests);
+  if (cycles) {
+    const cycleStr = cycles.map((c) => c.join(" → ")).join("; ");
+    throw new UserError(`Dependency cycle detected: ${cycleStr}`);
+  }
+
+  const inDegree = new Map<string, number>();
+  for (const name of filteredManifests.keys()) {
+    inDegree.set(name, 0);
+  }
+
+  for (const [, manifest] of filteredManifests) {
+    for (const dep of manifest.depends_on) {
+      if (filteredManifests.has(dep)) {
+        inDegree.set(manifest.name, (inDegree.get(manifest.name) ?? 0) + 1);
+      }
+    }
+  }
+
+  const tiers: ExecutionTier[] = [];
+  const remaining = new Set(filteredManifests.keys());
+  let tierNum = 0;
+
+  while (remaining.size > 0) {
+    const ready: string[] = [];
+    for (const name of remaining) {
+      if ((inDegree.get(name) ?? 0) === 0) {
+        ready.push(name);
+      }
+    }
+
+    if (ready.length === 0) {
+      throw new UserError(`Cannot resolve execution order for: ${Array.from(remaining).join(", ")}`);
+    }
+
+    ready.sort();
+    tiers.push({ tier: tierNum, skills: ready });
+
+    for (const name of ready) {
+      remaining.delete(name);
+      for (const [otherName, manifest] of filteredManifests) {
+        if (manifest.depends_on.includes(name) && remaining.has(otherName)) {
+          inDegree.set(otherName, (inDegree.get(otherName) ?? 0) - 1);
+        }
+      }
+    }
+
+    tierNum += 1;
+  }
+
+  return tiers;
+}
+
+export function getExecutionOrder(
+  manifests: Map<string, SkillManifest>,
+  targetSkills: string[]
+): string[] {
+  const tiers = buildExecutionPlan(manifests, targetSkills);
+  return tiers.flatMap((t) => t.skills);
+}

package/src/skill-engine/index.ts

@@ -0,0 +1,55 @@
+import { SkillRegistry } from "./registry";
+import { SkillPipeline } from "./pipeline";
+import { discoverSkills } from "./discovery";
+import { registerCoreSkills } from "../skills/register-core";
+import { createPipelineState, hydrateStateFromDisk } from "./context";
+import { listArtifactTypes } from "../core/artifact-registry";
+import type { PipelineState } from "./types";
+
+export async function createEngine(
+  cwd: string,
+  log?: (message: string) => void
+): Promise<SkillPipeline> {
+  const registry = new SkillRegistry();
+
+  await registerCoreSkills(registry, cwd);
+
+  const plugins = await discoverSkills(cwd, log);
+  for (const plugin of plugins) {
+    try {
+      registry.register(plugin);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log?.(`[Skill Engine] Plugin registration failed: ${message}`);
+    }
+  }
+
+  return new SkillPipeline(registry);
+}
+
+export async function createHydratedState(cwd: string): Promise<PipelineState> {
+  const state = createPipelineState(cwd);
+  const artifactTypes = await listArtifactTypes(cwd);
+  await hydrateStateFromDisk(cwd, state, artifactTypes);
+  return state;
+}
+
+export { SkillPipeline } from "./pipeline";
+export { SkillRegistry } from "./registry";
+export { createPipelineState, hydrateStateFromDisk } from "./context";
+export { buildExecutionPlan, detectCycles, getExecutionOrder } from "./graph";
+export { discoverSkills } from "./discovery";
+export { validateInputs, validateOutputs, validateInputPaths } from "./validator";
+export type {
+  Skill,
+  SkillManifest,
+  SkillInput,
+  SkillOutput,
+  SkillContext,
+  SkillExecuteFn,
+  PipelineState,
+  PipelineOptions,
+  ExecutionTier,
+  SkillError,
+  ProgressCallback
+} from "./types";

package/src/skill-engine/pipeline.ts

@@ -0,0 +1,112 @@
+import { UserError } from "../core/errors";
+import { wireInputsFromState, wireOutputsToState } from "./context";
+import { getExecutionOrder } from "./graph";
+import type { SkillRegistry } from "./registry";
+import type { PipelineOptions, PipelineState, SkillContext, SkillError } from "./types";
+import { validateInputs, validateOutputs } from "./validator";
+
+function createSkillError(
+  skillName: string,
+  phase: SkillError["phase"],
+  error: unknown
+): SkillError {
+  const message = error instanceof Error ? error.message : String(error);
+  const stack = error instanceof Error ? error.stack : undefined;
+  return {
+    skillName,
+    phase,
+    message,
+    stack,
+    recoveryHints: [`Skill "${skillName}" failed during ${phase}. Check inputs and retry.`]
+  };
+}
+
+export class SkillPipeline {
+  constructor(private registry: SkillRegistry) {}
+
+  async runPipeline(
+    skillNames: string[],
+    state: PipelineState,
+    options: PipelineOptions = {}
+  ): Promise<PipelineState> {
+    const { log = console.log, progress, agent } = options;
+
+    for (const name of skillNames) {
+      if (!this.registry.has(name)) {
+        const available = this.registry.list().map((s) => s.manifest.name).join(", ");
+        throw new UserError(`Unknown skill: "${name}". Available: ${available}`);
+      }
+    }
+
+    const manifests = new Map(
+      this.registry.list().map((s) => [s.manifest.name, s.manifest])
+    );
+    const executionOrder = getExecutionOrder(manifests, skillNames);
+    const totalSteps = executionOrder.length;
+
+    for (let i = 0; i < executionOrder.length; i++) {
+      const skillName = executionOrder[i];
+
+      if (state.completedSkills.includes(skillName)) {
+        log(`[Skip] ${skillName} — already completed`);
+        continue;
+      }
+
+      const skill = this.registry.get(skillName);
+      if (!skill) continue;
+
+      progress?.(i + 1, totalSteps, `Running ${skillName}...`);
+      log(`[${i + 1}/${totalSteps}] ${skillName}`);
+
+      const inputNames = skill.manifest.inputs.map((inp) => inp.name);
+      const wiredInputs = wireInputsFromState(inputNames, state);
+
+      const inputError = validateInputs(skill.manifest, wiredInputs);
+      if (inputError) {
+        throw new UserError(
+          `Skill "${skillName}" input validation failed: ${inputError.message}\n` +
+          inputError.recoveryHints.join("\n")
+        );
+      }
+
+      let outputs: Record<string, unknown>;
+      try {
+        const context: SkillContext = {
+          state,
+          progress: progress ?? (() => {}),
+          log,
+          agent
+        };
+        outputs = await skill.execute(context, wiredInputs);
+      } catch (error) {
+        const skillError = createSkillError(skillName, "execution", error);
+        throw new UserError(
+          `Skill "${skillName}" execution failed: ${skillError.message}\n` +
+          skillError.recoveryHints.join("\n")
+        );
+      }
+
+      const outputError = validateOutputs(skill.manifest, outputs);
+      if (outputError) {
+        log(`[Warning] Skill "${skillName}" output validation: ${outputError.message}`);
+      }
+
+      wireOutputsToState(outputs, state, skillName);
+      state.completedSkills.push(skillName);
+    }
+
+    return state;
+  }
+
+  async runSkill(
+    name: string,
+    state: PipelineState,
+    options: PipelineOptions = {}
+  ): Promise<PipelineState> {
+    return this.runPipeline([name], state, options);
+  }
+
+  getRegistry(): SkillRegistry {
+    return this.registry;
+  }
+}

package/src/skill-engine/registry.ts

@@ -0,0 +1,75 @@
+import { UserError } from "../core/errors";
+import type { Skill, SkillManifest } from "./types";
+
+function validateManifest(manifest: SkillManifest): string | null {
+  if (!manifest.name || typeof manifest.name !== "string") return "Skill name is required";
+  if (!manifest.version || typeof manifest.version !== "string") return "Skill version is required";
+  if (!manifest.description || typeof manifest.description !== "string") return "Skill description is required";
+
+  const validCategories = ["core", "artifact", "validation", "custom"];
+  if (!validCategories.includes(manifest.category)) {
+    return `Invalid category "${manifest.category}". Must be: ${validCategories.join(", ")}`;
+  }
+
+  if (!Array.isArray(manifest.depends_on)) return "depends_on must be an array";
+  if (!Array.isArray(manifest.inputs)) return "inputs must be an array";
+  if (!Array.isArray(manifest.outputs)) return "outputs must be an array";
+
+  const validTypes = ["string", "path", "boolean", "json", "number"];
+  for (const input of manifest.inputs) {
+    if (!input.name || typeof input.name !== "string") return "Input name is required";
+    if (!validTypes.includes(input.type)) return `Invalid input type "${input.type}" for "${input.name}"`;
+  }
+  for (const output of manifest.outputs) {
+    if (!output.name || typeof output.name !== "string") return "Output name is required";
+    if (!validTypes.includes(output.type)) return `Invalid output type "${output.type}" for "${output.name}"`;
+  }
+
+  return null;
+}
+
+export class SkillRegistry {
+  private skills = new Map<string, Skill>();
+
+  register(skill: Skill): void {
+    const error = validateManifest(skill.manifest);
+    if (error) {
+      throw new UserError(`Invalid skill manifest for "${skill.manifest?.name ?? "unknown"}": ${error}`);
+    }
+    if (typeof skill.execute !== "function") {
+      throw new UserError(`Skill "${skill.manifest.name}" must export an execute function`);
+    }
+    if (this.skills.has(skill.manifest.name)) {
+      throw new UserError(`Skill "${skill.manifest.name}" is already registered`);
+    }
+    this.skills.set(skill.manifest.name, skill);
+  }
+
+  get(name: string): Skill | undefined {
+    return this.skills.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.skills.has(name);
+  }
+
+  list(): Skill[] {
+    return Array.from(this.skills.values());
+  }
+
+  listByCategory(category: string): Skill[] {
+    return this.list().filter((s) => s.manifest.category === category);
+  }
+
+  listManifests(): SkillManifest[] {
+    return this.list().map((s) => s.manifest);
+  }
+
+  unregister(name: string): boolean {
+    return this.skills.delete(name);
+  }
+
+  size(): number {
+    return this.skills.size;
+  }
+}

package/src/skill-engine/types.ts

@@ -0,0 +1,81 @@
+import type { ValidationIssue } from "../core/types";
+
+export type SkillInputType = "string" | "path" | "boolean" | "json" | "number";
+
+export type SkillInput = {
+  name: string;
+  type: SkillInputType;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+};
+
+export type SkillOutput = {
+  name: string;
+  type: SkillInputType;
+  description?: string;
+};
+
+export type SkillManifest = {
+  name: string;
+  version: string;
+  description: string;
+  category: "core" | "artifact" | "validation" | "custom";
+  depends_on: string[];
+  inputs: SkillInput[];
+  outputs: SkillOutput[];
+  tags?: string[];
+};
+
+export type PipelineState = {
+  cwd: string;
+  normalizedBriefPath?: string;
+  generatedArtifacts: Map<string, string>;
+  validationResult?: {
+    pass: boolean;
+    reportPath: string;
+    issues: ValidationIssue[];
+  };
+  custom: Record<string, unknown>;
+  startedAt: string;
+  completedSkills: string[];
+};
+
+export type ProgressCallback = (step: number, total: number, message: string) => void;
+
+export type SkillContext = {
+  state: PipelineState;
+  progress: ProgressCallback;
+  log: (message: string) => void;
+  agent?: string;
+};
+
+export type SkillExecuteFn = (
+  context: SkillContext,
+  inputs: Record<string, unknown>
+) => Promise<Record<string, unknown>>;
+
+export type Skill = {
+  manifest: SkillManifest;
+  execute: SkillExecuteFn;
+};
+
+export type SkillError = {
+  skillName: string;
+  phase: "input_validation" | "execution" | "output_validation";
+  message: string;
+  inputContext?: Record<string, unknown>;
+  stack?: string;
+  recoveryHints: string[];
+};
+
+export type ExecutionTier = {
+  tier: number;
+  skills: string[];
+};
+
+export type PipelineOptions = {
+  log?: (message: string) => void;
+  progress?: ProgressCallback;
+  agent?: string;
+};

package/src/skill-engine/validator.ts

@@ -0,0 +1,135 @@
+import { fileExists } from "../core/utils";
+import type { SkillError, SkillManifest } from "./types";
+
+function makeError(
+  skillName: string,
+  phase: SkillError["phase"],
+  message: string,
+  hints: string[] = []
+): SkillError {
+  return {
+    skillName,
+    phase,
+    message,
+    recoveryHints: hints
+  };
+}
+
+function checkType(value: unknown, expectedType: string, fieldName: string): string | null {
+  switch (expectedType) {
+    case "string":
+      if (typeof value !== "string") return `"${fieldName}" must be a string, got ${typeof value}`;
+      return null;
+
+    case "path":
+      if (typeof value !== "string") return `"${fieldName}" must be a path (string), got ${typeof value}`;
+      return null;
+
+    case "boolean":
+      if (typeof value !== "boolean") return `"${fieldName}" must be a boolean, got ${typeof value}`;
+      return null;
+
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return `"${fieldName}" must be a finite number, got ${typeof value}`;
+      }
+      return null;
+
+    case "json":
+      if (typeof value === "string") {
+        try {
+          JSON.parse(value);
+        } catch {
+          return `"${fieldName}" must be valid JSON string`;
+        }
+      }
+      return null;
+
+    default:
+      return null;
+  }
+}
+
+export function validateInputs(
+  manifest: SkillManifest,
+  inputs: Record<string, unknown>
+): SkillError | null {
+  for (const input of manifest.inputs) {
+    const value = inputs[input.name];
+
+    if (input.required && (value === undefined || value === null)) {
+      if (input.default !== undefined) continue;
+      return makeError(
+        manifest.name,
+        "input_validation",
+        `Required input "${input.name}" is missing`,
+        [`Provide "${input.name}" (${input.type}): ${input.description ?? ""}`]
+      );
+    }
+
+    if (value === undefined || value === null) continue;
+
+    const typeError = checkType(value, input.type, input.name);
+    if (typeError) {
+      return makeError(
+        manifest.name,
+        "input_validation",
+        typeError,
+        [`Expected type: ${input.type}`]
+      );
+    }
+  }
+
+  return null;
+}
+
+export async function validateInputPaths(
+  manifest: SkillManifest,
+  inputs: Record<string, unknown>
+): Promise<SkillError | null> {
+  for (const input of manifest.inputs) {
+    if (input.type !== "path") continue;
+    const value = inputs[input.name];
+    if (typeof value !== "string") continue;
+
+    if (input.required && !(await fileExists(value))) {
+      return makeError(
+        manifest.name,
+        "input_validation",
+        `Path "${input.name}" does not exist: ${value}`,
+        [`Ensure the file or directory exists: ${value}`]
+      );
+    }
+  }
+  return null;
+}
+
+export function validateOutputs(
+  manifest: SkillManifest,
+  outputs: Record<string, unknown>
+): SkillError | null {
+  for (const output of manifest.outputs) {
+    const value = outputs[output.name];
+
+    if (value === undefined || value === null) {
+      return makeError(
+        manifest.name,
+        "output_validation",
+        `Expected output "${output.name}" was not produced`,
+        [`Skill "${manifest.name}" should return "${output.name}" (${output.type})`]
+      );
+    }
+
+    const typeError = checkType(value, output.type, output.name);
+    if (typeError) {
+      return makeError(
+        manifest.name,
+        "output_validation",
+        typeError,
+        [`Skill "${manifest.name}" returned wrong type for "${output.name}"`]
+      );
+    }
+  }
+
+  return null;
+}

package/src/skills/fix.ts

@@ -0,0 +1,45 @@
+import { runFix } from "../core/fix";
+import type { Skill } from "../skill-engine/types";
+
+export const fixSkill: Skill = {
+  manifest: {
+    name: "fix",
+    version: "2.0.0",
+    description: "Auto-regenerate failing artifacts with backup, proposal, and validation",
+    category: "validation",
+    depends_on: [],
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" }
+    ],
+    outputs: [
+      { name: "validationResult", type: "json", description: "Final validation result after fix" }
+    ],
+    tags: ["fix", "repair", "validation"]
+  },
+
+  async execute(context, inputs) {
+    const cwd = (inputs.cwd as string) ?? context.state.cwd;
+    context.progress(1, 3, "Running fix pipeline...");
+
+    const result = await runFix({
+      cwd,
+      agent: context.agent,
+      log: context.log
+    });
+
+    context.progress(3, 3, result.finalPass ? "Fix complete." : "Fix applied, issues remain.");
+
+    context.state.validationResult = result.finalPass
+      ? { pass: true, reportPath: result.reportPath, issues: [] }
+      : undefined;
+
+    return {
+      validationResult: {
+        pass: result.finalPass,
+        reportPath: result.reportPath,
+        applied: result.applied,
+        targetCount: result.proposal.targets.length
+      }
+    };
+  }
+};