@dedesfr/prompter 0.9.0 → 1.0.0

package/src/core/artifact-graph/instruction-loader.ts

@@ -1,302 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { getSchemaDir, resolveSchema } from './resolver.js';
-import { ArtifactGraph } from './graph.js';
-import { detectCompleted } from './state.js';
-import { resolveSchemaForChange } from '../../utils/change-metadata.js';
-import type { Artifact, CompletedSet } from './types.js';
-
-/**
- * Error thrown when loading a template fails.
- */
-export class TemplateLoadError extends Error {
-  constructor(
-    message: string,
-    public readonly templatePath: string
-  ) {
-    super(message);
-    this.name = 'TemplateLoadError';
-  }
-}
-
-/**
- * Change context containing graph, completion state, and metadata.
- */
-export interface ChangeContext {
-  /** The artifact dependency graph */
-  graph: ArtifactGraph;
-  /** Set of completed artifact IDs */
-  completed: CompletedSet;
-  /** Schema name being used */
-  schemaName: string;
-  /** Change name */
-  changeName: string;
-  /** Path to the change directory */
-  changeDir: string;
-}
-
-/**
- * Enriched instructions for creating an artifact.
- */
-export interface ArtifactInstructions {
-  /** Change name */
-  changeName: string;
-  /** Artifact ID */
-  artifactId: string;
-  /** Schema name */
-  schemaName: string;
-  /** Full path to change directory */
-  changeDir: string;
-  /** Output path pattern (e.g., "proposal.md") */
-  outputPath: string;
-  /** Artifact description */
-  description: string;
-  /** Guidance on how to create this artifact (from schema instruction field) */
-  instruction: string | undefined;
-  /** Template content (structure to follow) */
-  template: string;
-  /** Dependencies with completion status and paths */
-  dependencies: DependencyInfo[];
-  /** Artifacts that become available after completing this one */
-  unlocks: string[];
-}
-
-/**
- * Dependency information including path and description.
- */
-export interface DependencyInfo {
-  /** Artifact ID */
-  id: string;
-  /** Whether the dependency is completed */
-  done: boolean;
-  /** Relative output path of the dependency (e.g., "proposal.md") */
-  path: string;
-  /** Description of the dependency artifact */
-  description: string;
-}
-
-/**
- * Status of a single artifact in the workflow.
- */
-export interface ArtifactStatus {
-  /** Artifact ID */
-  id: string;
-  /** Output path pattern */
-  outputPath: string;
-  /** Status: done, ready, or blocked */
-  status: 'done' | 'ready' | 'blocked';
-  /** Missing dependencies (only for blocked) */
-  missingDeps?: string[];
-}
-
-/**
- * Formatted change status.
- */
-export interface ChangeStatus {
-  /** Change name */
-  changeName: string;
-  /** Schema name */
-  schemaName: string;
-  /** Whether all artifacts are complete */
-  isComplete: boolean;
-  /** Artifact IDs required before apply phase (from schema's apply.requires) */
-  applyRequires: string[];
-  /** Status of each artifact */
-  artifacts: ArtifactStatus[];
-}
-
-/**
- * Loads a template from a schema's templates directory.
- *
- * @param schemaName - Schema name (e.g., "spec-driven")
- * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
- * @returns The template content
- * @throws TemplateLoadError if the template cannot be loaded
- */
-export function loadTemplate(schemaName: string, templatePath: string): string {
-  const schemaDir = getSchemaDir(schemaName);
-  if (!schemaDir) {
-    throw new TemplateLoadError(
-      `Schema '${schemaName}' not found`,
-      templatePath
-    );
-  }
-
-  const fullPath = path.join(schemaDir, 'templates', templatePath);
-
-  if (!fs.existsSync(fullPath)) {
-    throw new TemplateLoadError(
-      `Template not found: ${fullPath}`,
-      fullPath
-    );
-  }
-
-  try {
-    return fs.readFileSync(fullPath, 'utf-8');
-  } catch (err) {
-    const ioError = err instanceof Error ? err : new Error(String(err));
-    throw new TemplateLoadError(
-      `Failed to read template: ${ioError.message}`,
-      fullPath
-    );
-  }
-}
-
-/**
- * Loads change context combining graph and completion state.
- *
- * Schema resolution order:
- * 1. Explicit schemaName parameter (if provided)
- * 2. Schema from .prompter.yaml metadata (if exists in change directory)
- * 3. Default 'spec-driven'
- *
- * @param projectRoot - Project root directory
- * @param changeName - Change name
- * @param schemaName - Optional schema name override. If not provided, auto-detected from metadata.
- * @returns Change context with graph, completed set, and metadata
- */
-export function loadChangeContext(
-  projectRoot: string,
-  changeName: string,
-  schemaName?: string
-): ChangeContext {
-  const changeDir = path.join(projectRoot, 'prompter', 'changes', changeName);
-
-  // Resolve schema: explicit > metadata > default
-  const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
-
-  const schema = resolveSchema(resolvedSchemaName);
-  const graph = ArtifactGraph.fromSchema(schema);
-  const completed = detectCompleted(graph, changeDir);
-
-  return {
-    graph,
-    completed,
-    schemaName: resolvedSchemaName,
-    changeName,
-    changeDir,
-  };
-}
-
-/**
- * Generates enriched instructions for creating an artifact.
- *
- * @param context - Change context
- * @param artifactId - Artifact ID to generate instructions for
- * @returns Enriched artifact instructions
- * @throws Error if artifact not found
- */
-export function generateInstructions(
-  context: ChangeContext,
-  artifactId: string
-): ArtifactInstructions {
-  const artifact = context.graph.getArtifact(artifactId);
-  if (!artifact) {
-    throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
-  }
-
-  const template = loadTemplate(context.schemaName, artifact.template);
-  const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
-  const unlocks = getUnlockedArtifacts(context.graph, artifactId);
-
-  return {
-    changeName: context.changeName,
-    artifactId: artifact.id,
-    schemaName: context.schemaName,
-    changeDir: context.changeDir,
-    outputPath: artifact.generates,
-    description: artifact.description,
-    instruction: artifact.instruction,
-    template,
-    dependencies,
-    unlocks,
-  };
-}
-
-/**
- * Gets dependency info including paths and descriptions.
- */
-function getDependencyInfo(
-  artifact: Artifact,
-  graph: ArtifactGraph,
-  completed: CompletedSet
-): DependencyInfo[] {
-  return artifact.requires.map(id => {
-    const depArtifact = graph.getArtifact(id);
-    return {
-      id,
-      done: completed.has(id),
-      path: depArtifact?.generates ?? id,
-      description: depArtifact?.description ?? '',
-    };
-  });
-}
-
-/**
- * Gets artifacts that become available after completing the given artifact.
- */
-function getUnlockedArtifacts(graph: ArtifactGraph, artifactId: string): string[] {
-  const unlocks: string[] = [];
-
-  for (const artifact of graph.getAllArtifacts()) {
-    if (artifact.requires.includes(artifactId)) {
-      unlocks.push(artifact.id);
-    }
-  }
-
-  return unlocks.sort();
-}
-
-/**
- * Formats the status of all artifacts in a change.
- *
- * @param context - Change context
- * @returns Formatted change status
- */
-export function formatChangeStatus(context: ChangeContext): ChangeStatus {
-  // Load schema to get apply phase configuration
-  const schema = resolveSchema(context.schemaName);
-  const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
-
-  const artifacts = context.graph.getAllArtifacts();
-  const ready = new Set(context.graph.getNextArtifacts(context.completed));
-  const blocked = context.graph.getBlocked(context.completed);
-
-  const artifactStatuses: ArtifactStatus[] = artifacts.map(artifact => {
-    if (context.completed.has(artifact.id)) {
-      return {
-        id: artifact.id,
-        outputPath: artifact.generates,
-        status: 'done' as const,
-      };
-    }
-
-    if (ready.has(artifact.id)) {
-      return {
-        id: artifact.id,
-        outputPath: artifact.generates,
-        status: 'ready' as const,
-      };
-    }
-
-    return {
-      id: artifact.id,
-      outputPath: artifact.generates,
-      status: 'blocked' as const,
-      missingDeps: blocked[artifact.id] ?? [],
-    };
-  });
-
-  // Sort by build order for consistent output
-  const buildOrder = context.graph.getBuildOrder();
-  const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
-  artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
-
-  return {
-    changeName: context.changeName,
-    schemaName: context.schemaName,
-    isComplete: context.graph.isComplete(context.completed),
-    applyRequires,
-    artifacts: artifactStatuses,
-  };
-}

