@shahmarasy/prodo 0.1.4 → 0.1.6

package/src/skill-engine/context.ts

@@ -0,0 +1,90 @@
+import { normalizedBriefPath } from "../core/paths";
+import { getActiveArtifactPath } from "../core/output-index";
+import { fileExists } from "../core/utils";
+import type { ArtifactType } from "../core/types";
+import type { PipelineState } from "./types";
+
+export function createPipelineState(cwd: string): PipelineState {
+  return {
+    cwd,
+    normalizedBriefPath: undefined,
+    generatedArtifacts: new Map(),
+    validationResult: undefined,
+    custom: {},
+    startedAt: new Date().toISOString(),
+    completedSkills: []
+  };
+}
+
+export async function hydrateStateFromDisk(
+  cwd: string,
+  state: PipelineState,
+  artifactTypes: ArtifactType[]
+): Promise<void> {
+  const nbPath = normalizedBriefPath(cwd);
+  if (!state.normalizedBriefPath && (await fileExists(nbPath))) {
+    state.normalizedBriefPath = nbPath;
+  }
+
+  for (const type of artifactTypes) {
+    if (!state.generatedArtifacts.has(type)) {
+      const active = await getActiveArtifactPath(cwd, type);
+      if (active) {
+        state.generatedArtifacts.set(type, active);
+      }
+    }
+  }
+}
+
+export function isOutputSatisfied(
+  outputName: string,
+  state: PipelineState,
+  artifactType?: string
+): boolean {
+  if (outputName === "normalizedBriefPath") {
+    return typeof state.normalizedBriefPath === "string" && state.normalizedBriefPath.length > 0;
+  }
+  if (outputName === "artifactPath" && artifactType) {
+    return state.generatedArtifacts.has(artifactType);
+  }
+  if (outputName === "validationResult") {
+    return state.validationResult !== undefined;
+  }
+  return false;
+}
+
+export function wireInputsFromState(
+  inputNames: string[],
+  state: PipelineState
+): Record<string, unknown> {
+  const inputs: Record<string, unknown> = {};
+  for (const name of inputNames) {
+    if (name === "cwd") inputs.cwd = state.cwd;
+    else if (name === "normalizedBriefPath") inputs.normalizedBriefPath = state.normalizedBriefPath;
+    else if (name in state.custom) inputs[name] = state.custom[name];
+  }
+  return inputs;
+}
+
+export function wireOutputsToState(
+  outputs: Record<string, unknown>,
+  state: PipelineState,
+  skillName: string
+): void {
+  if ("normalizedBriefPath" in outputs && typeof outputs.normalizedBriefPath === "string") {
+    state.normalizedBriefPath = outputs.normalizedBriefPath;
+  }
+  if ("artifactPath" in outputs && typeof outputs.artifactPath === "string") {
+    const artifactType = skillName;
+    state.generatedArtifacts.set(artifactType, outputs.artifactPath);
+  }
+  if ("validationResult" in outputs && outputs.validationResult && typeof outputs.validationResult === "object") {
+    state.validationResult = outputs.validationResult as PipelineState["validationResult"];
+  }
+
+  for (const [key, value] of Object.entries(outputs)) {
+    if (!["normalizedBriefPath", "artifactPath", "validationResult"].includes(key)) {
+      state.custom[key] = value;
+    }
+  }
+}

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;
+};