@kjerneverk/riotplan-catalyst 1.0.0-dev.0

package/.nvmrc

@@ -0,0 +1 @@
+v24.0.0

package/README.md

@@ -0,0 +1,327 @@
+# @kjerneverk/riotplan-catalyst
+
+Catalyst system for RiotPlan - composable, layerable guidance packages that shape the entire planning process.
+
+## What is a Catalyst?
+
+A catalyst is a collection of resources that affects the questions asked and the process used to come up with a plan. It provides guidance through six facets:
+
+- **Questions** - Things to consider during exploration
+- **Constraints** - Rules the plan must satisfy
+- **Output Templates** - Expected deliverables
+- **Domain Knowledge** - Context about the domain
+- **Process Guidance** - How to approach the planning process
+- **Validation Rules** - Post-creation checks
+
+## Installation
+
+```bash
+npm install @kjerneverk/riotplan-catalyst
+```
+
+## Usage
+
+### Loading a Single Catalyst
+
+```typescript
+import { loadCatalyst } from '@kjerneverk/riotplan-catalyst';
+
+// Load a catalyst from a directory
+const result = await loadCatalyst('./my-catalyst');
+
+if (result.success) {
+  console.log('Loaded:', result.catalyst.manifest.name);
+  console.log('Facets:', Object.keys(result.catalyst.facets));
+} else {
+  console.error('Failed to load:', result.error);
+}
+```
+
+### Loading Multiple Catalysts
+
+```typescript
+import { resolveCatalysts } from '@kjerneverk/riotplan-catalyst';
+
+// Resolve multiple catalysts by path
+const catalysts = await resolveCatalysts([
+  './catalysts/software',
+  './catalysts/nodejs',
+  './catalysts/company'
+]);
+
+console.log(`Loaded ${catalysts.length} catalysts`);
+```
+
+### Merging Catalysts
+
+```typescript
+import { resolveCatalysts, mergeCatalysts } from '@kjerneverk/riotplan-catalyst';
+
+// Load and merge catalysts
+const catalysts = await resolveCatalysts(['./catalyst-1', './catalyst-2']);
+const merged = mergeCatalysts(catalysts);
+
+// Access merged content
+console.log('Applied catalysts:', merged.catalystIds);
+console.log('Questions:', merged.facets.questions);
+console.log('Constraints:', merged.facets.constraints);
+```
+
+### Working with Plan Manifests
+
+```typescript
+import { 
+  readPlanManifest, 
+  writePlanManifest,
+  addCatalystToManifest 
+} from '@kjerneverk/riotplan-catalyst';
+
+// Read plan manifest
+const manifest = await readPlanManifest('./my-plan');
+console.log('Plan:', manifest.title);
+console.log('Catalysts:', manifest.catalysts);
+
+// Add a catalyst to a plan
+await addCatalystToManifest('./my-plan', '@kjerneverk/catalyst-nodejs');
+
+// Create a new plan manifest
+await writePlanManifest('./new-plan', {
+  id: 'new-plan',
+  title: 'New Plan',
+  catalysts: ['@kjerneverk/catalyst-nodejs'],
+  created: new Date().toISOString()
+});
+```
+
+## Catalyst Directory Structure
+
+```
+my-catalyst/
+  catalyst.yml              # Manifest (required)
+  questions/                # Optional
+    exploration.md          # Questions for idea phase
+  constraints/              # Optional
+    testing.md              # Testing requirements
+  output-templates/         # Optional
+    press-release.md        # Press release template
+  domain-knowledge/         # Optional
+    overview.md             # Domain context
+  process-guidance/         # Optional
+    lifecycle.md            # Process guidance
+  validation-rules/         # Optional
+    checklist.md            # Validation checklist
+```
+
+## Schema Reference
+
+### catalyst.yml
+
+```yaml
+id: '@myorg/catalyst-name'        # NPM package name format (required)
+name: 'Human Readable Name'       # Display name (required)
+version: '1.0.0'                  # Semver version (required)
+description: 'What this provides' # Description (required)
+facets:                           # Optional - auto-detected if omitted
+  questions: true
+  constraints: true
+  outputTemplates: true
+  domainKnowledge: true
+  processGuidance: true
+  validationRules: true
+```
+
+**Validation Rules:**
+- `id` must be a valid NPM package name (e.g., `@scope/name` or `name`)
+- `version` must be valid semver (e.g., `1.0.0` or `1.0.0-dev.0`)
+- `name` and `description` cannot be empty
+- Facets are optional - if omitted, detected from directory structure
+
+### plan.yaml
+
+```yaml
+id: 'plan-identifier'             # Plan ID (required)
+title: 'Plan Title'               # Display title (required)
+catalysts:                        # Optional - list of catalyst IDs
+  - '@myorg/catalyst-nodejs'
+  - '@myorg/catalyst-company'
+created: '2026-01-15T10:30:00Z'   # ISO timestamp (optional)
+metadata:                         # Optional - extensible
+  author: 'John Doe'
+  tags: ['feature', 'api']
+```
+
+## API Reference
+
+### Loader Functions
+
+#### `loadCatalyst(path: string): Promise<CatalystLoadResult>`
+
+Load a single catalyst from a directory.
+
+**Returns:**
+```typescript
+{
+  success: true,
+  catalyst: {
+    manifest: { id, name, version, description, facets },
+    directory: '/absolute/path',
+    facets: {
+      questions: [{ filename, content }],
+      constraints: [{ filename, content }],
+      // ... other facets
+    }
+  }
+}
+// or
+{
+  success: false,
+  error: 'Error message'
+}
+```
+
+#### `loadCatalystSafe(path: string): Promise<Catalyst | null>`
+
+Load a catalyst, returning null on error (no exception thrown).
+
+#### `resolveCatalysts(identifiers: string[]): Promise<Catalyst[]>`
+
+Load multiple catalysts by path. Skips any that fail to load.
+
+**Example:**
+```typescript
+const catalysts = await resolveCatalysts([
+  './catalyst-1',
+  './catalyst-2',
+  './catalyst-3'
+]);
+// Returns only successfully loaded catalysts
+```
+
+### Merger Functions
+
+#### `mergeCatalysts(catalysts: Catalyst[]): MergedCatalyst`
+
+Merge multiple catalysts into a single structure with source attribution.
+
+**Returns:**
+```typescript
+{
+  catalystIds: ['@org/cat-1', '@org/cat-2'],
+  facets: {
+    questions: [
+      { content: '...', sourceId: '@org/cat-1', filename: 'setup.md' },
+      { content: '...', sourceId: '@org/cat-2', filename: 'config.md' }
+    ],
+    // ... other facets
+  }
+}
+```
+
+#### `renderFacet(facetName: string, merged: MergedCatalyst): string`
+
+Render a single facet as markdown with source attribution.
+
+#### `renderAllFacets(merged: MergedCatalyst): Record<string, string>`
+
+Render all facets as markdown strings.
+
+**Example:**
+```typescript
+const rendered = renderAllFacets(merged);
+console.log(rendered.questions);
+console.log(rendered.constraints);
+```
+
+### Plan Manifest Functions
+
+#### `readPlanManifest(planPath: string): Promise<PlanManifest>`
+
+Read plan.yaml from a plan directory.
+
+#### `writePlanManifest(planPath: string, manifest: PlanManifest): Promise<void>`
+
+Write plan.yaml to a plan directory.
+
+#### `updatePlanManifest(planPath: string, updates: Partial<PlanManifest>): Promise<void>`
+
+Update specific fields in plan.yaml.
+
+#### `addCatalystToManifest(planPath: string, catalystId: string): Promise<void>`
+
+Add a catalyst ID to the plan's catalyst list (if not already present).
+
+#### `removeCatalystFromManifest(planPath: string, catalystId: string): Promise<void>`
+
+Remove a catalyst ID from the plan's catalyst list.
+
+## TypeScript Types
+
+```typescript
+// Catalyst manifest
+interface CatalystManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  facets?: FacetsDeclaration;
+}
+
+// Facet content
+interface FacetContent {
+  filename: string;
+  content: string;
+}
+
+// Loaded catalyst
+interface Catalyst {
+  manifest: CatalystManifest;
+  directory: string;
+  facets: CatalystFacets;
+}
+
+// Merged catalyst with attribution
+interface MergedCatalyst {
+  catalystIds: string[];
+  facets: Record<string, AttributedContent[]>;
+}
+
+interface AttributedContent {
+  content: string;
+  sourceId: string;
+  filename?: string;
+}
+
+// Plan manifest
+interface PlanManifest {
+  id: string;
+  title: string;
+  catalysts?: string[];
+  created?: string;
+  metadata?: Record<string, string>;
+}
+```
+
+## Error Handling
+
+All loader functions return structured results:
+
+```typescript
+// Success
+{ success: true, catalyst: Catalyst }
+
+// Failure
+{ success: false, error: string }
+```
+
+Safe variants return `null` on error:
+
+```typescript
+const catalyst = await loadCatalystSafe('./path');
+if (catalyst === null) {
+  console.error('Failed to load');
+}
+```
+
+## License
+
+Apache-2.0

