k0ntext 3.3.1 → 3.6.0

package/src/template-engine/helpers.ts

@@ -0,0 +1,163 @@
+/**
+ * Template Helpers
+ *
+ * Custom Handlebars helpers for template rendering.
+ */
+
+import type { HelperDelegate } from 'handlebars';
+
+/**
+ * Join array elements with a separator
+ */
+export const join: HelperDelegate = function (array: unknown[], separator = ', ') {
+  if (!Array.isArray(array)) return '';
+  return array.filter(Boolean).join(separator);
+};
+
+/**
+ * Get first N elements of an array
+ */
+export const first: HelperDelegate = function (array: unknown[], n = 1) {
+  if (!Array.isArray(array)) return [];
+  return array.slice(0, n);
+};
+
+/**
+ * Truncate a string to a maximum length
+ */
+export const truncate: HelperDelegate = function (str: unknown, len = 50, suffix = '...') {
+  if (typeof str !== 'string') return '';
+  if (str.length <= len) return str;
+  return str.slice(0, len) + suffix;
+};
+
+/**
+ * Slugify a string (convert to URL-friendly format)
+ */
+export const slugify: HelperDelegate = function (str: unknown) {
+  if (typeof str !== 'string') return '';
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+};
+
+/**
+ * Format a date
+ */
+export const formatDate: HelperDelegate = function (date: unknown, format = 'ISO') {
+  if (!date) return '';
+  const d = typeof date === 'string' ? new Date(date) : date as Date;
+  if (isNaN(d.getTime())) return '';
+
+  switch (format) {
+    case 'ISO':
+      return d.toISOString();
+    case 'locale':
+      return d.toLocaleDateString();
+    case 'time':
+      return d.toLocaleTimeString();
+    case 'short':
+      return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+    default:
+      return d.toISOString();
+  }
+};
+
+/**
+ * Conditional equality check
+ */
+export const eq: HelperDelegate = function (this: unknown, a: unknown, b: unknown, options: any) {
+  return a === b ? options.fn(this) : options.inverse(this);
+};
+
+/**
+ * Conditional inequality check
+ */
+export const ne: HelperDelegate = function (this: unknown, a: unknown, b: unknown, options: any) {
+  return a !== b ? options.fn(this) : options.inverse(this);
+};
+
+/**
+ * Logical AND
+ */
+export const and: HelperDelegate = function (this: unknown, ...args: unknown[]) {
+  const options = args[args.length - 1] as any;
+  const values = args.slice(0, -1);
+  return values.every(v => Boolean(v)) ? options.fn(this) : options.inverse(this);
+};
+
+/**
+ * Logical OR
+ */
+export const or: HelperDelegate = function (this: unknown, ...args: unknown[]) {
+  const options = args[args.length - 1] as any;
+  const values = args.slice(0, -1);
+  return values.some(v => Boolean(v)) ? options.fn(this) : options.inverse(this);
+};
+
+/**
+ * Default value if undefined/null
+ */
+export const defaults: HelperDelegate = function (value: unknown, defaultValue: unknown) {
+  return value !== null && value !== undefined ? value : defaultValue;
+};
+
+/**
+ * JSON stringify
+ */
+export const json: HelperDelegate = function (obj: unknown, spaces = 2) {
+  return JSON.stringify(obj, null, spaces);
+};
+
+/**
+ * Get object keys
+ */
+export const keys: HelperDelegate = function (obj: Record<string, unknown>) {
+  return Object.keys(obj || {});
+};
+
+/**
+ * Get object values
+ */
+export const values: HelperDelegate = function (obj: Record<string, unknown>) {
+  return Object.values(obj || {});
+};
+
+/**
+ * Register all helpers with a Handlebars instance
+ */
+export function registerHelpers(Handlebars: any): void {
+  Handlebars.registerHelper('join', join);
+  Handlebars.registerHelper('first', first);
+  Handlebars.registerHelper('truncate', truncate);
+  Handlebars.registerHelper('slugify', slugify);
+  Handlebars.registerHelper('formatDate', formatDate);
+  Handlebars.registerHelper('eq', eq);
+  Handlebars.registerHelper('ne', ne);
+  Handlebars.registerHelper('and', and);
+  Handlebars.registerHelper('or', or);
+  Handlebars.registerHelper('defaults', defaults);
+  Handlebars.registerHelper('json', json);
+  Handlebars.registerHelper('keys', keys);
+  Handlebars.registerHelper('values', values);
+}
+
+/**
+ * Export helpers as an object for external use
+ */
+export const helpers = {
+  join,
+  first,
+  truncate,
+  slugify,
+  formatDate,
+  eq,
+  ne,
+  and,
+  or,
+  defaults,
+  json,
+  keys,
+  values
+};

