@dedesfr/prompter 0.9.0 → 1.0.0

package/src/utils/change-metadata.ts

@@ -1,171 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as yaml from 'yaml';
-import { ChangeMetadataSchema, type ChangeMetadata } from '../core/artifact-graph/types.js';
-import { listSchemas } from '../core/artifact-graph/resolver.js';
-
-const METADATA_FILENAME = '.prompter.yaml';
-
-/**
- * Error thrown when change metadata validation fails.
- */
-export class ChangeMetadataError extends Error {
-  constructor(
-    message: string,
-    public readonly metadataPath: string,
-    public readonly cause?: Error
-  ) {
-    super(message);
-    this.name = 'ChangeMetadataError';
-  }
-}
-
-/**
- * Validates that a schema name is valid (exists in available schemas).
- *
- * @param schemaName - The schema name to validate
- * @returns The validated schema name
- * @throws Error if schema is not found
- */
-export function validateSchemaName(schemaName: string): string {
-  const availableSchemas = listSchemas();
-  if (!availableSchemas.includes(schemaName)) {
-    throw new Error(
-      `Unknown schema '${schemaName}'. Available: ${availableSchemas.join(', ')}`
-    );
-  }
-  return schemaName;
-}
-
-/**
- * Writes change metadata to .prompter.yaml in the change directory.
- *
- * @param changeDir - The path to the change directory
- * @param metadata - The metadata to write
- * @throws ChangeMetadataError if validation fails or write fails
- */
-export function writeChangeMetadata(
-  changeDir: string,
-  metadata: ChangeMetadata
-): void {
-  const metaPath = path.join(changeDir, METADATA_FILENAME);
-
-  // Validate schema exists
-  validateSchemaName(metadata.schema);
-
-  // Validate with Zod
-  const parseResult = ChangeMetadataSchema.safeParse(metadata);
-  if (!parseResult.success) {
-    throw new ChangeMetadataError(
-      `Invalid metadata: ${parseResult.error.message}`,
-      metaPath
-    );
-  }
-
-  // Write YAML file
-  const content = yaml.stringify(parseResult.data);
-  try {
-    fs.writeFileSync(metaPath, content, 'utf-8');
-  } catch (err) {
-    const ioError = err instanceof Error ? err : new Error(String(err));
-    throw new ChangeMetadataError(
-      `Failed to write metadata: ${ioError.message}`,
-      metaPath,
-      ioError
-    );
-  }
-}
-
-/**
- * Reads change metadata from .prompter.yaml in the change directory.
- *
- * @param changeDir - The path to the change directory
- * @returns The validated metadata, or null if no metadata file exists
- * @throws ChangeMetadataError if the file exists but is invalid
- */
-export function readChangeMetadata(changeDir: string): ChangeMetadata | null {
-  const metaPath = path.join(changeDir, METADATA_FILENAME);
-
-  if (!fs.existsSync(metaPath)) {
-    return null;
-  }
-
-  let content: string;
-  try {
-    content = fs.readFileSync(metaPath, 'utf-8');
-  } catch (err) {
-    const ioError = err instanceof Error ? err : new Error(String(err));
-    throw new ChangeMetadataError(
-      `Failed to read metadata: ${ioError.message}`,
-      metaPath,
-      ioError
-    );
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = yaml.parse(content);
-  } catch (err) {
-    const parseError = err instanceof Error ? err : new Error(String(err));
-    throw new ChangeMetadataError(
-      `Invalid YAML in metadata file: ${parseError.message}`,
-      metaPath,
-      parseError
-    );
-  }
-
-  // Validate with Zod
-  const parseResult = ChangeMetadataSchema.safeParse(parsed);
-  if (!parseResult.success) {
-    throw new ChangeMetadataError(
-      `Invalid metadata: ${parseResult.error.message}`,
-      metaPath
-    );
-  }
-
-  // Validate that the schema exists
-  const availableSchemas = listSchemas();
-  if (!availableSchemas.includes(parseResult.data.schema)) {
-    throw new ChangeMetadataError(
-      `Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`,
-      metaPath
-    );
-  }
-
-  return parseResult.data;
-}
-
-/**
- * Resolves the schema for a change, with explicit override taking precedence.
- *
- * Resolution order:
- * 1. Explicit schema (if provided)
- * 2. Schema from .prompter.yaml metadata (if exists)
- * 3. Default 'spec-driven'
- *
- * @param changeDir - The path to the change directory
- * @param explicitSchema - Optional explicit schema override
- * @returns The resolved schema name
- */
-export function resolveSchemaForChange(
-  changeDir: string,
-  explicitSchema?: string
-): string {
-  // 1. Explicit override wins
-  if (explicitSchema) {
-    return explicitSchema;
-  }
-
-  // 2. Try reading from metadata
-  try {
-    const metadata = readChangeMetadata(changeDir);
-    if (metadata?.schema) {
-      return metadata.schema;
-    }
-  } catch {
-    // If metadata read fails, fall back to default
-  }
-
-  // 3. Default
-  return 'spec-driven';
-}