package/src/core/artifact-graph/resolver.ts

@@ -1,226 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { getGlobalDataDir } from '../global-config.js';
-import { parseSchema, SchemaValidationError } from './schema.js';
-import type { SchemaYaml } from './types.js';
-
-/**
- * Error thrown when loading a schema fails.
- */
-export class SchemaLoadError extends Error {
-  constructor(
-    message: string,
-    public readonly schemaPath: string,
-    public readonly cause?: Error
-  ) {
-    super(message);
-    this.name = 'SchemaLoadError';
-  }
-}
-
-/**
- * Gets the package's built-in schemas directory path.
- * Uses import.meta.url to resolve relative to the current module.
- */
-export function getPackageSchemasDir(): string {
-  const currentFile = fileURLToPath(import.meta.url);
-  // Navigate from dist/core/artifact-graph/ to package root's schemas/
-  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
-}
-
-/**
- * Gets the user's schema override directory path.
- */
-export function getUserSchemasDir(): string {
-  return path.join(getGlobalDataDir(), 'schemas');
-}
-
-/**
- * Resolves a schema name to its directory path.
- *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/prompter/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
- *
- * @param name - Schema name (e.g., "spec-driven")
- * @returns The path to the schema directory, or null if not found
- */
-export function getSchemaDir(name: string): string | null {
-  // 1. Check user override directory
-  const userDir = path.join(getUserSchemasDir(), name);
-  const userSchemaPath = path.join(userDir, 'schema.yaml');
-  if (fs.existsSync(userSchemaPath)) {
-    return userDir;
-  }
-
-  // 2. Check package built-in directory
-  const packageDir = path.join(getPackageSchemasDir(), name);
-  const packageSchemaPath = path.join(packageDir, 'schema.yaml');
-  if (fs.existsSync(packageSchemaPath)) {
-    return packageDir;
-  }
-
-  return null;
-}
-
-/**
- * Resolves a schema name to a SchemaYaml object.
- *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/prompter/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
- *
- * @param name - Schema name (e.g., "spec-driven")
- * @returns The resolved schema object
- * @throws Error if schema is not found in any location
- */
-export function resolveSchema(name: string): SchemaYaml {
-  // Normalize name (remove .yaml extension if provided)
-  const normalizedName = name.replace(/\.ya?ml$/, '');
-
-  const schemaDir = getSchemaDir(normalizedName);
-  if (!schemaDir) {
-    const availableSchemas = listSchemas();
-    throw new Error(
-      `Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`
-    );
-  }
-
-  const schemaPath = path.join(schemaDir, 'schema.yaml');
-
-  // Load and parse the schema
-  let content: string;
-  try {
-    content = fs.readFileSync(schemaPath, 'utf-8');
-  } catch (err) {
-    const ioError = err instanceof Error ? err : new Error(String(err));
-    throw new SchemaLoadError(
-      `Failed to read schema at '${schemaPath}': ${ioError.message}`,
-      schemaPath,
-      ioError
-    );
-  }
-
-  try {
-    return parseSchema(content);
-  } catch (err) {
-    if (err instanceof SchemaValidationError) {
-      throw new SchemaLoadError(
-        `Invalid schema at '${schemaPath}': ${err.message}`,
-        schemaPath,
-        err
-      );
-    }
-    const parseError = err instanceof Error ? err : new Error(String(err));
-    throw new SchemaLoadError(
-      `Failed to parse schema at '${schemaPath}': ${parseError.message}`,
-      schemaPath,
-      parseError
-    );
-  }
-}
-
-/**
- * Lists all available schema names.
- * Combines user override and package built-in schemas.
- */
-export function listSchemas(): string[] {
-  const schemas = new Set<string>();
-
-  // Add package built-in schemas
-  const packageDir = getPackageSchemasDir();
-  if (fs.existsSync(packageDir)) {
-    for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
-        if (fs.existsSync(schemaPath)) {
-          schemas.add(entry.name);
-        }
-      }
-    }
-  }
-
-  // Add user override schemas (may override package schemas)
-  const userDir = getUserSchemasDir();
-  if (fs.existsSync(userDir)) {
-    for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
-        if (fs.existsSync(schemaPath)) {
-          schemas.add(entry.name);
-        }
-      }
-    }
-  }
-
-  return Array.from(schemas).sort();
-}
-
-/**
- * Schema info with metadata (name, description, artifacts).
- */
-export interface SchemaInfo {
-  name: string;
-  description: string;
-  artifacts: string[];
-  source: 'package' | 'user';
-}
-
-/**
- * Lists all available schemas with their descriptions and artifact lists.
- * Useful for agent skills to present schema selection to users.
- */
-export function listSchemasWithInfo(): SchemaInfo[] {
-  const schemas: SchemaInfo[] = [];
-  const seenNames = new Set<string>();
-
-  // Add user override schemas first (they take precedence)
-  const userDir = getUserSchemasDir();
-  if (fs.existsSync(userDir)) {
-    for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
-        if (fs.existsSync(schemaPath)) {
-          try {
-            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
-            schemas.push({
-              name: entry.name,
-              description: schema.description || '',
-              artifacts: schema.artifacts.map((a) => a.id),
-              source: 'user',
-            });
-            seenNames.add(entry.name);
-          } catch {
-            // Skip invalid schemas
-          }
-        }
-      }
-    }
-  }
-
-  // Add package built-in schemas (if not overridden)
-  const packageDir = getPackageSchemasDir();
-  if (fs.existsSync(packageDir)) {
-    for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && !seenNames.has(entry.name)) {
-        const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
-        if (fs.existsSync(schemaPath)) {
-          try {
-            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
-            schemas.push({
-              name: entry.name,
-              description: schema.description || '',
-              artifacts: schema.artifacts.map((a) => a.id),
-              source: 'package',
-            });
-          } catch {
-            // Skip invalid schemas
-          }
-        }
-      }
-    }
-  }
-
-  return schemas.sort((a, b) => a.name.localeCompare(b.name));
-}

