@specmarket/cli 0.0.4 → 0.0.6

package/src/commands/validate.ts

@@ -1,189 +1,61 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { readFile, readdir, access, stat } from 'fs/promises';
+import { readFile, readdir, access } from 'fs/promises';
 import { join, resolve, relative, normalize } from 'path';
 import { parse as parseYaml } from 'yaml';
 import {
   specYamlSchema,
+  specmarketSidecarSchema,
   EXIT_CODES,
   REQUIRED_SPEC_FILES,
   REQUIRED_STDLIB_FILES,
+  SIDECAR_FILENAME,
 } from '@specmarket/shared';
 import type { ValidationResult } from '@specmarket/shared';
+import {
+  fileExists,
+  directoryExists,
+  hasStoryFiles,
+  hasMarkdownFiles,
+} from '../lib/format-detection.js';
 
 /**
- * Validates a spec directory for completeness and schema compliance.
- *
- * Checks (errors):
- * - spec.yaml parses and conforms to Zod schema
- * - Required files exist and are non-empty: PROMPT.md, SPEC.md, SUCCESS_CRITERIA.md
- * - stdlib/ directory with STACK.md
- * - SUCCESS_CRITERIA.md has at least one criterion
- * - No circular references between spec files (Markdown link cycles)
- * - Infrastructure block validates (if present)
- *
- * Checks (warnings):
- * - Web-app/api-service/mobile-app with no infrastructure services
- * - Missing setup_time_minutes
- * - Token/cost/time estimates seem unreasonably low or high
- *
- * Exported as a testable function separate from the CLI command wrapper.
+ * Recursively collects file paths relative to baseDir, filtered by extension.
  */
