@dedesfr/prompter 0.6.14 → 0.7.0

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

@@ -0,0 +1,226 @@
+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

@@ -0,0 +1,124 @@
+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

@@ -0,0 +1,64 @@
+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;
+}

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

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+// Artifact definition schema
+export const ArtifactSchema = z.object({
+  id: z.string().min(1, { error: 'Artifact ID is required' }),
+  generates: z.string().min(1, { error: 'generates field is required' }),
+  description: z.string(),
+  template: z.string().min(1, { error: 'template field is required' }),
+  instruction: z.string().optional(),
+  requires: z.array(z.string()).default([]),
+});
+
+// Apply phase configuration for schema-aware apply instructions
+export const ApplyPhaseSchema = z.object({
+  // Artifact IDs that must exist before apply is available
+  requires: z.array(z.string()).min(1, { error: 'At least one required artifact' }),
+  // Path to file with checkboxes for progress (relative to change dir), or null if no tracking
+  tracks: z.string().nullable().optional(),
+  // Custom guidance for the apply phase
+  instruction: z.string().optional(),
+});
+
+// Full schema YAML structure
+export const SchemaYamlSchema = z.object({
+  name: z.string().min(1, { error: 'Schema name is required' }),
+  version: z.number().int().positive({ error: 'Version must be a positive integer' }),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+  // Optional apply phase configuration (for schema-aware apply instructions)
+  apply: ApplyPhaseSchema.optional(),
+});
+
+// Derived TypeScript types
+export type Artifact = z.infer<typeof ArtifactSchema>;
+export type ApplyPhase = z.infer<typeof ApplyPhaseSchema>;
+export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+
+// Per-change metadata schema
+// Note: schema field is validated at parse time against available schemas
+// using a lazy import to avoid circular dependencies
+export const ChangeMetadataSchema = z.object({
+  // Required: which workflow schema this change uses
+  schema: z.string().min(1, { message: 'schema is required' }),
+
+  // Optional: creation timestamp (ISO date string)
+  created: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, {
+      message: 'created must be YYYY-MM-DD format',
+    })
+    .optional(),
+});
+
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+
+// Runtime state types (not Zod - internal only)
+
+// Slice 1: Simple completion tracking via filesystem
+export type CompletedSet = Set<string>;
+
+// Return type for blocked query
+export interface BlockedArtifacts {
+  [artifactId: string]: string[];
+}
+