package/src/utils/change-utils.ts

@@ -1,131 +0,0 @@
-import path from 'path';
-import { FileSystemUtils } from './file-system.js';
-import { writeChangeMetadata, validateSchemaName } from './change-metadata.js';
-
-const DEFAULT_SCHEMA = 'spec-driven';
-
-/**
- * Options for creating a change.
- */
-export interface CreateChangeOptions {
-  /** The workflow schema to use (default: 'spec-driven') */
-  schema?: string;
-}
-
-/**
- * Result of validating a change name.
- */
-export interface ValidationResult {
-  valid: boolean;
-  error?: string;
-}
-
-/**
- * Validates that a change name follows kebab-case conventions.
- *
- * Valid names:
- * - Start with a lowercase letter
- * - Contain only lowercase letters, numbers, and hyphens
- * - Do not start or end with a hyphen
- * - Do not contain consecutive hyphens
- *
- * @param name - The change name to validate
- * @returns Validation result with `valid: true` or `valid: false` with an error message
- *
- * @example
- * validateChangeName('add-auth') // { valid: true }
- * validateChangeName('Add-Auth') // { valid: false, error: '...' }
- */
-export function validateChangeName(name: string): ValidationResult {
-  // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
-  // optionally followed by hyphen + lowercase letters/numbers (repeatable)
-  const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-
-  if (!name) {
-    return { valid: false, error: 'Change name cannot be empty' };
-  }
-
-  if (!kebabCasePattern.test(name)) {
-    // Provide specific error messages for common mistakes
-    if (/[A-Z]/.test(name)) {
-      return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
-    }
-    if (/\s/.test(name)) {
-      return { valid: false, error: 'Change name cannot contain spaces (use hyphens instead)' };
-    }
-    if (/_/.test(name)) {
-      return { valid: false, error: 'Change name cannot contain underscores (use hyphens instead)' };
-    }
-    if (name.startsWith('-')) {
-      return { valid: false, error: 'Change name cannot start with a hyphen' };
-    }
-    if (name.endsWith('-')) {
-      return { valid: false, error: 'Change name cannot end with a hyphen' };
-    }
-    if (/--/.test(name)) {
-      return { valid: false, error: 'Change name cannot contain consecutive hyphens' };
-    }
-    if (/[^a-z0-9-]/.test(name)) {
-      return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
-    }
-    if (/^[0-9]/.test(name)) {
-      return { valid: false, error: 'Change name must start with a letter' };
-    }
-
-    return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
-  }
-
-  return { valid: true };
-}
-
-/**
- * Creates a new change directory with metadata file.
- *
- * @param projectRoot - The root directory of the project (where `prompter/` lives)
- * @param name - The change name (must be valid kebab-case)
- * @param options - Optional settings for the change
- * @throws Error if the change name is invalid
- * @throws Error if the schema name is invalid
- * @throws Error if the change directory already exists
- *
- * @example
- * // Creates prompter/changes/add-auth/ with default schema
- * await createChange('/path/to/project', 'add-auth')
- *
- * @example
- * // Creates prompter/changes/add-auth/ with TDD schema
- * await createChange('/path/to/project', 'add-auth', { schema: 'tdd' })
- */
-export async function createChange(
-  projectRoot: string,
-  name: string,
-  options: CreateChangeOptions = {}
-): Promise<void> {
-  // Validate the name first
-  const validation = validateChangeName(name);
-  if (!validation.valid) {
-    throw new Error(validation.error);
-  }
-
-  // Determine schema (validate if provided)
-  const schemaName = options.schema ?? DEFAULT_SCHEMA;
-  validateSchemaName(schemaName);
-
-  // Build the change directory path
-  const changeDir = path.join(projectRoot, 'prompter', 'changes', name);
-
-  // Check if change already exists
-  if (await FileSystemUtils.directoryExists(changeDir)) {
-    throw new Error(`Change '${name}' already exists at ${changeDir}`);
-  }
-
-  // Create the directory (including parent directories if needed)
-  await FileSystemUtils.createDirectory(changeDir);
-
-  // Write metadata file with schema and creation date
-  const today = new Date().toISOString().split('T')[0];
-  writeChangeMetadata(changeDir, {
-    schema: schemaName,
-    created: today,
-  });
-}