-export async function validateSpec(specPath: string): Promise<ValidationResult> {
-  const dir = resolve(specPath);
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  // Check required files exist and are non-empty
-  for (const file of REQUIRED_SPEC_FILES) {
-    const filePath = join(dir, file);
-    try {
-      await access(filePath);
-      const content = await readFile(filePath, 'utf-8');
-      if (content.trim().length === 0) {
-        errors.push(`${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: ${file}`);
-    }
-  }
-
-  // Check stdlib directory
-  const stdlibDir = join(dir, 'stdlib');
-  for (const file of REQUIRED_STDLIB_FILES) {
-    const filePath = join(stdlibDir, file);
-    try {
-      await access(filePath);
-      const content = await readFile(filePath, 'utf-8');
-      if (content.trim().length === 0) {
-        errors.push(`stdlib/${file} exists but is empty`);
-      }
-    } catch {
-      errors.push(`Required file missing: stdlib/${file}`);
-    }
-  }
-
-  // Parse and validate spec.yaml
-  let specYaml: unknown = null;
-  const specYamlPath = join(dir, 'spec.yaml');
+async function collectFiles(
+  currentDir: string,
+  baseDir: string,
+  extensions: Set<string>
+): Promise<string[]> {
+  const results: string[] = [];
   try {
-    const raw = await readFile(specYamlPath, 'utf-8');
-    specYaml = parseYaml(raw);
-  } catch (err) {
-    errors.push(`spec.yaml: Failed to parse YAML: ${(err as Error).message}`);
-    return { valid: false, errors, warnings };
-  }
-
-  const parseResult = specYamlSchema.safeParse(specYaml);
-  if (!parseResult.success) {
-    for (const issue of parseResult.error.issues) {
-      errors.push(
-        `spec.yaml: ${issue.path.join('.')} — ${issue.message}`
-      );
-    }
-  } else {
-    const parsed = parseResult.data;
-
-    // Check SUCCESS_CRITERIA.md has at least one criterion
-    try {
-      const criteriaContent = await readFile(join(dir, 'SUCCESS_CRITERIA.md'), 'utf-8');
-      const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
-      if (!hasCriterion) {
-        errors.push(
-          'SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text'
-        );
-      }
-    } catch {
-      // Already caught in required files check
-    }
-
-    // Check for circular references between spec files
-    const cycles = await detectCircularReferences(dir);
-    for (const cycle of cycles) {
-      errors.push(`Circular reference detected: ${cycle}`);
-    }
-
-    // Infrastructure validation warnings
-    if (parsed.infrastructure) {
-      const infra = parsed.infrastructure;
-
-      // Warn if web/api/mobile apps have no services
-      if (
-        ['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type) &&
-        infra.services.length === 0
-      ) {
-        warnings.push(
-          `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
-        );
-      }
-
-      if (!infra.setup_time_minutes) {
-        warnings.push('infrastructure.setup_time_minutes is not set');
-      }
-
-      // Validate defaultProvider matches a defined provider name
-      for (const service of infra.services) {
-        if (service.default_provider) {
-          const providerNames = service.providers.map((p) => p.name);
-          if (!providerNames.includes(service.default_provider)) {
-            errors.push(
-              `infrastructure.services[${service.name}].default_provider "${service.default_provider}" ` +
-              `does not match any defined provider (${providerNames.join(', ')})`
-            );
-          }
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+        const subFiles = await collectFiles(fullPath, baseDir, extensions);
+        results.push(...subFiles);
+      } else if (entry.isFile()) {
+        const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop()! : '';
+        if (extensions.has(ext)) {
+          results.push(relative(baseDir, fullPath));
         }
       }
-    } else {
-      if (['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type)) {
-        warnings.push(
-          'No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc.'
-        );
-      }
-    }
-
-    // Estimate sanity checks
-    if (parsed.estimated_tokens < 1000) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
-      );
-    }
-    if (parsed.estimated_tokens > 10_000_000) {
-      warnings.push(
-        `estimated_tokens (${parsed.estimated_tokens}) seems very high.`
-      );
-    }
-    if (parsed.estimated_cost_usd < 0.01) {
-      warnings.push(
-        `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
-      );
-    }
-    if (parsed.estimated_time_minutes < 1) {
-      warnings.push(
-        `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
-      );
     }
+  } catch {
+    // Directory unreadable
   }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings,
-  };
+  return results;
 }
 
 /**
  * Scans all Markdown/YAML files in the spec directory for relative file
  * references (Markdown links) and detects cycles in the reference graph.
- *
- * Returns an array of cycle descriptions (empty if no cycles found).
- * Uses DFS with coloring (white/gray/black) for cycle detection.
  */
 export async function detectCircularReferences(dir: string): Promise<string[]> {
-  // Collect all text files in the spec directory (md, yaml, yml)
   const textExtensions = new Set(['.md', '.yaml', '.yml']);
   const files = await collectFiles(dir, dir, textExtensions);
-
-  // Build adjacency list: file -> files it references via Markdown links
   const graph = new Map<string, Set<string>>();
   const linkPattern = /\[(?:[^\]]*)\]\(([^)]+)\)/g;
 
@@ -194,32 +66,31 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
       let match: RegExpExecArray | null;
       while ((match = linkPattern.exec(content)) !== null) {
         const target = match[1]!;
-        // Skip external URLs, anchors, and mailto
-        if (target.startsWith('http://') || target.startsWith('https://') ||
-            target.startsWith('#') || target.startsWith('mailto:')) {
+        if (
+          target.startsWith('http://') ||
+          target.startsWith('https://') ||
+          target.startsWith('#') ||
+          target.startsWith('mailto:')
+        ) {
           continue;
         }
-        // Strip anchor fragments (e.g., "./SPEC.md#section" -> "./SPEC.md")
         const targetPath = target.split('#')[0]!;
         if (!targetPath) continue;
-
-        // Resolve relative to the file's directory
         const fileDir = join(dir, file, '..');
         const resolvedTarget = normalize(relative(dir, resolve(fileDir, targetPath)));
-
-        // Only track references to files within the spec directory
         if (!resolvedTarget.startsWith('..') && files.includes(resolvedTarget)) {
           refs.add(resolvedTarget);
         }
       }
     } catch {
-      // File unreadable — skip
+      // skip
     }
     graph.set(file, refs);
   }
 
-  // DFS cycle detection
-  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const WHITE = 0,
+    GRAY = 1,
+    BLACK = 2;
   const color = new Map<string, number>();
   const parent = new Map<string, string | null>();
   const cycles: string[] = [];
@@ -233,7 +104,6 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
     const neighbors = graph.get(node) ?? new Set();
     for (const neighbor of neighbors) {
       if (color.get(neighbor) === GRAY) {
-        // Found a cycle — reconstruct the path
         const cyclePath: string[] = [neighbor, node];
         let curr = node;
         while (curr !== neighbor) {
@@ -263,44 +133,297 @@ export async function detectCircularReferences(dir: string): Promise<string[]> {
 }
 
 /**
- * Recursively collects file paths relative to baseDir, filtered by extension.
+ * Content validation when spec_format is "specmarket" (spec.yaml + PROMPT.md + SPEC.md + SUCCESS_CRITERIA.md + stdlib).
+ * Pushes to errors/warnings.
  */
-async function collectFiles(
-  currentDir: string,
-  baseDir: string,
-  extensions: Set<string>
-): Promise<string[]> {
-  const results: string[] = [];
+async function validateSpecmarketContent(
+  dir: string,
+  errors: string[],
+  warnings: string[]
+): Promise<void> {
+  for (const file of REQUIRED_SPEC_FILES) {
+    const filePath = join(dir, file);
+    try {
+      await access(filePath);
+      const content = await readFile(filePath, 'utf-8');
+      if (content.trim().length === 0) {
+        errors.push(`${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: ${file}`);
+    }
+  }
+
+  const stdlibDir = join(dir, 'stdlib');
+  for (const file of REQUIRED_STDLIB_FILES) {
+    const filePath = join(stdlibDir, file);
+    try {
+      await access(filePath);
+      const content = await readFile(filePath, 'utf-8');
+      if (content.trim().length === 0) {
+        errors.push(`stdlib/${file} exists but is empty`);
+      }
+    } catch {
+      errors.push(`Required file missing: stdlib/${file}`);
+    }
+  }
+
+  let specYaml: unknown = null;
+  const specYamlPath = join(dir, 'spec.yaml');
   try {
-    const entries = await readdir(currentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join(currentDir, entry.name);
-      if (entry.isDirectory()) {
-        // Skip hidden directories and node_modules
-        if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-        const subFiles = await collectFiles(fullPath, baseDir, extensions);
-        results.push(...subFiles);
-      } else if (entry.isFile()) {
-        const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop() : '';
-        if (extensions.has(ext)) {
-          results.push(relative(baseDir, fullPath));
+    const raw = await readFile(specYamlPath, 'utf-8');
+    specYaml = parseYaml(raw);
+  } catch (err) {
+    errors.push(`spec.yaml: Failed to parse YAML: ${(err as Error).message}`);
+    return;
+  }
+
+  const parseResult = specYamlSchema.safeParse(specYaml);
+  if (!parseResult.success) {
+    for (const issue of parseResult.error.issues) {
+      errors.push(`spec.yaml: ${issue.path.join('.')} — ${issue.message}`);
+    }
+    return;
+  }
+
+  const parsed = parseResult.data;
+
+  try {
+    const criteriaContent = await readFile(join(dir, 'SUCCESS_CRITERIA.md'), 'utf-8');
+    const hasCriterion = /^- \[[ x]\]/m.test(criteriaContent);
+    if (!hasCriterion) {
+      errors.push(
+        'SUCCESS_CRITERIA.md: Must contain at least one criterion in format: - [ ] criterion text'
+      );
+    }
+  } catch {
+    // Already caught in required files check
+  }
+
+  const cycles = await detectCircularReferences(dir);
+  for (const cycle of cycles) {
+    errors.push(`Circular reference detected: ${cycle}`);
+  }
+
+  if (parsed.infrastructure) {
+    const infra = parsed.infrastructure;
+    if (
+      ['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type) &&
+      infra.services.length === 0
+    ) {
+      warnings.push(
+        `${parsed.output_type} should typically define infrastructure services (database, auth, etc.)`
+      );
+    }
+    if (!infra.setup_time_minutes) {
+      warnings.push('infrastructure.setup_time_minutes is not set');
+    }
+    for (const service of infra.services) {
+      if (service.default_provider) {
+        const providerNames = service.providers.map((p) => p.name);
+        if (!providerNames.includes(service.default_provider)) {
+          errors.push(
+            `infrastructure.services[${service.name}].default_provider "${service.default_provider}" ` +
+              `does not match any defined provider (${providerNames.join(', ')})`
+          );
         }
       }
     }
+  } else {
+    if (['web-app', 'api-service', 'mobile-app'].includes(parsed.output_type)) {
+      warnings.push(
+        'No infrastructure block defined. Consider adding infrastructure.services for database, auth, etc.'
+      );
+    }
+  }
+
+  if (parsed.estimated_tokens < 1000) {
+    warnings.push(
+      `estimated_tokens (${parsed.estimated_tokens}) seems very low. Most specs use 10,000+.`
+    );
+  }
+  if (parsed.estimated_tokens > 10_000_000) {
+    warnings.push(`estimated_tokens (${parsed.estimated_tokens}) seems very high.`);
+  }
+  if (parsed.estimated_cost_usd < 0.01) {
+    warnings.push(
+      `estimated_cost_usd ($${parsed.estimated_cost_usd}) seems very low.`
+    );
+  }
+  if (parsed.estimated_time_minutes < 1) {
+    warnings.push(
+      `estimated_time_minutes (${parsed.estimated_time_minutes}) seems unrealistically low.`
+    );
+  }
+}
+
+/**
+ * Validates a spec directory. Single standard: specmarket.yaml is required for every spec.
+ * Format and metadata come from the sidecar; format-specific content checks run based on spec_format.
+ */
+export async function validateSpec(specPath: string): Promise<ValidationResult> {
+  const dir = resolve(specPath);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  let format: string | undefined;
+  let formatDetectedBy: 'sidecar' | 'heuristic' | undefined = 'sidecar';
+
+  // Universal: directory non-empty
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const hasAnyFile = entries.some((e) => e.isFile());
+    if (!hasAnyFile) {
+      errors.push('Directory is empty or has no readable files');
+    }
   } catch {
-    // Directory unreadable
+    errors.push('Directory is empty or unreadable');
   }
-  return results;
+
+  const sidecarPath = join(dir, SIDECAR_FILENAME);
+  const sidecarExists = await fileExists(sidecarPath);
+
+  if (!sidecarExists) {
+    errors.push(`${SIDECAR_FILENAME} is required for all specs (single source of truth for format and metadata)`);
+  } else {
+    try {
+      const raw = await readFile(sidecarPath, 'utf-8');
+      const parsed = parseYaml(raw) as unknown;
+      const sidecarResult = specmarketSidecarSchema.safeParse(parsed);
+      if (!sidecarResult.success) {
+        for (const issue of sidecarResult.error.issues) {
+          errors.push(
+            `${SIDECAR_FILENAME}: ${issue.path.join('.')} — ${issue.message}`
+          );
+        }
+      } else {
+        const sidecar = sidecarResult.data;
+        format = sidecar.spec_format;
+
+        if (sidecar.estimated_tokens !== undefined) {
+          if (sidecar.estimated_tokens < 1000) {
+            warnings.push(
+              `estimated_tokens (${sidecar.estimated_tokens}) seems very low.`
+            );
+          }
+          if (sidecar.estimated_tokens > 10_000_000) {
+            warnings.push(`estimated_tokens (${sidecar.estimated_tokens}) seems very high.`);
+          }
+        }
+        if (sidecar.estimated_cost_usd !== undefined && sidecar.estimated_cost_usd < 0.01) {
+          warnings.push(
+            `estimated_cost_usd ($${sidecar.estimated_cost_usd}) seems very low.`
+          );
+        }
+        if (
+          sidecar.estimated_time_minutes !== undefined &&
+          sidecar.estimated_time_minutes < 1
+        ) {
+          warnings.push(
+            `estimated_time_minutes (${sidecar.estimated_time_minutes}) seems unrealistically low.`
+          );
+        }
+
+        // Format-specific content validation (based on sidecar.spec_format)
+        switch (format) {
+          case 'specmarket':
+            await validateSpecmarketContent(dir, errors, warnings);
+            break;
+          case 'speckit': {
+            const hasSpecMd = await fileExists(join(dir, 'spec.md'));
+            const hasTasksMd = await fileExists(join(dir, 'tasks.md'));
+            const hasPlanMd = await fileExists(join(dir, 'plan.md'));
+            const hasSpecifyDir = await directoryExists(join(dir, '.specify'));
+            if (!hasSpecMd) errors.push('speckit format requires spec.md');
+            if (!hasTasksMd && !hasPlanMd) errors.push('speckit format requires tasks.md or plan.md');
+            if (!hasSpecifyDir) warnings.push('speckit format: .specify/ directory is recommended');
+            break;
+          }
+          case 'bmad': {
+            const hasPrdMd = await fileExists(join(dir, 'prd.md'));
+            const hasStory = await hasStoryFiles(dir);
+            if (!hasPrdMd && !hasStory) errors.push('bmad format requires prd.md or story-*.md files');
+            const hasArch = await fileExists(join(dir, 'architecture.md'));
+            if (!hasArch) warnings.push('bmad format: architecture.md is recommended');
+            break;
+          }
+          case 'ralph': {
+            const prdPath = join(dir, 'prd.json');
+            if (!(await fileExists(prdPath))) {
+              errors.push('ralph format requires prd.json');
+              break;
+            }
+            try {
+              const raw = await readFile(prdPath, 'utf-8');
+              const data = JSON.parse(raw) as unknown;
+              if (
+                !data ||
+                typeof data !== 'object' ||
+                !('userStories' in data) ||
+                !Array.isArray((data as { userStories: unknown }).userStories)
+              ) {
+                errors.push('ralph format: prd.json must have userStories array');
+              }
+            } catch {
+              errors.push('ralph format: prd.json must be valid JSON with userStories array');
+            }
+            break;
+          }
+          case 'custom':
+          default: {
+            const hasMd = await hasMarkdownFiles(dir);
+            if (!hasMd) {
+              errors.push('custom format requires at least one .md file');
+              break;
+            }
+            const textExtensions = new Set(['.md']);
+            const mdFiles = await collectFiles(dir, dir, textExtensions);
+            let hasSubstantialMd = false;
+            for (const f of mdFiles) {
+              try {
+                const content = await readFile(join(dir, f), 'utf-8');
+                if (content.length > 100) {
+                  hasSubstantialMd = true;
+                  break;
+                }
+              } catch {
+                // skip
+              }
+            }
+            if (!hasSubstantialMd) {
+              errors.push('custom format requires at least one .md file larger than 100 bytes');
+            }
+            break;
+          }
+        }
+      }
+    } catch (err) {
+      errors.push(
+        `${SIDECAR_FILENAME}: Failed to read or parse: ${(err as Error).message}`
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    format,
+    formatDetectedBy,
+  };
 }
 
 export function createValidateCommand(): Command {
   return new Command('validate')
     .description('Validate a spec directory for completeness and schema compliance')
-    .argument('<path>', 'Path to the spec directory')
+    .argument('[path]', 'Path to the spec directory (defaults to current directory)', '.')
     .action(async (specPath: string) => {
       try {
         const result = await validateSpec(specPath);
 
+        if (result.format !== undefined) {
+          console.log(chalk.gray(`Format: ${result.format}`));
+        }
+
         if (result.warnings.length > 0) {
           console.log(chalk.yellow('\nWarnings:'));
           for (const warning of result.warnings) {

package/src/commands/whoami.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// --- Hoisted mocks ---
+
+const { mockQuery, mockClient, mockLoadCreds } = vi.hoisted(() => {
+  const mockQuery = vi.fn();
+  const mockClient = { query: mockQuery };
+  const mockLoadCreds = vi.fn();
+  return { mockQuery, mockClient, mockLoadCreds };
+});
+
+vi.mock('../lib/convex-client.js', () => ({
+  getConvexClient: vi.fn().mockResolvedValue(mockClient),
+}));
+
+vi.mock('../lib/auth.js', () => ({
+  loadCredentials: mockLoadCreds,
+}));
+
+vi.mock('@specmarket/convex/api', () => ({
+  api: {
+    users: { getMe: 'users.getMe' },
+  },
+}));
+
+const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+import { handleWhoami } from './whoami.js';
+
+describe('handleWhoami', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('shows not-logged-in message when no credentials exist', async () => {
+    mockLoadCreds.mockResolvedValue(null);
+
+    await handleWhoami();
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Not logged in')
+    );
+  });
+
+  it('displays full profile from Convex when available', async () => {
+    mockLoadCreds.mockResolvedValue({
+      token: 'test-token',
+      username: 'alice',
+      expiresAt: Date.now() + 30 * 24 * 3600_000,
+    });
+    mockQuery.mockResolvedValue({
+      username: 'alice',
+      displayName: 'Alice Smith',
+      role: 'user',
+      totalSpecsPublished: 5,
+      reputationScore: 120,
+    });
+
+    await handleWhoami();
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Authenticated as')
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('@alice')
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Alice Smith')
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('120')
+    );
+  });
+
+  it('falls back to cached credentials when Convex is unreachable', async () => {
+    mockLoadCreds.mockResolvedValue({
+      token: 'test-token',
+      username: 'bob',
+      expiresAt: Date.now() + 30 * 24 * 3600_000,
+    });
+    mockQuery.mockRejectedValue(new Error('Network error'));
+
+    await handleWhoami();
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Authenticated (cached)')
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('@bob')
+    );
+  });
+
+  it('shows "unknown" when cached credentials have no username', async () => {
+    mockLoadCreds.mockResolvedValue({
+      token: 'test-token',
+      expiresAt: Date.now() + 3600_000,
+    });
+    mockQuery.mockRejectedValue(new Error('Network error'));
+
+    await handleWhoami();
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('@unknown')
+    );
+  });
+});