@planvokter/riotplan-catalyst 1.0.17-dev.0

package/dist/riotplan-catalyst.d.ts

@@ -0,0 +1,534 @@
+/**
+ * @packageDocumentation
+ * Catalyst system for RiotPlan - composable, layerable guidance packages for plan creation
+ */
+
+import { z } from 'zod';
+
+/**
+ * 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 declare function addCatalystToManifest(planDirectory: string, catalystId: string): Promise<void>;
+
+/**
+ * A single piece of content with source attribution
+ */
+export declare interface AttributedContent {
+    content: string;
+    sourceId: string;
+    filename?: string;
+}
+
+/**
+ * A fully loaded catalyst with manifest and all facet content
+ */
+export declare interface Catalyst {
+    /** Parsed manifest from catalyst.yml */
+    manifest: CatalystManifest;
+    /** Loaded content for each facet type */
+    facets: CatalystFacets;
+    /** Absolute path to the catalyst directory */
+    directoryPath: string;
+}
+
+/**
+ * Container for all loaded facet content from a catalyst
+ * Each facet type maps to an array of file contents
+ */
+export declare interface CatalystFacets {
+    /** Guiding questions for idea exploration and shaping */
+    questions?: FacetContent[];
+    /** Constraints and rules the plan must satisfy */
+    constraints?: FacetContent[];
+    /** Templates for expected deliverables (press release, 6-pager, etc.) */
+    outputTemplates?: FacetContent[];
+    /** Context about the domain, organization, or technology */
+    domainKnowledge?: FacetContent[];
+    /** Guidance on how to run the planning process */
+    processGuidance?: FacetContent[];
+    /** Post-creation validation checks */
+    validationRules?: FacetContent[];
+}
+
+/**
+ * Options for loading a catalyst
+ */
+export declare interface CatalystLoadOptions {
+    /** Whether to validate the manifest strictly */
+    strict?: boolean;
+    /** Whether to warn about declared but missing facets */
+    warnOnMissingFacets?: boolean;
+    /** Whether to warn about present but undeclared facets */
+    warnOnUndeclaredFacets?: boolean;
+}
+
+/**
+ * Result of loading a catalyst - either success or error
+ */
+export declare interface CatalystLoadResult {
+    success: boolean;
+    catalyst?: Catalyst;
+    error?: string;
+    warnings?: string[];
+}
+
+/**
+ * Parsed catalyst.yml manifest
+ */
+export declare interface CatalystManifest {
+    /** Catalyst identifier (NPM package name) */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this catalyst provides */
+    description: string;
+    /** Semver version */
+    version: string;
+    /** Declaration of which facets this catalyst provides */
+    facets?: {
+        questions?: boolean;
+        constraints?: boolean;
+        outputTemplates?: boolean;
+        domainKnowledge?: boolean;
+        processGuidance?: boolean;
+        validationRules?: boolean;
+    };
+}
+
+/**
+ * Inferred TypeScript types from Zod schemas
+ */
+export declare type CatalystManifestInput = z.input<typeof CatalystManifestSchema>;
+
+export declare type CatalystManifestOutput = z.output<typeof CatalystManifestSchema>;
+
+/**
+ * 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 declare const CatalystManifestSchema: z.ZodObject<{
+    /**
+     * Catalyst identifier - should match NPM package name
+     * @example "@kjerneverk/catalyst-nodejs"
+     */
+    id: z.ZodString;
+    /** Human-readable name for display */
+    name: z.ZodString;
+    /** Description of what this catalyst provides */
+    description: z.ZodString;
+    /**
+     * Semver version string
+     * @example "1.0.0" or "1.0.0-dev.0"
+     */
+    version: z.ZodString;
+    /**
+     * Declaration of which facets this catalyst provides
+     * If omitted, facets are auto-detected from directory structure
+     */
+    facets: z.ZodOptional<z.ZodObject<{
+        questions: z.ZodOptional<z.ZodBoolean>;
+        constraints: z.ZodOptional<z.ZodBoolean>;
+        outputTemplates: z.ZodOptional<z.ZodBoolean>;
+        domainKnowledge: z.ZodOptional<z.ZodBoolean>;
+        processGuidance: z.ZodOptional<z.ZodBoolean>;
+        validationRules: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        questions?: boolean | undefined;
+        constraints?: boolean | undefined;
+        outputTemplates?: boolean | undefined;
+        domainKnowledge?: boolean | undefined;
+        processGuidance?: boolean | undefined;
+        validationRules?: boolean | undefined;
+    }, {
+        questions?: boolean | undefined;
+        constraints?: boolean | undefined;
+        outputTemplates?: boolean | undefined;
+        domainKnowledge?: boolean | undefined;
+        processGuidance?: boolean | undefined;
+        validationRules?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    facets?: {
+        questions?: boolean | undefined;
+        constraints?: boolean | undefined;
+        outputTemplates?: boolean | undefined;
+        domainKnowledge?: boolean | undefined;
+        processGuidance?: boolean | undefined;
+        validationRules?: boolean | undefined;
+    } | undefined;
+}, {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    facets?: {
+        questions?: boolean | undefined;
+        constraints?: boolean | undefined;
+        outputTemplates?: boolean | undefined;
+        domainKnowledge?: boolean | undefined;
+        processGuidance?: boolean | undefined;
+        validationRules?: boolean | undefined;
+    } | undefined;
+}>;
+
+/**
+ * Facet directory names as they appear on disk
+ */
+export declare const FACET_DIRECTORIES: {
+    readonly questions: "questions";
+    readonly constraints: "constraints";
+    readonly outputTemplates: "output-templates";
+    readonly domainKnowledge: "domain-knowledge";
+    readonly processGuidance: "process-guidance";
+    readonly validationRules: "validation-rules";
+};
+
+/**
+ * All valid facet types
+ */
+export declare const FACET_TYPES: readonly ["questions", "constraints", "outputTemplates", "domainKnowledge", "processGuidance", "validationRules"];
+
+/**
+ * Content loaded from a single facet file
+ */
+export declare interface FacetContent {
+    /** Filename without path (e.g., "testing.md") */
+    filename: string;
+    /** Full content of the file */
+    content: string;
+}
+
+/**
+ * Mapping from facet type to directory name on disk
+ */
+export declare type FacetDirectoryMap = Record<FacetType, string>;
+
+export declare type FacetsDeclaration = z.infer<typeof FacetsDeclarationSchema>;
+
+/**
+ * Schema for the facets declaration in catalyst.yml
+ * Each facet can be declared as present (true) or explicitly absent (false)
+ */
+export declare const FacetsDeclarationSchema: z.ZodObject<{
+    questions: z.ZodOptional<z.ZodBoolean>;
+    constraints: z.ZodOptional<z.ZodBoolean>;
+    outputTemplates: z.ZodOptional<z.ZodBoolean>;
+    domainKnowledge: z.ZodOptional<z.ZodBoolean>;
+    processGuidance: z.ZodOptional<z.ZodBoolean>;
+    validationRules: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    questions?: boolean | undefined;
+    constraints?: boolean | undefined;
+    outputTemplates?: boolean | undefined;
+    domainKnowledge?: boolean | undefined;
+    processGuidance?: boolean | undefined;
+    validationRules?: boolean | undefined;
+}, {
+    questions?: boolean | undefined;
+    constraints?: boolean | undefined;
+    outputTemplates?: boolean | undefined;
+    domainKnowledge?: boolean | undefined;
+    processGuidance?: boolean | undefined;
+    validationRules?: boolean | undefined;
+}>;
+
+export declare type FacetType = typeof FACET_TYPES[number];
+
+/**
+ * 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 declare function loadCatalyst(directoryPath: string, options?: CatalystLoadOptions): Promise<Catalyst>;
+
+/**
+ * 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 declare function loadCatalystSafe(directoryPath: string, options?: CatalystLoadOptions): Promise<CatalystLoadResult>;
+
+/**
+ * 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 declare function mergeCatalysts(catalysts: Catalyst[]): MergedCatalyst;
+
+/**
+ * Result of merging multiple catalysts
+ */
+export declare 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;
+    }>;
+}
+
+/**
+ * Facets merged from multiple catalysts with source attribution
+ */
+export declare interface MergedFacets {
+    questions?: AttributedContent[];
+    constraints?: AttributedContent[];
+    outputTemplates?: AttributedContent[];
+    domainKnowledge?: AttributedContent[];
+    processGuidance?: AttributedContent[];
+    validationRules?: AttributedContent[];
+}
+
+/**
+ * Plan manifest stored in plan.yaml
+ */
+export declare interface PlanManifest {
+    /** Plan identifier */
+    id: string;
+    /** Human-readable title */
+    title: string;
+    /** Ordered list of catalyst IDs */
+    catalysts?: string[];
+    /** ISO timestamp of creation */
+    created?: string;
+    /** Extensible metadata */
+    metadata?: Record<string, string>;
+}
+
+/**
+ * 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
+ */
+declare type PlanManifest_2 = PlanManifestOutput;
+
+export declare type PlanManifestInput = z.input<typeof PlanManifestSchema>;
+
+export declare type PlanManifestOutput = z.output<typeof PlanManifestSchema>;
+
+/**
+ * Schema for plan.yaml manifest file
+ *
+ * The plan manifest gives each plan an identity and records which catalysts
+ * are associated with it.
+ */
+export declare const PlanManifestSchema: z.ZodObject<{
+    /** Plan identifier (typically kebab-case) */
+    id: z.ZodString;
+    /** Human-readable title */
+    title: z.ZodString;
+    /**
+     * Ordered list of catalyst IDs associated with this plan
+     * Catalysts are applied in order (first = base, last = top layer)
+     */
+    catalysts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** ISO timestamp of when the plan was created */
+    created: z.ZodOptional<z.ZodString>;
+    /** Extensible metadata for future use */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    catalysts?: string[] | undefined;
+    created?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}, {
+    id: string;
+    title: string;
+    catalysts?: string[] | undefined;
+    created?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+}>;
+
+/**
+ * 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 declare function readPlanManifest(planDirectory: string): Promise<PlanManifest_2 | null>;
+
+/**
+ * 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 declare function removeCatalystFromManifest(planDirectory: string, catalystId: string): Promise<void>;
+
+/**
+ * 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 declare function renderAllFacets(merged: MergedCatalyst): Record<FacetType, string>;
+
+/**
+ * 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 declare function renderFacet(merged: MergedCatalyst, facetType: FacetType): string;
+
+/**
+ * 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 declare function resolveCatalysts(identifiers: string[], basePath?: string, options?: CatalystLoadOptions): Promise<Catalyst[]>;
+
+/**
+ * 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 declare function summarizeMerge(merged: MergedCatalyst): string;
+
+/**
+ * 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 declare function updatePlanManifest(planDirectory: string, updates: Partial<PlanManifest_2>): Promise<void>;
+
+/**
+ * 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 declare function writePlanManifest(planDirectory: string, manifest: PlanManifest_2): Promise<void>;
+
+export { }