package/src/utils/file-system.ts

@@ -1,252 +0,0 @@
-import { promises as fs, constants as fsConstants } from 'fs';
-import path from 'path';
-
-function isMarkerOnOwnLine(content: string, markerIndex: number, markerLength: number): boolean {
-  let leftIndex = markerIndex - 1;
-  while (leftIndex >= 0 && content[leftIndex] !== '\n') {
-    const char = content[leftIndex];
-    if (char !== ' ' && char !== '\t' && char !== '\r') {
-      return false;
-    }
-    leftIndex--;
-  }
-
-  let rightIndex = markerIndex + markerLength;
-  while (rightIndex < content.length && content[rightIndex] !== '\n') {
-    const char = content[rightIndex];
-    if (char !== ' ' && char !== '\t' && char !== '\r') {
-      return false;
-    }
-    rightIndex++;
-  }
-
-  return true;
-}
-
-function findMarkerIndex(
-  content: string,
-  marker: string,
-  fromIndex = 0
-): number {
-  let currentIndex = content.indexOf(marker, fromIndex);
-
-  while (currentIndex !== -1) {
-    if (isMarkerOnOwnLine(content, currentIndex, marker.length)) {
-      return currentIndex;
-    }
-
-    currentIndex = content.indexOf(marker, currentIndex + marker.length);
-  }
-
-  return -1;
-}
-
-export class FileSystemUtils {
-  /**
-   * Converts a path to use forward slashes (POSIX style).
-   * Essential for cross-platform compatibility with glob libraries like fast-glob.
-   */
-  static toPosixPath(p: string): string {
-    return p.replace(/\\/g, '/');
-  }
-
-  private static isWindowsBasePath(basePath: string): boolean {
-    return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
-  }
-
-  private static normalizeSegments(segments: string[]): string[] {
-    return segments
-      .flatMap((segment) => segment.split(/[\\/]+/u))
-      .filter((part) => part.length > 0);
-  }
-
-  static joinPath(basePath: string, ...segments: string[]): string {
-    const normalizedSegments = this.normalizeSegments(segments);
-
-    if (this.isWindowsBasePath(basePath)) {
-      const normalizedBasePath = path.win32.normalize(basePath);
-      return normalizedSegments.length
-        ? path.win32.join(normalizedBasePath, ...normalizedSegments)
-        : normalizedBasePath;
-    }
-
-    const posixBasePath = basePath.replace(/\\/g, '/');
-
-    return normalizedSegments.length
-      ? path.posix.join(posixBasePath, ...normalizedSegments)
-      : path.posix.normalize(posixBasePath);
-  }
-
-  static async createDirectory(dirPath: string): Promise<void> {
-    await fs.mkdir(dirPath, { recursive: true });
-  }
-
-  static async fileExists(filePath: string): Promise<boolean> {
-    try {
-      await fs.access(filePath);
-      return true;
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
-        console.debug(`Unable to check if file exists at ${filePath}: ${error.message}`);
-      }
-      return false;
-    }
-  }
-
-  /**
-   * Finds the first existing parent directory by walking up the directory tree.
-   * @param dirPath Starting directory path
-   * @returns The first existing directory path, or null if root is reached without finding one
-   */
-  private static async findFirstExistingDirectory(dirPath: string): Promise<string | null> {
-    let currentDir = dirPath;
-
-    while (true) {
-      try {
-        const stats = await fs.stat(currentDir);
-        if (stats.isDirectory()) {
-          return currentDir;
-        }
-        // Path component exists but is not a directory (edge case)
-        console.debug(`Path component ${currentDir} exists but is not a directory`);
-        return null;
-      } catch (error: any) {
-        if (error.code === 'ENOENT') {
-          // Directory doesn't exist, move up one level
-          const parentDir = path.dirname(currentDir);
-          if (parentDir === currentDir) {
-            // Reached filesystem root without finding existing directory
-            return null;
-          }
-          currentDir = parentDir;
-        } else {
-          // Unexpected error (permissions, I/O error, etc.)
-          console.debug(`Error checking directory ${currentDir}: ${error.message}`);
-          return null;
-        }
-      }
-    }
-  }
-
-  static async canWriteFile(filePath: string): Promise<boolean> {
-    try {
-      const stats = await fs.stat(filePath);
-
-      if (!stats.isFile()) {
-        return true;
-      }
-
-      // On Windows, stats.mode doesn't reliably indicate write permissions.
-      // Use fs.access with W_OK to check actual write permissions cross-platform.
-      try {
-        await fs.access(filePath, fsConstants.W_OK);
-        return true;
-      } catch {
-        return false;
-      }
-    } catch (error: any) {
-      if (error.code === 'ENOENT') {
-        // File doesn't exist - find first existing parent directory and check its permissions
-        const parentDir = path.dirname(filePath);
-        const existingDir = await this.findFirstExistingDirectory(parentDir);
-
-        if (existingDir === null) {
-          // No existing parent directory found (edge case)
-          return false;
-        }
-
-        // Check if the existing parent directory is writable
-        try {
-          await fs.access(existingDir, fsConstants.W_OK);
-          return true;
-        } catch {
-          return false;
-        }
-      }
-
-      console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
-      return false;
-    }
-  }
-
-  static async directoryExists(dirPath: string): Promise<boolean> {
-    try {
-      const stats = await fs.stat(dirPath);
-      return stats.isDirectory();
-    } catch (error: any) {
-      if (error.code !== 'ENOENT') {
-        console.debug(`Unable to check if directory exists at ${dirPath}: ${error.message}`);
-      }
-      return false;
-    }
-  }
-
-  static async writeFile(filePath: string, content: string): Promise<void> {
-    const dir = path.dirname(filePath);
-    await this.createDirectory(dir);
-    await fs.writeFile(filePath, content, 'utf-8');
-  }
-
-  static async readFile(filePath: string): Promise<string> {
-    return await fs.readFile(filePath, 'utf-8');
-  }
-
-  static async updateFileWithMarkers(
-    filePath: string,
-    content: string,
-    startMarker: string,
-    endMarker: string
-  ): Promise<void> {
-    let existingContent = '';
-    
-    if (await this.fileExists(filePath)) {
-      existingContent = await this.readFile(filePath);
-      
-      const startIndex = findMarkerIndex(existingContent, startMarker);
-      const endIndex = startIndex !== -1
-        ? findMarkerIndex(existingContent, endMarker, startIndex + startMarker.length)
-        : findMarkerIndex(existingContent, endMarker);
-
-      if (startIndex !== -1 && endIndex !== -1) {
-        if (endIndex < startIndex) {
-          throw new Error(
-            `Invalid marker state in ${filePath}. End marker appears before start marker.`
-          );
-        }
-
-        const before = existingContent.substring(0, startIndex);
-        const after = existingContent.substring(endIndex + endMarker.length);
-        existingContent = before + startMarker + '\n' + content + '\n' + endMarker + after;
-      } else if (startIndex === -1 && endIndex === -1) {
-        existingContent = startMarker + '\n' + content + '\n' + endMarker + '\n\n' + existingContent;
-      } else {
-        throw new Error(`Invalid marker state in ${filePath}. Found start: ${startIndex !== -1}, Found end: ${endIndex !== -1}`);
-      }
-    } else {
-      existingContent = startMarker + '\n' + content + '\n' + endMarker;
-    }
-    
-    await this.writeFile(filePath, existingContent);
-  }
-
-  static async ensureWritePermissions(dirPath: string): Promise<boolean> {
-    try {
-      // If directory doesn't exist, check parent directory permissions
-      if (!await this.directoryExists(dirPath)) {
-        const parentDir = path.dirname(dirPath);
-        if (!await this.directoryExists(parentDir)) {
-          await this.createDirectory(parentDir);
-        }
-        return await this.ensureWritePermissions(parentDir);
-      }
-      
-      const testFile = path.join(dirPath, '.prompter-test-' + Date.now());
-      await fs.writeFile(testFile, '');
-      await fs.unlink(testFile);
-      return true;
-    } catch (error: any) {
-      console.debug(`Insufficient permissions to write to ${dirPath}: ${error.message}`);
-      return false;
-    }
-  }
-}