package/src/core/artifact-graph/schema.ts

@@ -1,124 +0,0 @@
-import * as fs from 'node:fs';
-import { parse as parseYaml } from 'yaml';
-import { SchemaYamlSchema, type SchemaYaml, type Artifact } from './types.js';
-
-export class SchemaValidationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'SchemaValidationError';
-  }
-}
-
-/**
- * Loads and validates an artifact schema from a YAML file.
- */
-export function loadSchema(filePath: string): SchemaYaml {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  return parseSchema(content);
-}
-
-/**
- * Parses and validates an artifact schema from YAML content.
- */
-export function parseSchema(yamlContent: string): SchemaYaml {
-  const parsed = parseYaml(yamlContent);
-
-  // Validate with Zod
-  const result = SchemaYamlSchema.safeParse(parsed);
-  if (!result.success) {
-    const errors = result.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
-    throw new SchemaValidationError(`Invalid schema: ${errors}`);
-  }
-
-  const schema = result.data;
-
-  // Check for duplicate artifact IDs
-  validateNoDuplicateIds(schema.artifacts);
-
-  // Check that all requires references are valid
-  validateRequiresReferences(schema.artifacts);
-
-  // Check for cycles
-  validateNoCycles(schema.artifacts);
-
-  return schema;
-}
-
-/**
- * Validates that there are no duplicate artifact IDs.
- */
-function validateNoDuplicateIds(artifacts: Artifact[]): void {
-  const seen = new Set<string>();
-  for (const artifact of artifacts) {
-    if (seen.has(artifact.id)) {
-      throw new SchemaValidationError(`Duplicate artifact ID: ${artifact.id}`);
-    }
-    seen.add(artifact.id);
-  }
-}
-
-/**
- * Validates that all `requires` references point to valid artifact IDs.
- */
-function validateRequiresReferences(artifacts: Artifact[]): void {
-  const validIds = new Set(artifacts.map(a => a.id));
-
-  for (const artifact of artifacts) {
-    for (const req of artifact.requires) {
-      if (!validIds.has(req)) {
-        throw new SchemaValidationError(
-          `Invalid dependency reference in artifact '${artifact.id}': '${req}' does not exist`
-        );
-      }
-    }
-  }
-}
-
-/**
- * Validates that there are no cyclic dependencies.
- * Uses DFS to detect cycles and reports the full cycle path.
- */
-function validateNoCycles(artifacts: Artifact[]): void {
-  const artifactMap = new Map(artifacts.map(a => [a.id, a]));
-  const visited = new Set<string>();
-  const inStack = new Set<string>();
-  const parent = new Map<string, string>();
-
-  function dfs(id: string): string | null {
-    visited.add(id);
-    inStack.add(id);
-
-    const artifact = artifactMap.get(id);
-    if (!artifact) return null;
-
-    for (const dep of artifact.requires) {
-      if (!visited.has(dep)) {
-        parent.set(dep, id);
-        const cycle = dfs(dep);
-        if (cycle) return cycle;
-      } else if (inStack.has(dep)) {
-        // Found a cycle - reconstruct the path
-        const cyclePath = [dep];
-        let current = id;
-        while (current !== dep) {
-          cyclePath.unshift(current);
-          current = parent.get(current)!;
-        }
-        cyclePath.unshift(dep);
-        return cyclePath.join(' → ');
-      }
-    }
-
-    inStack.delete(id);
-    return null;
-  }
-
-  for (const artifact of artifacts) {
-    if (!visited.has(artifact.id)) {
-      const cycle = dfs(artifact.id);
-      if (cycle) {
-        throw new SchemaValidationError(`Cyclic dependency detected: ${cycle}`);
-      }
-    }
-  }
-}

