@kjerneverk/riotplan-catalyst 1.0.0-dev.0

package/src/loader/plan-manifest.ts

@@ -0,0 +1,228 @@
+/**
+ * Plan manifest read/write
+ * @packageDocumentation
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { PlanManifestSchema, type PlanManifestOutput } from '@/schema/schemas';
+
+/**
+ * Plan manifest stored in plan.yaml
+ * 
+ * This is the metadata file for a plan that records:
+ * - The plan's identity (ID and title)
+ * - Which catalysts are associated with the plan
+ * - When the plan was created
+ * - Arbitrary metadata for extensibility
+ */
+export interface PlanManifest extends PlanManifestOutput {}
+
+const MANIFEST_FILENAME = 'plan.yaml';
+
+/**
+ * Read a plan manifest from plan.yaml
+ * 
+ * Returns null if the manifest file doesn't exist (graceful handling
+ * for backward compatibility with plans created before catalyst support).
+ * Throws if the file exists but contains invalid data.
+ * 
+ * @param planDirectory - Absolute path to plan directory
+ * @returns Parsed and validated manifest, or null if not present
+ * @throws Error if manifest exists but is invalid
+ * 
+ * @example
+ * ```typescript
+ * const manifest = await readPlanManifest('./my-plan');
+ * if (manifest) {
+ *   console.log(`Plan: ${manifest.title}`);
+ *   console.log(`Uses catalysts: ${manifest.catalysts?.join(', ')}`);
+ * }
+ * ```
+ */
+export async function readPlanManifest(planDirectory: string): Promise<PlanManifest | null> {
+  const manifestPath = join(planDirectory, MANIFEST_FILENAME);
+  
+  try {
+    const content = await readFile(manifestPath, 'utf-8');
+    const parsed = parseYaml(content);
+    
+    // Validate with Zod schema
+    const result = PlanManifestSchema.safeParse(parsed);
+    
+    if (!result.success) {
+      const errors = result.error.issues.map(issue => 
+        `${issue.path.join('.')}: ${issue.message}`
+      ).join('; ');
+      throw new Error(`Invalid plan manifest: ${errors}`);
+    }
+    
+    return result.data;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      // File doesn't exist - return null for backward compatibility
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Write a plan manifest to plan.yaml
+ * 
+ * Creates or overwrites the plan.yaml file with the provided manifest.
+ * Automatically timestamps the manifest if `created` is not provided.
+ * 
+ * @param planDirectory - Absolute path to plan directory
+ * @param manifest - Manifest to write
+ * @throws Error if manifest is invalid or write fails
+ * 
+ * @example
+ * ```typescript
+ * const manifest: PlanManifest = {
+ *   id: 'add-user-auth',
+ *   title: 'Add User Authentication',
+ *   catalysts: ['@kjerneverk/catalyst-nodejs'],
+ *   created: new Date().toISOString(),
+ * };
+ * await writePlanManifest('./my-plan', manifest);
+ * ```
+ */
+export async function writePlanManifest(
+  planDirectory: string,
+  manifest: PlanManifest
+): Promise<void> {
+  // Validate manifest
+  const result = PlanManifestSchema.safeParse(manifest);
+  
+  if (!result.success) {
+    const errors = result.error.issues.map(issue => 
+      `${issue.path.join('.')}: ${issue.message}`
+    ).join('; ');
+    throw new Error(`Invalid plan manifest: ${errors}`);
+  }
+  
+  // Ensure created timestamp exists
+  const manifestToWrite: PlanManifest = {
+    ...result.data,
+    created: result.data.created || new Date().toISOString(),
+  };
+  
+  // Serialize to YAML
+  const yaml = stringifyYaml(manifestToWrite, {
+    indent: 2,
+    lineWidth: 120,
+  });
+  
+  // Write to file
+  const manifestPath = join(planDirectory, MANIFEST_FILENAME);
+  await writeFile(manifestPath, yaml, 'utf-8');
+}
+
+/**
+ * Update specific fields in a plan manifest
+ * 
+ * Reads the existing manifest (or creates a new one if it doesn't exist),
+ * merges the provided updates, and writes it back.
+ * 
+ * @param planDirectory - Absolute path to plan directory
+ * @param updates - Partial manifest to merge (only specified fields are changed)
+ * @throws Error if updates are invalid or operation fails
+ * 
+ * @example
+ * ```typescript
+ * // Add a catalyst to an existing plan
+ * await updatePlanManifest('./my-plan', {
+ *   catalysts: ['@kjerneverk/catalyst-nodejs', '@kjerneverk/catalyst-react'],
+ * });
+ * ```
+ */
+export async function updatePlanManifest(
+  planDirectory: string,
+  updates: Partial<PlanManifest>
+): Promise<void> {
+  // Read existing manifest
+  let existing = await readPlanManifest(planDirectory);
+  
+  // If no existing manifest, start with a minimal one
+  if (!existing) {
+    // Updates must contain at least id and title
+    if (!updates.id || !updates.title) {
+      throw new Error('Cannot create manifest without id and title');
+    }
+    existing = {
+      id: '',
+      title: '',
+    };
+  }
+  
+  // Merge updates
+  const merged: PlanManifest = {
+    ...existing,
+    ...updates,
+  };
+  
+  // Write back
+  await writePlanManifest(planDirectory, merged);
+}
+
+/**
+ * Add a catalyst to a plan's manifest
+ * 
+ * Convenience function that adds a catalyst ID to the catalysts array
+ * without affecting other fields.
+ * 
+ * @param planDirectory - Absolute path to plan directory
+ * @param catalystId - Catalyst ID to add
+ * 
+ * @example
+ * ```typescript
+ * await addCatalystToManifest('./my-plan', '@kjerneverk/catalyst-nodejs');
+ * ```
+ */
+export async function addCatalystToManifest(
+  planDirectory: string,
+  catalystId: string
+): Promise<void> {
+  const manifest = await readPlanManifest(planDirectory);
+  const currentCatalysts = manifest?.catalysts ?? [];
+  
+  // Only add if not already present
+  if (!currentCatalysts.includes(catalystId)) {
+    currentCatalysts.push(catalystId);
+  }
+  
+  await updatePlanManifest(planDirectory, {
+    catalysts: currentCatalysts,
+  });
+}
+
+/**
+ * Remove a catalyst from a plan's manifest
+ * 
+ * Convenience function that removes a catalyst ID from the catalysts array.
+ * 
+ * @param planDirectory - Absolute path to plan directory
+ * @param catalystId - Catalyst ID to remove
+ * 
+ * @example
+ * ```typescript
+ * await removeCatalystFromManifest('./my-plan', '@kjerneverk/catalyst-old');
+ * ```
+ */
+export async function removeCatalystFromManifest(
+  planDirectory: string,
+  catalystId: string
+): Promise<void> {
+  const manifest = await readPlanManifest(planDirectory);
+  const currentCatalysts = manifest?.catalysts ?? [];
+  
+  const filtered = currentCatalysts.filter(id => id !== catalystId);
+  
+  if (filtered.length !== currentCatalysts.length) {
+    await updatePlanManifest(planDirectory, {
+      catalysts: filtered.length > 0 ? filtered : undefined,
+    });
+  }
+}

package/src/merger/facet-merger.ts

@@ -0,0 +1,225 @@
+/**
+ * Facet merging for multiple catalysts
+ * @packageDocumentation
+ */
+
+import type { Catalyst } from '@/types';
+import type { FacetType } from '@/schema/schemas';
+import { FACET_TYPES } from '@/schema/schemas';
+
+/**
+ * A single piece of content with source attribution
+ */
+export interface AttributedContent {
+  content: string;
+  sourceId: string;
+  filename?: string;
+}
+
+/**
+ * Facets merged from multiple catalysts with source attribution
+ */
+export interface MergedFacets {
+  questions?: AttributedContent[];
+  constraints?: AttributedContent[];
+  outputTemplates?: AttributedContent[];
+  domainKnowledge?: AttributedContent[];
+  processGuidance?: AttributedContent[];
+  validationRules?: AttributedContent[];
+}
+
+/**
+ * Result of merging multiple catalysts
+ */
+export interface MergedCatalyst {
+  /** Ordered list of catalyst IDs that were merged */
+  catalystIds: string[];
+  /** Merged facets with source attribution */
+  facets: MergedFacets;
+  /** Metadata about each catalyst's contribution */
+  contributions: Map<string, {
+    facetTypes: FacetType[];
+    contentCount: number;
+  }>;
+}
+
+/**
+ * Merge multiple catalysts in order
+ * 
+ * Catalysts are merged in the order provided, with later catalysts
+ * layering on top of earlier ones. Content is concatenated (no conflict
+ * resolution in v1), and each piece of content retains its source catalyst ID.
+ * 
+ * @param catalysts - Ordered array of catalysts to merge (can be empty)
+ * @returns Merged catalyst with source attribution
+ * 
+ * @example
+ * ```typescript
+ * const catalyst1 = await loadCatalyst('./base-catalyst');
+ * const catalyst2 = await loadCatalyst('./nodejs-catalyst');
+ * const merged = mergeCatalysts([catalyst1, catalyst2]);
+ * ```
+ */
+export function mergeCatalysts(catalysts: Catalyst[]): MergedCatalyst {
+  const mergedFacets: MergedFacets = {};
+  const catalystIds = catalysts.map(c => c.manifest.id);
+  const contributions = new Map<string, {
+    facetTypes: FacetType[];
+    contentCount: number;
+  }>();
+
+  // Process each facet type
+  for (const facetType of FACET_TYPES) {
+    const mergedContent: AttributedContent[] = [];
+
+    // Iterate through catalysts in order
+    for (const catalyst of catalysts) {
+      const facetContent = catalyst.facets[facetType];
+      
+      if (facetContent && facetContent.length > 0) {
+        // Add each file's content with source attribution
+        for (const file of facetContent) {
+          mergedContent.push({
+            content: file.content,
+            sourceId: catalyst.manifest.id,
+            filename: file.filename,
+          });
+        }
+
+        // Track contribution
+        const contrib = contributions.get(catalyst.manifest.id) || {
+          facetTypes: [],
+          contentCount: 0,
+        };
+        if (!contrib.facetTypes.includes(facetType)) {
+          contrib.facetTypes.push(facetType);
+        }
+        contrib.contentCount += facetContent.length;
+        contributions.set(catalyst.manifest.id, contrib);
+      }
+    }
+
+    // Only set facet type if there's content
+    if (mergedContent.length > 0) {
+      mergedFacets[facetType] = mergedContent;
+    }
+  }
+
+  return {
+    catalystIds,
+    facets: mergedFacets,
+    contributions,
+  };
+}
+
+/**
+ * Format a facet type name for display
+ */
+function formatFacetName(facetType: FacetType): string {
+  const names: Record<FacetType, string> = {
+    questions: 'Questions',
+    constraints: 'Constraints',
+    outputTemplates: 'Output Templates',
+    domainKnowledge: 'Domain Knowledge',
+    processGuidance: 'Process Guidance',
+    validationRules: 'Validation Rules',
+  };
+  return names[facetType];
+}
+
+/**
+ * Render merged facet content into a prompt-ready string
+ * 
+ * Groups content by catalyst source and formats it for use in AI prompts.
+ * Each source is labeled and content is separated for readability.
+ * 
+ * @param merged - Merged catalyst
+ * @param facetType - Facet type to render
+ * @returns Formatted string ready for prompt injection, or empty string if no content
+ * 
+ * @example
+ * ```typescript
+ * const merged = mergeCatalysts([catalyst1, catalyst2]);
+ * const constraints = renderFacet(merged, 'constraints');
+ * // Returns:
+ * // From @kjerneverk/base-catalyst:
+ * // [content from first catalyst]
+ * // From @kjerneverk/nodejs-catalyst:
+ * // [content from second catalyst]
+ * ```
+ */
+export function renderFacet(
+  merged: MergedCatalyst, 
+  facetType: FacetType
+): string {
+  const content = merged.facets[facetType];
+  
+  if (!content || content.length === 0) {
+    return '';
+  }
+
+  const lines: string[] = [];
+  let currentSource = '';
+
+  for (const item of content) {
+    // Add source header when it changes
+    if (item.sourceId !== currentSource) {
+      if (lines.length > 0) {
+        lines.push(''); // Blank line between sources
+      }
+      lines.push(`From ${item.sourceId}:`);
+      currentSource = item.sourceId;
+    }
+
+    // Add content
+    lines.push(item.content);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render all facets from a merged catalyst
+ * 
+ * Returns an object with each facet type mapped to its rendered string.
+ * Empty strings for facets with no content.
+ * 
+ * @param merged - Merged catalyst
+ * @returns Object with all facets rendered
+ */
+export function renderAllFacets(merged: MergedCatalyst): Record<FacetType, string> {
+  const rendered: Partial<Record<FacetType, string>> = {};
+
+  for (const facetType of FACET_TYPES) {
+    rendered[facetType] = renderFacet(merged, facetType);
+  }
+
+  return rendered as Record<FacetType, string>;
+}
+
+/**
+ * Generate a summary of merged catalysts
+ * 
+ * Returns human-readable text about what was merged and what each
+ * catalyst contributed.
+ * 
+ * @param merged - Merged catalyst
+ * @returns Summary string
+ */
+export function summarizeMerge(merged: MergedCatalyst): string {
+  if (merged.catalystIds.length === 0) {
+    return 'No catalysts merged';
+  }
+
+  const lines: string[] = [];
+  lines.push(`Merged ${merged.catalystIds.length} catalyst(s):`);
+  lines.push('');
+
+  for (const [catalystId, contrib] of merged.contributions) {
+    lines.push(`- ${catalystId}:`);
+    lines.push(`  - Facets: ${contrib.facetTypes.map(t => formatFacetName(t)).join(', ')}`);
+    lines.push(`  - Content items: ${contrib.contentCount}`);
+  }
+
+  return lines.join('\n');
+}

package/src/riotplan-catalyst.ts

@@ -0,0 +1,59 @@
+/**
+ * @packageDocumentation
+ * Catalyst system for RiotPlan - composable, layerable guidance packages for plan creation
+ */
+
+// Type exports
+export type { 
+  Catalyst, 
+  CatalystManifest, 
+  CatalystFacets, 
+  FacetContent,
+  CatalystLoadResult,
+  CatalystLoadOptions,
+  FacetDirectoryMap,
+  PlanManifest,
+} from './types';
+
+// Schema exports
+export { 
+  CatalystManifestSchema, 
+  PlanManifestSchema,
+  FacetsDeclarationSchema,
+  FACET_DIRECTORIES,
+  FACET_TYPES,
+} from '@/schema/schemas';
+
+export type {
+  FacetType,
+  CatalystManifestInput,
+  CatalystManifestOutput,
+  PlanManifestInput,
+  PlanManifestOutput,
+  FacetsDeclaration,
+} from '@/schema/schemas';
+
+// Loader exports
+export { 
+  loadCatalyst, 
+  loadCatalystSafe,
+  resolveCatalysts,
+} from '@/loader/catalyst-loader';
+
+// Merger exports
+export { 
+  mergeCatalysts, 
+  renderFacet,
+  renderAllFacets,
+  summarizeMerge,
+} from '@/merger/facet-merger';
+export type { MergedCatalyst, AttributedContent, MergedFacets } from '@/merger/facet-merger';
+
+// Plan manifest exports
+export { 
+  readPlanManifest, 
+  writePlanManifest, 
+  updatePlanManifest,
+  addCatalystToManifest,
+  removeCatalystFromManifest,
+} from '@/loader/plan-manifest';

package/src/schema/schemas.ts

@@ -0,0 +1,143 @@
+/**
+ * Zod schemas for catalyst.yml and plan.yaml manifests
+ * @packageDocumentation
+ */
+
+import { z } from 'zod';
+
+/**
+ * Facet directory names as they appear on disk
+ */
+export const FACET_DIRECTORIES = {
+  questions: 'questions',
+  constraints: 'constraints',
+  outputTemplates: 'output-templates',
+  domainKnowledge: 'domain-knowledge',
+  processGuidance: 'process-guidance',
+  validationRules: 'validation-rules',
+} as const;
+
+/**
+ * All valid facet types
+ */
+export const FACET_TYPES = [
+  'questions',
+  'constraints',
+  'outputTemplates',
+  'domainKnowledge',
+  'processGuidance',
+  'validationRules',
+] as const;
+
+export type FacetType = typeof FACET_TYPES[number];
+
+/**
+ * Schema for the facets declaration in catalyst.yml
+ * Each facet can be declared as present (true) or explicitly absent (false)
+ */
+export const FacetsDeclarationSchema = z.object({
+  questions: z.boolean().optional().describe('Whether this catalyst provides guiding questions'),
+  constraints: z.boolean().optional().describe('Whether this catalyst provides constraints/rules'),
+  outputTemplates: z.boolean().optional().describe('Whether this catalyst provides output templates'),
+  domainKnowledge: z.boolean().optional().describe('Whether this catalyst provides domain knowledge'),
+  processGuidance: z.boolean().optional().describe('Whether this catalyst provides process guidance'),
+  validationRules: z.boolean().optional().describe('Whether this catalyst provides validation rules'),
+});
+
+/**
+ * Semver pattern for version validation
+ * Matches: 1.0.0, 1.0.0-dev.0, 1.0.0-alpha.1, etc.
+ */
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+
+/**
+ * NPM package name pattern
+ * Matches: @scope/name, name, @scope/name-with-dashes
+ */
+const NPM_PACKAGE_PATTERN = /^(@[\w-]+\/)?[\w-]+$/;
+
+/**
+ * Schema for catalyst.yml manifest file
+ * 
+ * The manifest defines the catalyst's identity and declares which facets it provides.
+ * Facets are optional - a catalyst can provide any subset of the six facet types.
+ */
+export const CatalystManifestSchema = z.object({
+  /** 
+   * Catalyst identifier - should match NPM package name
+   * @example "@kjerneverk/catalyst-nodejs"
+   */
+  id: z.string()
+    .regex(NPM_PACKAGE_PATTERN, 'ID must be a valid NPM package name (e.g., @scope/name or name)')
+    .describe('Catalyst identifier (NPM package name)'),
+  
+  /** Human-readable name for display */
+  name: z.string()
+    .min(1, 'Name cannot be empty')
+    .describe('Human-readable name'),
+  
+  /** Description of what this catalyst provides */
+  description: z.string()
+    .min(1, 'Description cannot be empty')
+    .describe('What this catalyst provides'),
+  
+  /** 
+   * Semver version string
+   * @example "1.0.0" or "1.0.0-dev.0"
+   */
+  version: z.string()
+    .regex(SEMVER_PATTERN, 'Version must be valid semver (e.g., 1.0.0 or 1.0.0-dev.0)')
+    .describe('Semver version'),
+  
+  /** 
+   * Declaration of which facets this catalyst provides
+   * If omitted, facets are auto-detected from directory structure
+   */
+  facets: FacetsDeclarationSchema.optional()
+    .describe('Declaration of which facets this catalyst provides'),
+});
+
+/**
+ * Schema for plan.yaml manifest file
+ * 
+ * The plan manifest gives each plan an identity and records which catalysts
+ * are associated with it.
+ */
+export const PlanManifestSchema = z.object({
+  /** Plan identifier (typically kebab-case) */
+  id: z.string()
+    .min(1, 'ID cannot be empty')
+    .describe('Plan identifier'),
+  
+  /** Human-readable title */
+  title: z.string()
+    .min(1, 'Title cannot be empty')
+    .describe('Human-readable title'),
+  
+  /** 
+   * Ordered list of catalyst IDs associated with this plan
+   * Catalysts are applied in order (first = base, last = top layer)
+   */
+  catalysts: z.array(z.string())
+    .optional()
+    .describe('Ordered list of catalyst IDs'),
+  
+  /** ISO timestamp of when the plan was created */
+  created: z.string()
+    .optional()
+    .describe('ISO timestamp of creation'),
+  
+  /** Extensible metadata for future use */
+  metadata: z.record(z.string())
+    .optional()
+    .describe('Extensible metadata'),
+});
+
+/**
+ * Inferred TypeScript types from Zod schemas
+ */
+export type CatalystManifestInput = z.input<typeof CatalystManifestSchema>;
+export type CatalystManifestOutput = z.output<typeof CatalystManifestSchema>;
+export type PlanManifestInput = z.input<typeof PlanManifestSchema>;
+export type PlanManifestOutput = z.output<typeof PlanManifestSchema>;
+export type FacetsDeclaration = z.infer<typeof FacetsDeclarationSchema>;