package/src/utils/index.ts

@@ -1,12 +0,0 @@
-// Shared utilities
-export { validateChangeName, createChange } from './change-utils.js';
-export type { ValidationResult, CreateChangeOptions } from './change-utils.js';
-
-// Change metadata utilities
-export {
-  readChangeMetadata,
-  writeChangeMetadata,
-  resolveSchemaForChange,
-  validateSchemaName,
-  ChangeMetadataError,
-} from './change-metadata.js';

package/src/utils/interactive.ts

@@ -1,29 +0,0 @@
-export type InteractiveOptions = {
-  /**
-   * Explicit "disable prompts" flag passed by internal callers.
-   */
-  noInteractive?: boolean;
-  /**
-   * Commander-style negated option: `--no-interactive` sets this to false.
-   */
-  interactive?: boolean;
-};
-
-/**
- * Resolves whether non-interactive mode is requested.
- * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
- * Use this helper instead of manually checking options.noInteractive to avoid bugs.
- */
-export function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean {
-  if (typeof value === 'boolean') return value;
-  return value?.noInteractive === true || value?.interactive === false;
-}
-
-export function isInteractive(value?: boolean | InteractiveOptions): boolean {
-  if (resolveNoInteractive(value)) return false;
-  if (process.env.OPEN_SPEC_INTERACTIVE === '0') return false;
-  // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
-  if ('CI' in process.env) return false;
-  return !!process.stdin.isTTY;
-}
-

