@specmind/format 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @specmind/format
+
+.sm file format parser and writer for SpecMind.
+
+## Overview
+
+This package provides the core .sm file format implementation:
+- **Zod schemas** for validation and type generation
+- **Parser** for converting markdown to SmFile objects
+- **Writer** for generating .sm files from SmFile objects
+- **Utilities** for feature naming and file paths
+
+## Installation
+
+```bash
+npm install @specmind/format
+# or
+pnpm add @specmind/format
+```
+
+## Usage
+
+```typescript
+import { parseSmFile, writeSmFile, createFeatureName } from '@specmind/format'
+
+// Parse .sm file content
+const content = '# Feature Name\n\n## Overview\nDescription...'
+const result = parseSmFile(content, 'feature')
+
+if (result.success) {
+  console.log(result.data.name) // "Feature Name"
+  console.log(result.data.requirements) // ["req1", "req2"]
+
+  // Write back to markdown
+  const writeResult = writeSmFile(result.data)
+  console.log(writeResult.content) // Generated .sm content
+}
+
+// Create feature names
+const featureName = createFeatureName('User Authentication')
+console.log(featureName.slug) // "user-authentication"
+console.log(featureName.filename) // "user-authentication.sm"
+```
+
+## Development
+
+### Commands
+
+```bash
+# Build package
+pnpm build
+
+# Run unit tests
+pnpm test
+
+# Type checking
+pnpm lint
+
+# Validate test fixtures (end-to-end)
+pnpm validate-fixtures
+
+# Clean build outputs
+pnpm clean
+```
+
+### Testing Strategy
+
+This package uses **two complementary testing approaches**:
+
+#### **Unit Tests** (`pnpm test`)
+- **Purpose**: Test individual functions with controlled inputs
+- **Location**: `src/*.test.ts`
+- **Speed**: Fast (milliseconds)
+- **Examples**:
+  - Function behavior with edge cases
+  - Error handling and validation
+  - Small, focused test cases
+
+#### **Fixture Validation** (`pnpm validate-fixtures`)
+- **Purpose**: End-to-end validation with realistic .sm files
+- **Location**: `test-fixtures/` + `scripts/validate-fixtures.mjs`
+- **Speed**: Slower (file I/O, full parsing)
+- **Examples**:
+  - Complete feature specifications
+  - Complex Mermaid diagrams with subgraphs
+  - Real-world content roundtrip testing
+
+**Both are important**: Unit tests catch regressions and edge cases, while fixture validation ensures real-world usage works correctly.
+
+## API Reference
+
+### Types
+
+```typescript
+import type { SmFile, FeatureName } from '@specmind/format'
+```
+
+### Functions
+
+- `parseSmFile(content, type?)` - Parse .sm content to SmFile object
+- `writeSmFile(smFile)` - Convert SmFile object to markdown
+- `validateSmFileForWriting(smFile)` - Check for writing issues
+- `createFeatureName(name)` - Generate slug and filename from feature name
+- `slugify(name)` - Convert string to kebab-case slug
+- `getFeatureFilePath(slug)` - Get `.specmind/features/{slug}.sm` path
+- `getSystemFilePath()` - Get `.specmind/system.sm` path
+
+## .sm File Format
+
+See [CONSTITUTION.md](../../CONSTITUTION.md) Section 4.2 for complete format specification.
+
+**Example:**
+```markdown
+# Feature Name
+
+## Overview
+Feature description here.
+
+## Requirements
+- Requirement 1
+- Requirement 2
+
+## Architecture
+```mermaid
+graph TD
+    A --> B
+```
+
+## Design Decisions
+Rationale and trade-offs.
+
+## Integration Points
+- Service A: Integration details
+- Service B: Integration details
+
+## Notes
+Warnings, optimizations, tips.
+```

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @specmind/format
+ *
+ * Simplified .sm file format utilities for SpecMind
+ *
+ * This package provides:
+ * - Mermaid diagram extraction from markdown
+ * - Simple validation (markdown + at least one diagram)
+ * - Utilities for feature naming and file paths
+ *
+ * Based on CONSTITUTION.md Section 4.2:
+ * - .sm files are flexible markdown with any structure
+ * - Must contain at least one Mermaid diagram
+ * - No rigid section requirements
+ */
+export { SmFileSchema, FeatureNameSchema, type SmFile, type FeatureName } from './schemas.js';
+export { extractMermaidDiagrams, validateSmFile, parseSmFile, tryParseSmFile } from './parser.js';
+export { slugify, createFeatureName, isValidSlug, extractSlugFromFilename, getFeatureFilePath, getSystemFilePath } from './utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAG7F,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @specmind/format
+ *
+ * Simplified .sm file format utilities for SpecMind
+ *
+ * This package provides:
+ * - Mermaid diagram extraction from markdown
+ * - Simple validation (markdown + at least one diagram)
+ * - Utilities for feature naming and file paths
+ *
+ * Based on CONSTITUTION.md Section 4.2:
+ * - .sm files are flexible markdown with any structure
+ * - Must contain at least one Mermaid diagram
+ * - No rigid section requirements
+ */
+// Schemas
+export { SmFileSchema, FeatureNameSchema } from './schemas.js';
+// Parser
+export { extractMermaidDiagrams, validateSmFile, parseSmFile, tryParseSmFile } from './parser.js';
+// Utilities
+export { slugify, createFeatureName, isValidSlug, extractSlugFromFilename, getFeatureFilePath, getSystemFilePath } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAiC,MAAM,cAAc,CAAA;AAE7F,SAAS;AACT,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB,YAAY;AACZ,OAAO,EACL,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAA"}

