@urielsh/prodify 0.1.0

package/src/core/repo-root.ts

@@ -0,0 +1,74 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { ProdifyError } from './errors.js';
+
+interface ResolveRepoRootOptions {
+  cwd?: string;
+  repoRoot?: string;
+  allowBootstrap?: boolean;
+}
+
+async function isDirectory(targetPath: string): Promise<boolean> {
+  try {
+    return (await fs.stat(targetPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function directoryHas(directory: string, childName: string): Promise<boolean> {
+  return isDirectory(path.join(directory, childName));
+}
+
+async function searchUpwards(startDir: string, predicate: (candidate: string) => Promise<boolean>): Promise<string | null> {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (await predicate(current)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+
+    current = parent;
+  }
+}
+
+export async function resolveRepoRoot(options: ResolveRepoRootOptions = {}): Promise<string> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const explicitRepo = options.repoRoot ? path.resolve(options.repoRoot) : null;
+  const allowBootstrap = options.allowBootstrap ?? false;
+
+  if (explicitRepo) {
+    const hasProdify = await directoryHas(explicitRepo, '.prodify');
+    const hasGit = await directoryHas(explicitRepo, '.git');
+
+    if (!hasProdify && !(allowBootstrap && hasGit)) {
+      throw new ProdifyError(`Could not verify repository root at ${explicitRepo}.`, {
+        code: 'REPO_ROOT_NOT_FOUND'
+      });
+    }
+
+    return explicitRepo;
+  }
+
+  const prodifyRoot = await searchUpwards(cwd, async (candidate) => directoryHas(candidate, '.prodify'));
+  if (prodifyRoot) {
+    return prodifyRoot;
+  }
+
+  if (allowBootstrap) {
+    const gitRoot = await searchUpwards(cwd, async (candidate) => directoryHas(candidate, '.git'));
+    if (gitRoot) {
+      return gitRoot;
+    }
+  }
+
+  throw new ProdifyError('Could not resolve repository root from the current working directory.', {
+    code: 'REPO_ROOT_NOT_FOUND'
+  });
+}

package/src/core/skill-resolution.ts

@@ -0,0 +1,151 @@
+import { loadCompiledContract } from '../contracts/compiler.js';
+import { ProdifyError } from './errors.js';
+import { detectRepoContext } from './repo-context.js';
+import { loadSkillRegistry } from '../skills/loader.js';
+import type {
+  FlowStage,
+  RepoContextFact,
+  RepoContextSnapshot,
+  SkillActivationRecord,
+  SkillCondition,
+  SkillDefinition,
+  StageSkillResolution,
+  StageSkillRouting
+} from '../types.js';
+
+function factValues(context: RepoContextSnapshot, fact: RepoContextFact): string[] {
+  switch (fact) {
+    case 'language':
+      return context.languages;
+    case 'framework':
+      return context.frameworks;
+    case 'project_type':
+      return context.project_types;
+    case 'architecture_pattern':
+      return context.architecture_patterns;
+    case 'risk_signal':
+      return context.risk_signals;
+    default:
+      return [];
+  }
+}
+
+function formatCondition(condition: SkillCondition): string {
+  return condition.all.map((predicate) => `${predicate.fact}=${predicate.includes}`).join(' and ');
+}
+
+function formatSkillActivationConditions(skill: SkillDefinition): string {
+  return skill.activation_conditions.map((condition) => formatCondition(condition)).join(' or ');
+}
+
+function matchesCondition(context: RepoContextSnapshot, condition: SkillCondition): boolean {
+  return condition.all.every((predicate) => factValues(context, predicate.fact).includes(predicate.includes));
+}
+
+function matchesSkillActivationConditions(context: RepoContextSnapshot, skill: SkillDefinition): boolean {
+  if (skill.activation_conditions.length === 0) {
+    return true;
+  }
+
+  return skill.activation_conditions.some((condition) => matchesCondition(context, condition));
+}
+
+function assertStageCompatible(skill: SkillDefinition, stage: FlowStage): void {
+  if (!skill.stage_compatibility.includes(stage)) {
+    throw new ProdifyError(`Skill "${skill.id}" is not compatible with stage "${stage}".`, {
+      code: 'SKILL_STAGE_INCOMPATIBLE'
+    });
+  }
+}
+
+function resolveSkill(registry: Map<string, SkillDefinition>, skillId: string, stage: FlowStage): SkillDefinition {
+  const skill = registry.get(skillId);
+  if (!skill) {
+    throw new ProdifyError(`Stage skill routing references unknown skill "${skillId}".`, {
+      code: 'SKILL_NOT_FOUND'
+    });
+  }
+
+  assertStageCompatible(skill, stage);
+  return skill;
+}
+
+function defaultRecord(skill: SkillDefinition, active: boolean): SkillActivationRecord {
+  return {
+    id: skill.id,
+    name: skill.name,
+    category: skill.category,
+    source: 'default',
+    active,
+    reason: active ? 'default stage skill' : `inactive: ${formatSkillActivationConditions(skill)}`
+  };
+}
+
+function conditionalRecord(skill: SkillDefinition, conditionLabel: string, active: boolean): SkillActivationRecord {
+  return {
+    id: skill.id,
+    name: skill.name,
+    category: skill.category,
+    source: 'conditional',
+    active,
+    reason: active ? conditionLabel : `inactive: ${conditionLabel}`
+  };
+}
+
+function validateRouting(routing: StageSkillRouting, registry: Map<string, SkillDefinition>, stage: FlowStage): void {
+  for (const skillId of routing.allowed_skills) {
+    resolveSkill(registry, skillId, stage);
+  }
+}
+
+export async function resolveStageSkills(repoRoot: string, stage: FlowStage): Promise<StageSkillResolution> {
+  const [contract, registry, context] = await Promise.all([
+    loadCompiledContract(repoRoot, stage),
+    loadSkillRegistry(repoRoot),
+    detectRepoContext(repoRoot)
+  ]);
+  const routing = contract.skill_routing;
+
+  validateRouting(routing, registry, stage);
+
+  const consideredSkills: SkillActivationRecord[] = [];
+  const activeSkillIds = new Set<string>();
+
+  for (const skillId of routing.default_skills) {
+    const skill = resolveSkill(registry, skillId, stage);
+    const active = matchesSkillActivationConditions(context, skill);
+    consideredSkills.push(defaultRecord(skill, active));
+    if (active) {
+      activeSkillIds.add(skill.id);
+    }
+  }
+
+  for (const rule of routing.conditional_skills) {
+    const skill = resolveSkill(registry, rule.skill, stage);
+    const conditionLabel = rule.reason || formatCondition(rule.when);
+    const active = matchesCondition(context, rule.when) && matchesSkillActivationConditions(context, skill);
+    const existing = consideredSkills.find((entry) => entry.id === skill.id);
+    if (existing) {
+      if (active) {
+        existing.active = true;
+        existing.reason = `${existing.reason}; ${conditionLabel}`;
+        activeSkillIds.add(skill.id);
+      } else if (!existing.active && skill.activation_conditions.length > 0) {
+        existing.reason = `inactive: ${formatSkillActivationConditions(skill)}`;
+      }
+      continue;
+    }
+
+    consideredSkills.push(conditionalRecord(skill, conditionLabel, active));
+    if (active) {
+      activeSkillIds.add(skill.id);
+    }
+  }
+
+  return {
+    stage,
+    context,
+    considered_skills: consideredSkills.sort((left, right) => left.id.localeCompare(right.id)),
+    active_skill_ids: [...activeSkillIds].sort((left, right) => left.localeCompare(right))
+  };
+}

package/src/core/state.ts

@@ -0,0 +1,264 @@
+import fs from 'node:fs/promises';
+
+import { ProdifyError } from './errors.js';
+import { pathExists, writeFileEnsuringDir } from './fs.js';
+import { isRuntimeProfileName, resolveCanonicalPath } from './paths.js';
+import type {
+  ExecutionMode,
+  FlowStage,
+  ProdifyState,
+  RuntimeBootstrapMetadata,
+  RuntimeFailureMetadata,
+  RuntimeStateBlock,
+  RuntimeStatus,
+  StageValidationResult,
+  ValidationResult,
+  VersionMetadata
+} from '../types.js';
+
+export const RUNTIME_STATE_SCHEMA_VERSION = '2';
+
+export const RUNTIME_STATUS: Record<string, RuntimeStatus> = {
+  NOT_BOOTSTRAPPED: 'not_bootstrapped',
+  READY: 'ready',
+  RUNNING: 'running',
+  AWAITING_VALIDATION: 'awaiting_validation',
+  BLOCKED: 'blocked',
+  FAILED: 'failed',
+  COMPLETE: 'complete'
+};
+
+function isExecutionMode(value: unknown): value is ExecutionMode {
+  return value === 'interactive' || value === 'auto';
+}
+
+function isFlowStage(value: unknown): value is FlowStage {
+  return value === 'understand'
+    || value === 'diagnose'
+    || value === 'architecture'
+    || value === 'plan'
+    || value === 'refactor'
+    || value === 'validate';
+}
+
+function isRuntimeStatus(value: unknown): value is RuntimeStatus {
+  return value === 'not_bootstrapped'
+    || value === 'ready'
+    || value === 'running'
+    || value === 'awaiting_validation'
+    || value === 'blocked'
+    || value === 'failed'
+    || value === 'complete';
+}
+
+function isValidationResult(value: unknown): value is ValidationResult {
+  return value === 'unknown' || value === 'pass' || value === 'fail' || value === 'inconclusive';
+}
+
+function isRuntimeContractState(value: unknown): value is RuntimeStateBlock['current_state'] {
+  return typeof value === 'string' && [
+    'not_bootstrapped',
+    'bootstrapped',
+    'understand_pending',
+    'understand_complete',
+    'diagnose_pending',
+    'diagnose_complete',
+    'architecture_pending',
+    'architecture_complete',
+    'plan_pending',
+    'plan_complete',
+    'refactor_pending',
+    'refactor_complete',
+    'validate_pending',
+    'validate_complete',
+    'blocked',
+    'failed',
+    'completed'
+  ].includes(value);
+}
+
+function normalizeStageList(value: unknown): FlowStage[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter(isFlowStage);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {};
+}
+
+function normalizeBootstrapMetadata(value: unknown): RuntimeBootstrapMetadata {
+  const record = asRecord(value);
+  return {
+    bootstrapped: Boolean(record.bootstrapped)
+  };
+}
+
+function normalizeFailureMetadata(value: unknown): RuntimeFailureMetadata | null {
+  if (!value) {
+    return null;
+  }
+
+  const record = asRecord(value);
+  return {
+    stage: isFlowStage(record.stage) ? record.stage : null,
+    contract_version: typeof record.contract_version === 'string' ? record.contract_version : null,
+    reason: typeof record.reason === 'string' ? record.reason : 'unknown failure'
+  };
+}
+
+function normalizeValidation(value: unknown): StageValidationResult | null {
+  if (!value) {
+    return null;
+  }
+
+  const record = asRecord(value);
+  return {
+    stage: isFlowStage(record.stage) ? record.stage : 'understand',
+    contract_version: typeof record.contract_version === 'string' ? record.contract_version : 'unknown',
+    passed: Boolean(record.passed),
+    violated_rules: Array.isArray(record.violated_rules)
+      ? record.violated_rules
+        .map((entry) => asRecord(entry))
+        .map((entry) => ({
+          rule: typeof entry.rule === 'string' ? entry.rule : 'unknown',
+          message: typeof entry.message === 'string' ? entry.message : 'validation issue',
+          path: typeof entry.path === 'string' ? entry.path : undefined
+        }))
+      : [],
+    missing_artifacts: Array.isArray(record.missing_artifacts)
+      ? record.missing_artifacts.filter((entry): entry is string => typeof entry === 'string')
+      : [],
+    warnings: Array.isArray(record.warnings)
+      ? record.warnings.filter((entry): entry is string => typeof entry === 'string')
+      : [],
+    diagnostics: Array.isArray(record.diagnostics)
+      ? record.diagnostics.filter((entry): entry is string => typeof entry === 'string')
+      : []
+  };
+}
+
+function normalizeValidatedContractVersions(value: unknown): Partial<Record<FlowStage, string>> {
+  const record = asRecord(value);
+  const normalized: Partial<Record<FlowStage, string>> = {};
+
+  for (const [key, rawValue] of Object.entries(record)) {
+    if (isFlowStage(key) && typeof rawValue === 'string') {
+      normalized[key] = rawValue;
+    }
+  }
+
+  return normalized;
+}
+
+export function createInitialRuntimeState({ presetMetadata }: { presetMetadata: VersionMetadata }): ProdifyState {
+  return {
+    schema_version: RUNTIME_STATE_SCHEMA_VERSION,
+    preset_name: presetMetadata.name,
+    preset_version: presetMetadata.version,
+    runtime: {
+      status: RUNTIME_STATUS.NOT_BOOTSTRAPPED,
+      current_state: 'not_bootstrapped',
+      mode: null,
+      current_stage: null,
+      current_task_id: null,
+      pending_stage: null,
+      completed_stages: [],
+      awaiting_user_validation: false,
+      last_validation_result: 'unknown',
+      last_validation: null,
+      last_validated_contract_versions: {},
+      resumable: false,
+      blocked_reason: null,
+      failure_metadata: null,
+      bootstrap: {
+        bootstrapped: false
+      },
+      next_action: '$prodify-init',
+      timestamps: {
+        bootstrapped_at: null,
+        last_transition_at: null,
+        completed_at: null
+      }
+    }
+  };
+}
+
+function normalizeRuntimeBlock(runtime: unknown): RuntimeStateBlock {
+  const record = asRecord(runtime);
+  const timestamps = asRecord(record.timestamps);
+
+  return {
+    status: isRuntimeStatus(record.status) ? record.status : RUNTIME_STATUS.NOT_BOOTSTRAPPED,
+    current_state: isRuntimeContractState(record.current_state) ? record.current_state : 'not_bootstrapped',
+    mode: isExecutionMode(record.mode) ? record.mode : null,
+    current_stage: isFlowStage(record.current_stage) ? record.current_stage : null,
+    current_task_id: typeof record.current_task_id === 'string' ? record.current_task_id : null,
+    pending_stage: isFlowStage(record.pending_stage) ? record.pending_stage : null,
+    completed_stages: normalizeStageList(record.completed_stages),
+    awaiting_user_validation: Boolean(record.awaiting_user_validation),
+    last_validation_result: isValidationResult(record.last_validation_result) ? record.last_validation_result : 'unknown',
+    last_validation: normalizeValidation(record.last_validation),
+    last_validated_contract_versions: normalizeValidatedContractVersions(record.last_validated_contract_versions),
+    resumable: Boolean(record.resumable),
+    blocked_reason: typeof record.blocked_reason === 'string' ? record.blocked_reason : null,
+    failure_metadata: normalizeFailureMetadata(record.failure_metadata),
+    bootstrap: normalizeBootstrapMetadata(record.bootstrap),
+    next_action: typeof record.next_action === 'string' ? record.next_action : '$prodify-init',
+    timestamps: {
+      bootstrapped_at: typeof timestamps.bootstrapped_at === 'string' ? timestamps.bootstrapped_at : null,
+      last_transition_at: typeof timestamps.last_transition_at === 'string' ? timestamps.last_transition_at : null,
+      completed_at: typeof timestamps.completed_at === 'string' ? timestamps.completed_at : null
+    }
+  };
+}
+
+export function normalizeRuntimeState(raw: unknown, { presetMetadata }: { presetMetadata: VersionMetadata }): ProdifyState {
+  const record = asRecord(raw);
+  const base = createInitialRuntimeState({ presetMetadata });
+
+  return {
+    ...base,
+    schema_version: base.schema_version,
+    preset_name: presetMetadata.name,
+    preset_version: presetMetadata.version,
+    runtime: normalizeRuntimeBlock(record.runtime)
+  };
+}
+
+export function serializeRuntimeState(state: ProdifyState): string {
+  return `${JSON.stringify(state, null, 2)}\n`;
+}
+
+export async function readRuntimeState(
+  repoRoot: string,
+  { allowMissing = false, presetMetadata }: { allowMissing?: boolean; presetMetadata: VersionMetadata }
+): Promise<ProdifyState | null> {
+  const statePath = resolveCanonicalPath(repoRoot, '.prodify/state.json');
+
+  if (!(await pathExists(statePath))) {
+    if (allowMissing) {
+      return null;
+    }
+
+    throw new ProdifyError('Runtime state is missing: .prodify/state.json', {
+      code: 'RUNTIME_STATE_MISSING'
+    });
+  }
+
+  try {
+    const raw = JSON.parse(await fs.readFile(statePath, 'utf8'));
+    return normalizeRuntimeState(raw, { presetMetadata });
+  } catch {
+    throw new ProdifyError('Runtime state is malformed: .prodify/state.json', {
+      code: 'RUNTIME_STATE_MALFORMED'
+    });
+  }
+}
+
+export async function writeRuntimeState(repoRoot: string, state: ProdifyState): Promise<void> {
+  const statePath = resolveCanonicalPath(repoRoot, '.prodify/state.json');
+  await writeFileEnsuringDir(statePath, serializeRuntimeState(state));
+}