package/src/utils/item-discovery.ts

@@ -1,66 +0,0 @@
-import { promises as fs } from 'fs';
-import path from 'path';
-
-export async function getActiveChangeIds(root: string = process.cwd()): Promise<string[]> {
-  const changesPath = path.join(root, 'prompter', 'changes');
-  try {
-    const entries = await fs.readdir(changesPath, { withFileTypes: true });
-    const result: string[] = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive') continue;
-      const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
-      try {
-        await fs.access(proposalPath);
-        result.push(entry.name);
-      } catch {
-        // skip directories without proposal.md
-      }
-    }
-    return result.sort();
-  } catch {
-    return [];
-  }
-}
-
-export async function getSpecIds(root: string = process.cwd()): Promise<string[]> {
-  const specsPath = path.join(root, 'prompter', 'specs');
-  const result: string[] = [];
-  try {
-    const entries = await fs.readdir(specsPath, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-      const specFile = path.join(specsPath, entry.name, 'spec.md');
-      try {
-        await fs.access(specFile);
-        result.push(entry.name);
-      } catch {
-        // ignore
-      }
-    }
-  } catch {
-    // ignore
-  }
-  return result.sort();
-}
-
-export async function getArchivedChangeIds(root: string = process.cwd()): Promise<string[]> {
-  const archivePath = path.join(root, 'prompter', 'changes', 'archive');
-  try {
-    const entries = await fs.readdir(archivePath, { withFileTypes: true });
-    const result: string[] = [];
-    for (const entry of entries) {
-      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
-      const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
-      try {
-        await fs.access(proposalPath);
-        result.push(entry.name);
-      } catch {
-        // skip directories without proposal.md
-      }
-    }
-    return result.sort();
-  } catch {
-    return [];
-  }
-}
-

package/src/utils/match.ts

@@ -1,26 +0,0 @@
-export function nearestMatches(input: string, candidates: string[], max: number = 5): string[] {
-  const scored = candidates.map(candidate => ({ candidate, distance: levenshtein(input, candidate) }));
-  scored.sort((a, b) => a.distance - b.distance);
-  return scored.slice(0, max).map(s => s.candidate);
-}
-
-export function levenshtein(a: string, b: string): number {
-  const m = a.length;
-  const n = b.length;
-  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
-  for (let i = 0; i <= m; i++) dp[i][0] = i;
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      dp[i][j] = Math.min(
-        dp[i - 1][j] + 1,
-        dp[i][j - 1] + 1,
-        dp[i - 1][j - 1] + cost
-      );
-    }
-  }
-  return dp[m][n];
-}
-
-