package/dist/parser.d.ts

@@ -0,0 +1,44 @@
+import { SmFile } from './schemas.js';
+/**
+ * Extracts all Mermaid diagrams from markdown content
+ *
+ * @param markdown Markdown content
+ * @returns Array of Mermaid diagram strings (without the ``` markers)
+ */
+export declare function extractMermaidDiagrams(markdown: string): string[];
+/**
+ * Validates that content is a valid .sm file
+ *
+ * Requirements:
+ * - Non-empty content
+ * - At least one Mermaid diagram
+ *
+ * @param content Markdown content
+ * @returns Validation result
+ */
+export declare function validateSmFile(content: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Parses a .sm file content
+ *
+ * @param content Markdown content
+ * @returns Parsed SmFile object
+ * @throws Error if validation fails
+ */
+export declare function parseSmFile(content: string): SmFile;
+/**
+ * Safe version of parseSmFile that returns a result object
+ *
+ * @param content Markdown content
+ * @returns Parse result with success flag
+ */
+export declare function tryParseSmFile(content: string): {
+    success: true;
+    data: SmFile;
+} | {
+    success: false;
+    error: string;
+};
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAgB,MAAM,cAAc,CAAA;AAEnD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA+BjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkBlF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAenD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAC1C;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAWpC"}

package/dist/parser.js

@@ -0,0 +1,97 @@
+import { SmFileSchema } from './schemas.js';
+/**
+ * Extracts all Mermaid diagrams from markdown content
+ *
+ * @param markdown Markdown content
+ * @returns Array of Mermaid diagram strings (without the ``` markers)
+ */
+export function extractMermaidDiagrams(markdown) {
+    const diagrams = [];
+    const lines = markdown.split('\n');
+    let inMermaidBlock = false;
+    let currentDiagram = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === '```mermaid') {
+            inMermaidBlock = true;
+            currentDiagram = [];
+            continue;
+        }
+        if (trimmed === '```' && inMermaidBlock) {
+            inMermaidBlock = false;
+            if (currentDiagram.length > 0) {
+                diagrams.push(currentDiagram.join('\n').trim());
+            }
+            currentDiagram = [];
+            continue;
+        }
+        if (inMermaidBlock) {
+            currentDiagram.push(line);
+        }
+    }
+    return diagrams;
+}
+/**
+ * Validates that content is a valid .sm file
+ *
+ * Requirements:
+ * - Non-empty content
+ * - At least one Mermaid diagram
+ *
+ * @param content Markdown content
+ * @returns Validation result
+ */
+export function validateSmFile(content) {
+    if (!content || content.trim().length === 0) {
+        return {
+            valid: false,
+            error: 'Content cannot be empty'
+        };
+    }
+    const diagrams = extractMermaidDiagrams(content);
+    if (diagrams.length === 0) {
+        return {
+            valid: false,
+            error: 'Must have at least one Mermaid diagram'
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Parses a .sm file content
+ *
+ * @param content Markdown content
+ * @returns Parsed SmFile object
+ * @throws Error if validation fails
+ */
+export function parseSmFile(content) {
+    const validation = validateSmFile(content);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    const diagrams = extractMermaidDiagrams(content);
+    const smFile = {
+        content,
+        diagrams
+    };
+    return SmFileSchema.parse(smFile);
+}
+/**
+ * Safe version of parseSmFile that returns a result object
+ *
+ * @param content Markdown content
+ * @returns Parse result with success flag
+ */
+export function tryParseSmFile(content) {
+    try {
+        const data = parseSmFile(content);
+        return { success: true, data };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown parsing error'
+        };
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,YAAY,EAAE,MAAM,cAAc,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAElC,IAAI,cAAc,GAAG,KAAK,CAAA;IAC1B,IAAI,cAAc,GAAa,EAAE,CAAA;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAE3B,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;YAC7B,cAAc,GAAG,IAAI,CAAA;YACrB,cAAc,GAAG,EAAE,CAAA;YACnB,SAAQ;QACV,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,IAAI,cAAc,EAAE,CAAC;YACxC,cAAc,GAAG,KAAK,CAAA;YACtB,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;YACjD,CAAC;YACD,cAAc,GAAG,EAAE,CAAA;YACnB,SAAQ;QACV,CAAC;QAED,IAAI,cAAc,EAAE,CAAC;YACnB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,yBAAyB;SACjC,CAAA;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAA;IAEhD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,wCAAwC;SAChD,CAAA;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACxB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,CAAA;IAE1C,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAA;IACnC,CAAC;IAED,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAA;IAEhD,MAAM,MAAM,GAAW;QACrB,OAAO;QACP,QAAQ;KACT,CAAA;IAED,OAAO,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAI5C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;QACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;SACxE,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * Simplified schema for .sm file format
+ *
+ * Based on CONSTITUTION.md Section 4.2 (Flexible Format):
+ * - Markdown with any structure/sections (customizable)
+ * - Must contain at least one Mermaid diagram
+ */
+export declare const SmFileSchema: z.ZodObject<{
+    /** Full markdown content */
+    content: z.ZodString;
+    /** Extracted Mermaid diagrams */
+    diagrams: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    diagrams: string[];
+}, {
+    content: string;
+    diagrams: string[];
+}>;
+export type SmFile = z.infer<typeof SmFileSchema>;
+/**
+ * Schema for feature naming and slugification
+ */
+export declare const FeatureNameSchema: z.ZodObject<{
+    /** Original feature name as provided by user */
+    original: z.ZodString;
+    /** Slugified name for filename (kebab-case) */
+    slug: z.ZodString;
+    /** Filename with .sm extension */
+    filename: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    original: string;
+    slug: string;
+    filename: string;
+}, {
+    original: string;
+    slug: string;
+    filename: string;
+}>;
+export type FeatureName = z.infer<typeof FeatureNameSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY;IACvB,4BAA4B;;IAG5B,iCAAiC;;;;;;;;EAEjC,CAAA;AAEF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEjD;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,gDAAgD;;IAGhD,+CAA+C;;IAG/C,kCAAkC;;;;;;;;;;EAElC,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA"}

package/dist/schemas.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+/**
+ * Simplified schema for .sm file format
+ *
+ * Based on CONSTITUTION.md Section 4.2 (Flexible Format):
+ * - Markdown with any structure/sections (customizable)
+ * - Must contain at least one Mermaid diagram
+ */
+export const SmFileSchema = z.object({
+    /** Full markdown content */
+    content: z.string().min(1, 'Content cannot be empty'),
+    /** Extracted Mermaid diagrams */
+    diagrams: z.array(z.string()).min(1, 'Must have at least one Mermaid diagram')
+});
+/**
+ * Schema for feature naming and slugification
+ */
+export const FeatureNameSchema = z.object({
+    /** Original feature name as provided by user */
+    original: z.string().min(1),
+    /** Slugified name for filename (kebab-case) */
+    slug: z.string().min(1).regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'Must be kebab-case'),
+    /** Filename with .sm extension */
+    filename: z.string().min(1).endsWith('.sm')
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,4BAA4B;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,yBAAyB,CAAC;IAErD,iCAAiC;IACjC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,wCAAwC,CAAC;CAC/E,CAAC,CAAA;AAIF;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,gDAAgD;IAChD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE3B,+CAA+C;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,0BAA0B,EAAE,oBAAoB,CAAC;IAE/E,kCAAkC;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;CAC5C,CAAC,CAAA"}

package/dist/utils.d.ts

@@ -0,0 +1,50 @@
+import { FeatureName } from './schemas.js';
+/**
+ * Slugifies a feature name according to CONSTITUTION.md Section 4.2
+ *
+ * Rules:
+ * 1. Convert to lowercase
+ * 2. Replace spaces and special characters with hyphens (-)
+ * 3. Remove leading/trailing hyphens
+ * 4. Use descriptive, meaningful names
+ * 5. No timestamps in filename
+ *
+ * @param name Original feature name
+ * @returns Slugified name suitable for filename
+ */
+export declare function slugify(name: string): string;
+/**
+ * Creates a FeatureName object from a user-provided name
+ *
+ * @param originalName Feature name as provided by user
+ * @returns Validated FeatureName object
+ */
+export declare function createFeatureName(originalName: string): FeatureName;
+/**
+ * Validates if a string is a valid feature slug
+ *
+ * @param slug String to validate
+ * @returns True if valid kebab-case slug
+ */
+export declare function isValidSlug(slug: string): boolean;
+/**
+ * Extracts feature name from .sm filename
+ *
+ * @param filename .sm filename
+ * @returns Feature slug or null if invalid
+ */
+export declare function extractSlugFromFilename(filename: string): string | null;
+/**
+ * Gets the file path for a feature .sm file
+ *
+ * @param slug Feature slug
+ * @returns Relative path from project root
+ */
+export declare function getFeatureFilePath(slug: string): string;
+/**
+ * Gets the file path for system.sm
+ *
+ * @returns Relative path from project root
+ */
+export declare function getSystemFilePath(): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAA;AAE7D;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,CAWnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/utils.js

@@ -0,0 +1,76 @@
+import { FeatureNameSchema } from './schemas.js';
+/**
+ * Slugifies a feature name according to CONSTITUTION.md Section 4.2
+ *
+ * Rules:
+ * 1. Convert to lowercase
+ * 2. Replace spaces and special characters with hyphens (-)
+ * 3. Remove leading/trailing hyphens
+ * 4. Use descriptive, meaningful names
+ * 5. No timestamps in filename
+ *
+ * @param name Original feature name
+ * @returns Slugified name suitable for filename
+ */
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Creates a FeatureName object from a user-provided name
+ *
+ * @param originalName Feature name as provided by user
+ * @returns Validated FeatureName object
+ */
+export function createFeatureName(originalName) {
+    const slug = slugify(originalName);
+    const filename = `${slug}.sm`;
+    const featureName = {
+        original: originalName,
+        slug,
+        filename
+    };
+    return FeatureNameSchema.parse(featureName);
+}
+/**
+ * Validates if a string is a valid feature slug
+ *
+ * @param slug String to validate
+ * @returns True if valid kebab-case slug
+ */
+export function isValidSlug(slug) {
+    return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug);
+}
+/**
+ * Extracts feature name from .sm filename
+ *
+ * @param filename .sm filename
+ * @returns Feature slug or null if invalid
+ */
+export function extractSlugFromFilename(filename) {
+    if (!filename.endsWith('.sm')) {
+        return null;
+    }
+    const slug = filename.slice(0, -3); // Remove .sm extension
+    return isValidSlug(slug) ? slug : null;
+}
+/**
+ * Gets the file path for a feature .sm file
+ *
+ * @param slug Feature slug
+ * @returns Relative path from project root
+ */
+export function getFeatureFilePath(slug) {
+    return `.specmind/features/${slug}.sm`;
+}
+/**
+ * Gets the file path for system.sm
+ *
+ * @returns Relative path from project root
+ */
+export function getSystemFilePath() {
+    return '.specmind/system.sm';
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI;SACR,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAClC,MAAM,QAAQ,GAAG,GAAG,IAAI,KAAK,CAAA;IAE7B,MAAM,WAAW,GAAG;QAClB,QAAQ,EAAE,YAAY;QACtB,IAAI;QACJ,QAAQ;KACT,CAAA;IAED,OAAO,iBAAiB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA,CAAC,uBAAuB;IAC1D,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,sBAAsB,IAAI,KAAK,CAAA;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,qBAAqB,CAAA;AAC9B,CAAC"}

package/dist/writer.d.ts

@@ -0,0 +1,37 @@
+import { SmFile } from './schemas.js';
+/**
+ * Converts a SmFile object to markdown format
+ *
+ * Generates .sm file content according to CONSTITUTION.md Section 4.2 format:
+ * - Feature name as # heading
+ * - Overview section with markdown content
+ * - Requirements as bulleted list
+ * - Architecture with mermaid code block
+ * - Design decisions as markdown
+ * - Integration points as bulleted list
+ * - Notes as markdown
+ */
+export interface WriteResult {
+    success: boolean;
+    content?: string;
+    error?: string;
+}
+export declare function writeSmFile(smFile: SmFile): WriteResult;
+/**
+ * Formats a SmFile for display with metadata
+ *
+ * @param smFile SmFile object
+ * @returns Formatted content with metadata comments
+ */
+export declare function writeSmFileWithMetadata(smFile: SmFile): WriteResult;
+/**
+ * Validates that a SmFile can be written without data loss
+ *
+ * @param smFile SmFile to validate
+ * @returns Validation result
+ */
+export declare function validateSmFileForWriting(smFile: SmFile): {
+    valid: boolean;
+    issues: string[];
+};
+//# sourceMappingURL=writer.d.ts.map

package/dist/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA8EvD;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA2BnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAgC7F"}

package/dist/writer.js

@@ -0,0 +1,135 @@
+export function writeSmFile(smFile) {
+    try {
+        const sections = [];
+        // Feature name as main heading
+        sections.push(`# ${smFile.name}`);
+        sections.push('');
+        // Overview section
+        if (smFile.overview) {
+            sections.push('## Overview');
+            sections.push('');
+            sections.push(smFile.overview);
+            sections.push('');
+        }
+        // Requirements section
+        if (smFile.requirements.length > 0) {
+            sections.push('## Requirements');
+            sections.push('');
+            for (const requirement of smFile.requirements) {
+                sections.push(`- ${requirement}`);
+            }
+            sections.push('');
+        }
+        // Architecture section
+        if (smFile.architecture) {
+            sections.push('## Architecture');
+            sections.push('');
+            sections.push('```mermaid');
+            sections.push(smFile.architecture);
+            sections.push('```');
+            sections.push('');
+        }
+        // Design decisions section
+        if (smFile.designDecisions) {
+            sections.push('## Design Decisions');
+            sections.push('');
+            sections.push(smFile.designDecisions);
+            sections.push('');
+        }
+        // Integration points section
+        if (smFile.integrationPoints.length > 0) {
+            sections.push('## Integration Points');
+            sections.push('');
+            for (const point of smFile.integrationPoints) {
+                sections.push(`- ${point}`);
+            }
+            sections.push('');
+        }
+        // Notes section
+        if (smFile.notes) {
+            sections.push('## Notes');
+            sections.push('');
+            sections.push(smFile.notes);
+        }
+        // Remove trailing empty lines
+        while (sections.length > 0 && sections[sections.length - 1] === '') {
+            sections.pop();
+        }
+        const content = sections.join('\n');
+        return {
+            success: true,
+            content
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown writing error'
+        };
+    }
+}
+/**
+ * Formats a SmFile for display with metadata
+ *
+ * @param smFile SmFile object
+ * @returns Formatted content with metadata comments
+ */
+export function writeSmFileWithMetadata(smFile) {
+    try {
+        const result = writeSmFile(smFile);
+        if (!result.success || !result.content) {
+            return result;
+        }
+        const metadata = [
+            `<!-- Generated by SpecMind -->`,
+            `<!-- Type: ${smFile.type} -->`,
+            `<!-- Created: ${smFile.createdAt.toISOString()} -->`,
+            `<!-- Updated: ${smFile.updatedAt.toISOString()} -->`,
+            ''
+        ];
+        const content = metadata.join('\n') + result.content;
+        return {
+            success: true,
+            content
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown writing error'
+        };
+    }
+}
+/**
+ * Validates that a SmFile can be written without data loss
+ *
+ * @param smFile SmFile to validate
+ * @returns Validation result
+ */
+export function validateSmFileForWriting(smFile) {
+    const issues = [];
+    if (!smFile.name.trim()) {
+        issues.push('Feature name is required');
+    }
+    if (smFile.architecture && !smFile.architecture.trim()) {
+        issues.push('Architecture section is empty but present');
+    }
+    if (smFile.requirements.some(req => !req.trim())) {
+        issues.push('One or more requirements are empty');
+    }
+    if (smFile.integrationPoints.some(point => !point.trim())) {
+        issues.push('One or more integration points are empty');
+    }
+    // Check for potentially problematic content
+    if (smFile.name.includes('\n')) {
+        issues.push('Feature name contains newlines');
+    }
+    if (smFile.architecture.includes('```')) {
+        issues.push('Architecture contains code block markers (``` will be added automatically)');
+    }
+    return {
+        valid: issues.length === 0,
+        issues
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../src/writer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@specmind/format",
+  "version": "0.1.0",
+  "description": ".sm file format parser and writer",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "validate-fixtures": "node test-fixtures/validate-fixtures.mjs"
+  },
+  "keywords": [
+    "specmind",
+    "architecture",
+    "documentation",
+    "mermaid",
+    "sm-format",
+    "parser"
+  ],
+  "author": "SpecMind",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/specmind/specmind.git",
+    "directory": "packages/format"
+  },
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}