package/eslint.config.mjs

@@ -0,0 +1,38 @@
+import js from '@eslint/js';
+import ts from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+import importPlugin from 'eslint-plugin-import';
+
+export default [
+  {
+    ignores: ['dist/**', 'node_modules/**', '**/*.test.ts', 'vitest.config.ts', 'vite.config.ts'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2024,
+        sourceType: 'module',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        NodeJS: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': ts,
+      import: importPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...ts.configs.recommended.rules,
+      indent: ['error', 2],
+      quotes: ['error', 'single'],
+      semi: ['error', 'always'],
+      'no-console': ['error', { allow: ['warn', 'error'] }],
+      'import/order': 'error',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kjerneverk/riotplan-catalyst",
+  "version": "1.0.0-dev.0",
+  "description": "Catalyst system for RiotPlan - composable, layerable guidance packages for plan creation",
+  "type": "module",
+  "main": "./dist/riotplan-catalyst.js",
+  "types": "./dist/riotplan-catalyst.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/riotplan-catalyst.d.ts",
+      "import": "./dist/riotplan-catalyst.js"
+    }
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "npm run lint && vite build",
+    "test": "npm run test:coverage",
+    "test:coverage": "vitest run --coverage",
+    "test:debug": "vitest --run --coverage --reporter verbose",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "precommit": "npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-replace": "^5.0.5",
+    "@types/node": "^25.2.2",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.1.0",
+    "eslint": "^8.56.0",
+    "eslint-plugin-import": "^2.29.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.1.0",
+    "vite-plugin-dts": "^1.0.0",
+    "vitest": "^1.1.0"
+  },
+  "keywords": [
+    "riotplan",
+    "catalyst",
+    "planning",
+    "guidance",
+    "ai"
+  ],
+  "author": "Kjerneverk",
+  "license": "Apache-2.0"
+}