package/src/core/artifact-graph/state.ts

@@ -1,64 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import fg from 'fast-glob';
-import type { CompletedSet } from './types.js';
-import type { ArtifactGraph } from './graph.js';
-import { FileSystemUtils } from '../../utils/file-system.js';
-
-/**
- * Detects which artifacts are completed by checking file existence in the change directory.
- * Returns a Set of completed artifact IDs.
- *
- * @param graph - The artifact graph to check
- * @param changeDir - The change directory to scan for files
- * @returns Set of artifact IDs whose generated files exist
- */
-export function detectCompleted(graph: ArtifactGraph, changeDir: string): CompletedSet {
-  const completed = new Set<string>();
-
-  // Handle missing change directory gracefully
-  if (!fs.existsSync(changeDir)) {
-    return completed;
-  }
-
-  for (const artifact of graph.getAllArtifacts()) {
-    if (isArtifactComplete(artifact.generates, changeDir)) {
-      completed.add(artifact.id);
-    }
-  }
-
-  return completed;
-}
-
-/**
- * Checks if an artifact is complete by checking if its generated file(s) exist.
- * Supports both simple paths and glob patterns.
- */
-function isArtifactComplete(generates: string, changeDir: string): boolean {
-  const fullPattern = path.join(changeDir, generates);
-
-  // Check if it's a glob pattern
-  if (isGlobPattern(generates)) {
-    return hasGlobMatches(fullPattern);
-  }
-
-  // Simple file path - check if file exists
-  return fs.existsSync(fullPattern);
-}
-
-/**
- * Checks if a path contains glob pattern characters.
- */
-function isGlobPattern(pattern: string): boolean {
-  return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
-}
-
-/**
- * Checks if a glob pattern has any matches.
- * Normalizes Windows backslashes to forward slashes for cross-platform glob compatibility.
- */
-function hasGlobMatches(pattern: string): boolean {
-  const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
-  const matches = fg.sync(normalizedPattern, { onlyFiles: true });
-  return matches.length > 0;
-}