package/src/template-engine/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Template Engine Module
+ *
+ * Exports all template engine functionality.
+ */
+
+export * from './types.js';
+export * from './helpers.js';
+export * from './data-transformer.js';
+export * from './engine.js';

package/src/template-engine/types.ts

@@ -0,0 +1,158 @@
+/**
+ * Template Engine Types
+ *
+ * Type definitions for template data and rendering.
+ */
+
+/**
+ * Project metadata for templates
+ */
+export interface ProjectTemplateData {
+  name: string;
+  description?: string;
+  type?: string;
+  tech_stack: string[];
+  primary_language?: string;
+  version?: string;
+}
+
+/**
+ * Architecture information
+ */
+export interface ArchitectureTemplateData {
+  pattern?: string;
+  layers?: LayerInfo[];
+  key_modules?: string[];
+  integrations?: string[];
+}
+
+/**
+ * Layer information
+ */
+export interface LayerInfo {
+  name: string;
+  path: string;
+  purpose?: string;
+}
+
+/**
+ * Key files information
+ */
+export interface KeyFilesTemplateData {
+  entry_points?: string[];
+  api_routes?: string[];
+  config?: string[];
+  tests?: string[];
+}
+
+/**
+ * Commands information
+ */
+export interface CommandsTemplateData {
+  install?: string;
+  dev?: string;
+  test?: string;
+  build?: string;
+  lint?: string;
+  clean?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Workflow information for templates
+ */
+export interface WorkflowTemplateData {
+  name: string;
+  category?: string;
+  complexity?: string;
+  description?: string;
+  entry_points?: Array<{
+    endpoint: string;
+    file: string;
+    line?: number;
+    method?: string;
+  }>;
+  files?: string[];
+  steps?: string[];
+}
+
+/**
+ * Gotcha information
+ */
+export interface GotchaTemplateData {
+  title?: string;
+  description: string;
+  severity?: 'low' | 'medium' | 'high' | 'critical';
+  location?: string;
+}
+
+/**
+ * Environment variables information
+ */
+export interface EnvironmentTemplateData {
+  required?: string[];
+  optional?: string[];
+}
+
+/**
+ * Coordination/footer information
+ */
+export interface CoordinationTemplateData {
+  footer?: string;
+  version?: string;
+  timestamp?: string;
+}
+
+/**
+ * Complete template data model
+ */
+export interface TemplateData {
+  /** Project metadata */
+  project: ProjectTemplateData;
+  /** Architecture information */
+  architecture: ArchitectureTemplateData;
+  /** Key files */
+  key_files: KeyFilesTemplateData;
+  /** Development commands */
+  commands: CommandsTemplateData;
+  /** Workflows */
+  workflows: WorkflowTemplateData[];
+  /** Gotchas / critical gotchas */
+  gotchas?: GotchaTemplateData[];
+  /** Critical constraints */
+  critical_constraints?: string[];
+  /** Environment variables */
+  environment?: EnvironmentTemplateData;
+  /** Metadata */
+  metadata: {
+    generator_version: string;
+    timestamp: string;
+    header?: string;
+  };
+  /** Coordination/footer */
+  coordination?: CoordinationTemplateData;
+}
+
+/**
+ * Template rendering options
+ */
+export interface TemplateRenderOptions {
+  /** Template name (e.g., 'claude', 'copilot') */
+  template: string;
+  /** Whether to use partials */
+  usePartials?: boolean;
+  /** Custom data to merge */
+  customData?: Partial<TemplateData>;
+}
+
+/**
+ * Template render result
+ */
+export interface TemplateRenderResult {
+  /** Rendered content */
+  content: string;
+  /** Template used */
+  template: string;
+  /** Bytes written */
+  bytes: number;
+}