package/src/loader/catalyst-loader.ts

@@ -0,0 +1,261 @@
+/**
+ * Catalyst loading from local directories
+ * @packageDocumentation
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { 
+  CatalystManifestSchema, 
+  FACET_DIRECTORIES,
+  type FacetType,
+} from '@/schema/schemas';
+import type { 
+  Catalyst, 
+  CatalystManifest, 
+  CatalystFacets, 
+  FacetContent,
+  CatalystLoadOptions,
+  CatalystLoadResult,
+} from '@/types';
+
+/**
+ * Load a catalyst manifest from catalyst.yml
+ * @param directoryPath - Absolute path to catalyst directory
+ * @returns Parsed and validated manifest
+ * @throws Error if manifest is missing or invalid
+ */
+async function loadManifest(directoryPath: string): Promise<CatalystManifest> {
+  const manifestPath = join(directoryPath, 'catalyst.yml');
+  
+  try {
+    const content = await readFile(manifestPath, 'utf-8');
+    const parsed = parseYaml(content);
+    
+    // Validate with Zod schema
+    const result = CatalystManifestSchema.safeParse(parsed);
+    
+    if (!result.success) {
+      const errors = result.error.issues.map(issue => 
+        `${issue.path.join('.')}: ${issue.message}`
+      ).join('; ');
+      throw new Error(`Invalid catalyst manifest: ${errors}`);
+    }
+    
+    return result.data;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`Catalyst manifest not found at ${manifestPath}`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Load all markdown files from a facet directory
+ * @param facetPath - Path to facet directory
+ * @returns Array of FacetContent objects
+ */
+async function loadFacetFiles(facetPath: string): Promise<FacetContent[]> {
+  try {
+    const entries = await readdir(facetPath, { withFileTypes: true });
+    const markdownFiles = entries.filter(
+      entry => entry.isFile() && entry.name.endsWith('.md')
+    );
+    
+    const contents = await Promise.all(
+      markdownFiles.map(async (file) => {
+        const filePath = join(facetPath, file.name);
+        const content = await readFile(filePath, 'utf-8');
+        return {
+          filename: file.name,
+          content,
+        };
+      })
+    );
+    
+    return contents;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      // Directory doesn't exist - return empty array
+      return [];
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if a directory exists
+ */
+async function directoryExists(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load all facets from a catalyst directory
+ * @param directoryPath - Absolute path to catalyst directory
+ * @param manifest - Parsed manifest (for cross-referencing)
+ * @param options - Load options
+ * @returns Loaded facets and any warnings
+ */
+async function loadFacets(
+  directoryPath: string,
+  manifest: CatalystManifest,
+  options: CatalystLoadOptions = {}
+): Promise<{ facets: CatalystFacets; warnings: string[] }> {
+  const facets: CatalystFacets = {};
+  const warnings: string[] = [];
+  
+  // Load each facet type
+  for (const [facetKey, dirName] of Object.entries(FACET_DIRECTORIES)) {
+    const facetType = facetKey as FacetType;
+    const facetPath = join(directoryPath, dirName);
+    const exists = await directoryExists(facetPath);
+    
+    // Check if facet is declared in manifest
+    const declared = manifest.facets?.[facetType];
+    
+    if (exists) {
+      // Load the facet content
+      const content = await loadFacetFiles(facetPath);
+      if (content.length > 0) {
+        facets[facetType] = content;
+      }
+      
+      // Warn if present but explicitly declared as false
+      if (declared === false && options.warnOnUndeclaredFacets) {
+        warnings.push(
+          `Facet '${facetType}' is present but declared as false in manifest`
+        );
+      }
+    } else {
+      // Warn if declared but missing
+      if (declared === true && options.warnOnMissingFacets) {
+        warnings.push(
+          `Facet '${facetType}' is declared in manifest but directory '${dirName}' not found`
+        );
+      }
+    }
+  }
+  
+  return { facets, warnings };
+}
+
+/**
+ * Load a catalyst from a local directory
+ * 
+ * Reads the catalyst.yml manifest, validates it, and loads all facet content
+ * from the directory structure.
+ * 
+ * @param directoryPath - Path to catalyst directory (absolute or relative)
+ * @param options - Load options
+ * @returns Loaded catalyst
+ * @throws Error if manifest is missing or invalid
+ * 
+ * @example
+ * ```typescript
+ * const catalyst = await loadCatalyst('./my-catalyst');
+ * console.log(catalyst.manifest.name);
+ * console.log(catalyst.facets.constraints?.length);
+ * ```
+ */
+export async function loadCatalyst(
+  directoryPath: string,
+  options: CatalystLoadOptions = {}
+): Promise<Catalyst> {
+  // Resolve to absolute path
+  const absolutePath = resolve(directoryPath);
+  
+  // Check if directory exists
+  if (!await directoryExists(absolutePath)) {
+    throw new Error(`Catalyst directory not found: ${absolutePath}`);
+  }
+  
+  // Load and validate manifest
+  const manifest = await loadManifest(absolutePath);
+  
+  // Load all facets
+  const { facets, warnings } = await loadFacets(absolutePath, manifest, options);
+  
+  // Log warnings if any
+  if (warnings.length > 0 && !options.strict) {
+    for (const warning of warnings) {
+      console.warn(`[catalyst-loader] ${warning}`);
+    }
+  }
+  
+  return {
+    manifest,
+    facets,
+    directoryPath: absolutePath,
+  };
+}
+
+/**
+ * Load a catalyst with full error handling
+ * 
+ * Like loadCatalyst but returns a result object instead of throwing
+ * 
+ * @param directoryPath - Path to catalyst directory
+ * @param options - Load options
+ * @returns Result object with success/error
+ */
+export async function loadCatalystSafe(
+  directoryPath: string,
+  options: CatalystLoadOptions = {}
+): Promise<CatalystLoadResult> {
+  try {
+    const catalyst = await loadCatalyst(directoryPath, options);
+    return {
+      success: true,
+      catalyst,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Resolve catalyst identifiers to directories and load them
+ * 
+ * Phase 1: Only supports local directory paths (absolute or relative)
+ * Phase 2 (future): Will support NPM package resolution from node_modules
+ * 
+ * @param identifiers - Array of catalyst paths
+ * @param basePath - Base path for resolving relative paths
+ * @param options - Load options
+ * @returns Array of loaded catalysts
+ */
+export async function resolveCatalysts(
+  identifiers: string[],
+  basePath: string = process.cwd(),
+  options: CatalystLoadOptions = {}
+): Promise<Catalyst[]> {
+  const catalysts: Catalyst[] = [];
+  
+  for (const identifier of identifiers) {
+    // Phase 1: treat identifier as a path
+    // If it's relative, resolve from basePath
+    const path = resolve(basePath, identifier);
+    
+    try {
+      const catalyst = await loadCatalyst(path, options);
+      catalysts.push(catalyst);
+    } catch (error) {
+      throw new Error(
+        `Failed to load catalyst '${identifier}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  
+  return catalysts;
+}