logicstamp-context 0.1.0

package/dist/utils/fsx.js

@@ -0,0 +1,181 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: fsx - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: []
+ *   hooks: []
+ *   components: []
+ *   functions: ["deleteSidecar","fileExists","findSidecarFiles","getRelativePath","getSidecarPath","globFiles","normalizeEntryId","readFileWithText","resolvePath"]
+ *   imports: ["glob","node:fs/promises","node:path"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:80b91273520265259cc8e40e (informational)
+ *   file: uif:f6ee3958ee861ee956f6b5c9
+ */
+/**
+ * File system utilities for glob patterns and path operations
+ */
+import { glob } from 'glob';
+import { readFile, unlink, stat } from 'node:fs/promises';
+import { resolve, relative, join, normalize, isAbsolute } from 'node:path';
+/**
+ * Find files matching glob patterns
+ */
+export async function globFiles(searchPath, extensions = '.tsx,.ts') {
+    const extArray = extensions.split(',').map((ext) => ext.trim());
+    // Build glob pattern
+    const patterns = extArray.map((ext) => {
+        if (ext.startsWith('.')) {
+            return `**/*${ext}`;
+        }
+        return `**/*.${ext}`;
+    });
+    const files = [];
+    for (const pattern of patterns) {
+        const matches = await glob(pattern, {
+            cwd: searchPath,
+            absolute: true,
+            ignore: [
+                '**/node_modules/**',
+                '**/dist/**',
+                '**/build/**',
+                '**/.next/**',
+                '**/coverage/**',
+                '**/*.test.ts',
+                '**/*.test.tsx',
+                '**/*.spec.ts',
+                '**/*.spec.tsx',
+            ],
+        });
+        files.push(...matches);
+    }
+    // Remove duplicates and sort
+    return [...new Set(files)].sort();
+}
+/**
+ * Read file and return path + content
+ */
+export async function readFileWithText(filePath) {
+    const text = await readFile(filePath, 'utf8');
+    return { path: filePath, text };
+}
+/**
+ * Find all sidecar files (*.uif.json) in a directory
+ */
+export async function findSidecarFiles(searchPath) {
+    return glob('**/*.uif.json', {
+        cwd: searchPath,
+        absolute: true,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/build/**'],
+    });
+}
+/**
+ * Delete a sidecar file
+ */
+export async function deleteSidecar(sidecarPath) {
+    try {
+        await unlink(sidecarPath);
+    }
+    catch (err) {
+        // Ignore if file doesn't exist
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+}
+/**
+ * Get relative path from base directory
+ */
+export function getRelativePath(from, to) {
+    return relative(from, to).replace(/\\/g, '/');
+}
+/**
+ * Resolve absolute path
+ */
+export function resolvePath(...paths) {
+    return resolve(...paths);
+}
+/**
+ * Check if file exists
+ */
+export async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get sidecar path for a source file
+ */
+export function getSidecarPath(sourcePath, outRoot) {
+    // If sourcePath is absolute, place sidecar next to source file
+    // This matches the behavior of writeSidecar()
+    if (isAbsolute(sourcePath)) {
+        return `${sourcePath}.uif.json`;
+    }
+    // Otherwise, resolve relative path from outRoot
+    return join(outRoot, `${sourcePath}.uif.json`);
+}
+/**
+ * Normalize a file path for cross-platform consistency
+ * This is the canonical path normalization used throughout the codebase.
+ * Rules:
+ * - Convert backslashes to forward slashes (POSIX-style)
+ * - Use Node's normalize() to resolve .. and . segments
+ * - On Windows: preserve drive letter but normalize case
+ * - Remove leading ./ if present
+ * - Result should match manifest keys exactly
+ *
+ * This function is the single source of truth for path normalization.
+ * All entryId fields in contracts and manifest keys use this normalization.
+ */
+export function normalizeEntryId(entryId) {
+    const normalized = normalize(entryId).replace(/\\/g, '/');
+    // On Windows, normalize drive letter to lowercase for consistency
+    // This ensures manifest keys match across different input formats
+    let result = normalized.replace(/^([A-Z]):/, (_, drive) => `${drive.toLowerCase()}:`);
+    // Remove leading ./ if present
+    result = result.replace(/^\.\//, '');
+    return result;
+}
+/**
+ * Get the folder path for a given file (parent directory)
+ * Returns normalized folder path
+ */
+export function getFolderPath(filePath) {
+    const normalized = normalizeEntryId(filePath);
+    const lastSlash = normalized.lastIndexOf('/');
+    if (lastSlash === -1)
+        return '.';
+    return normalized.substring(0, lastSlash);
+}
+/**
+ * Group files by their containing folder
+ * Returns a Map of folderPath -> array of file paths
+ */
+export function groupFilesByFolder(files, projectRoot) {
+    const normalizedRoot = normalizeEntryId(projectRoot);
+    const folderMap = new Map();
+    for (const file of files) {
+        const folderPath = getFolderPath(file);
+        if (!folderMap.has(folderPath)) {
+            folderMap.set(folderPath, []);
+        }
+        folderMap.get(folderPath).push(file);
+    }
+    return folderMap;
+}
+//# sourceMappingURL=fsx.js.map

package/dist/utils/fsx.js.map

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

package/dist/utils/gitignore.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Utilities for managing .gitignore files
+ */
+/**
+ * Patterns that should be added to .gitignore for LogicStamp context files
+ */
+export declare const LOGICSTAMP_GITIGNORE_PATTERNS: string[];
+/**
+ * Check if .gitignore exists in the given directory
+ */
+export declare function gitignoreExists(targetDir: string): Promise<boolean>;
+/**
+ * Read .gitignore content
+ */
+export declare function readGitignore(targetDir: string): Promise<string>;
+/**
+ * Check if a pattern exists in .gitignore content
+ */
+export declare function hasPattern(content: string, pattern: string): boolean;
+/**
+ * Check if .gitignore has LogicStamp patterns
+ */
+export declare function hasLogicStampPatterns(content: string): boolean;
+/**
+ * Add LogicStamp patterns to .gitignore content
+ */
+export declare function addLogicStampPatterns(content: string): string;
+/**
+ * Write content to .gitignore
+ */
+export declare function writeGitignore(targetDir: string, content: string): Promise<void>;
+/**
+ * Add LogicStamp patterns to .gitignore file
+ * Creates .gitignore if it doesn't exist
+ */
+export declare function ensureGitignorePatterns(targetDir: string): Promise<{
+    added: boolean;
+    created: boolean;
+}>;
+/**
+ * Smart .gitignore management with user prompt and config persistence
+ *
+ * Behavior:
+ * 1. If --skip-gitignore flag: do nothing
+ * 2. If config has preference: respect it
+ * 3. If patterns already exist: do nothing
+ * 4. If TTY (interactive): prompt user once, save preference
+ * 5. If non-TTY (CI): do nothing (don't auto-add)
+ *
+ * @param targetDir - Project root directory
+ * @param options - Options to control behavior
+ * @returns Result of the operation
+ */
+export declare function smartGitignoreSetup(targetDir: string, options?: {
+    skipGitignore?: boolean;
+}): Promise<{
+    added: boolean;
+    created: boolean;
+    prompted: boolean;
+    skipped: boolean;
+}>;
+//# sourceMappingURL=gitignore.d.ts.map

package/dist/utils/gitignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.d.ts","sourceRoot":"","sources":["../../src/utils/gitignore.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;GAEG;AACH,eAAO,MAAM,6BAA6B,UAOzC,CAAC;AAEF;;GAEG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOtE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ9D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0B7D;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtF;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAY9G;AA2BD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA6CpF"}

package/dist/utils/gitignore.js

@@ -0,0 +1,183 @@
+/**
+ * Utilities for managing .gitignore files
+ */
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readConfig, updateConfig } from './config.js';
+/**
+ * Patterns that should be added to .gitignore for LogicStamp context files
+ */
+export const LOGICSTAMP_GITIGNORE_PATTERNS = [
+    '# LogicStamp context files',
+    'context.json',
+    'context_*.json',
+    '*.uif.json',
+    'logicstamp.manifest.json',
+    '.logicstamp/',
+];
+/**
+ * Check if .gitignore exists in the given directory
+ */
+export async function gitignoreExists(targetDir) {
+    try {
+        await access(join(targetDir, '.gitignore'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read .gitignore content
+ */
+export async function readGitignore(targetDir) {
+    const gitignorePath = join(targetDir, '.gitignore');
+    try {
+        return await readFile(gitignorePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Check if a pattern exists in .gitignore content
+ */
+export function hasPattern(content, pattern) {
+    const lines = content.split('\n').map(line => line.trim());
+    return lines.includes(pattern);
+}
+/**
+ * Check if .gitignore has LogicStamp patterns
+ */
+export function hasLogicStampPatterns(content) {
+    // Check for the key patterns (ignore the comment line)
+    const patterns = LOGICSTAMP_GITIGNORE_PATTERNS.filter(p => !p.startsWith('#'));
+    // Check if at least the main patterns exist
+    // We consider it "has patterns" if context.json and context_*.json are present
+    return hasPattern(content, 'context.json') &&
+        (hasPattern(content, 'context_*.json') || hasPattern(content, 'context_main.json'));
+}
+/**
+ * Add LogicStamp patterns to .gitignore content
+ */
+export function addLogicStampPatterns(content) {
+    const lines = content.split('\n');
+    // Check which patterns are missing
+    const missingPatterns = LOGICSTAMP_GITIGNORE_PATTERNS.filter(pattern => {
+        if (pattern.startsWith('#'))
+            return false; // Always add the comment
+        return !hasPattern(content, pattern);
+    });
+    if (missingPatterns.length === 0 && hasPattern(content, '# LogicStamp context files')) {
+        return content; // All patterns already exist
+    }
+    // Add a blank line before the section if content exists and doesn't end with blank line
+    let newContent = content;
+    if (newContent.length > 0 && !newContent.endsWith('\n\n') && !newContent.endsWith('\n')) {
+        newContent += '\n';
+    }
+    if (newContent.length > 0 && !newContent.endsWith('\n\n')) {
+        newContent += '\n';
+    }
+    // Add all LogicStamp patterns as a group
+    newContent += LOGICSTAMP_GITIGNORE_PATTERNS.join('\n') + '\n';
+    return newContent;
+}
+/**
+ * Write content to .gitignore
+ */
+export async function writeGitignore(targetDir, content) {
+    const gitignorePath = join(targetDir, '.gitignore');
+    await writeFile(gitignorePath, content, 'utf-8');
+}
+/**
+ * Add LogicStamp patterns to .gitignore file
+ * Creates .gitignore if it doesn't exist
+ */
+export async function ensureGitignorePatterns(targetDir) {
+    const exists = await gitignoreExists(targetDir);
+    const content = await readGitignore(targetDir);
+    if (hasLogicStampPatterns(content)) {
+        return { added: false, created: false };
+    }
+    const newContent = addLogicStampPatterns(content);
+    await writeGitignore(targetDir, newContent);
+    return { added: true, created: !exists };
+}
+/**
+ * Check if running in interactive TTY
+ */
+function isTTY() {
+    return process.stdout.isTTY === true && process.stdin.isTTY === true;
+}
+/**
+ * Prompt user for Y/N input (only in TTY mode)
+ */
+async function promptYesNo(question) {
+    const { createInterface } = await import('node:readline');
+    const readline = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        readline.question(question, (answer) => {
+            readline.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes' || answer === '');
+        });
+    });
+}
+/**
+ * Smart .gitignore management with user prompt and config persistence
+ *
+ * Behavior:
+ * 1. If --skip-gitignore flag: do nothing
+ * 2. If config has preference: respect it
+ * 3. If patterns already exist: do nothing
+ * 4. If TTY (interactive): prompt user once, save preference
+ * 5. If non-TTY (CI): do nothing (don't auto-add)
+ *
+ * @param targetDir - Project root directory
+ * @param options - Options to control behavior
+ * @returns Result of the operation
+ */
+export async function smartGitignoreSetup(targetDir, options = {}) {
+    // If --skip-gitignore flag is set, do nothing
+    if (options.skipGitignore) {
+        return { added: false, created: false, prompted: false, skipped: true };
+    }
+    // Check if patterns already exist
+    const content = await readGitignore(targetDir);
+    if (hasLogicStampPatterns(content)) {
+        return { added: false, created: false, prompted: false, skipped: false };
+    }
+    // Check config for saved preference
+    const config = await readConfig(targetDir);
+    // If user previously chose to skip, respect that
+    if (config.gitignorePreference === 'skipped') {
+        return { added: false, created: false, prompted: false, skipped: true };
+    }
+    // If user previously chose to add, do it without prompting
+    if (config.gitignorePreference === 'added') {
+        const result = await ensureGitignorePatterns(targetDir);
+        return { ...result, prompted: false, skipped: false };
+    }
+    // No preference saved yet - prompt if interactive
+    if (isTTY()) {
+        console.log('\n💡 LogicStamp generates large context files that are usually not committed.\n');
+        const shouldAdd = await promptYesNo('Add recommended patterns to .gitignore? [Y/n] ');
+        if (shouldAdd) {
+            // User said yes - add patterns and save preference
+            await updateConfig(targetDir, { gitignorePreference: 'added' });
+            const result = await ensureGitignorePatterns(targetDir);
+            return { ...result, prompted: true, skipped: false };
+        }
+        else {
+            // User said no - save preference to never ask again
+            await updateConfig(targetDir, { gitignorePreference: 'skipped' });
+            return { added: false, created: false, prompted: true, skipped: true };
+        }
+    }
+    // Non-interactive (CI) - don't auto-add, don't prompt
+    return { added: false, created: false, prompted: false, skipped: true };
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/utils/gitignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignore.js","sourceRoot":"","sources":["../../src/utils/gitignore.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvD;;GAEG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,4BAA4B;IAC5B,cAAc;IACd,gBAAgB;IAChB,YAAY;IACZ,0BAA0B;IAC1B,cAAc;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAiB;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAAiB;IACnD,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAe;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,uDAAuD;IACvD,MAAM,QAAQ,GAAG,6BAA6B,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAE/E,4CAA4C;IAC5C,+EAA+E;IAC/E,OAAO,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC;QACnC,CAAC,UAAU,CAAC,OAAO,EAAE,gBAAgB,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAElC,mCAAmC;IACnC,MAAM,eAAe,GAAG,6BAA6B,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE;QACrE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,yBAAyB;QACpE,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,4BAA4B,CAAC,EAAE,CAAC;QACtF,OAAO,OAAO,CAAC,CAAC,6BAA6B;IAC/C,CAAC;IAED,wFAAwF;IACxF,IAAI,UAAU,GAAG,OAAO,CAAC;IACzB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxF,UAAU,IAAI,IAAI,CAAC;IACrB,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1D,UAAU,IAAI,IAAI,CAAC;IACrB,CAAC;IAED,yCAAyC;IACzC,UAAU,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE9D,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAAiB,EAAE,OAAe;IACrE,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,SAAiB;IAC7D,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;IAE/C,IAAI,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,cAAc,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAE5C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED;;GAEG;AACH,SAAS,KAAK;IACZ,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,WAAW,CAAC,QAAgB;IACzC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC;QAC/B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE;YACrC,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,KAAK,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC;QAC3F,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EACjB,UAAuC,EAAE;IAEzC,8CAA8C;IAC9C,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1E,CAAC;IAED,kCAAkC;IAClC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,qBAAqB,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC3E,CAAC;IAED,oCAAoC;IACpC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,CAAC;IAE3C,iDAAiD;IACjD,IAAI,MAAM,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1E,CAAC;IAED,2DAA2D;IAC3D,IAAI,MAAM,CAAC,mBAAmB,KAAK,OAAO,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,SAAS,CAAC,CAAC;QACxD,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxD,CAAC;IAED,kDAAkD;IAClD,IAAI,KAAK,EAAE,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;QAC/F,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,gDAAgD,CAAC,CAAC;QAEtF,IAAI,SAAS,EAAE,CAAC;YACd,mDAAmD;YACnD,MAAM,YAAY,CAAC,SAAS,EAAE,EAAE,mBAAmB,EAAE,OAAO,EAAE,CAAC,CAAC;YAChE,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,SAAS,CAAC,CAAC;YACxD,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACvD,CAAC;aAAM,CAAC;YACN,oDAAoD;YACpD,MAAM,YAAY,CAAC,SAAS,EAAE,EAAE,mBAAmB,EAAE,SAAS,EAAE,CAAC,CAAC;YAClE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACzE,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC1E,CAAC"}

package/dist/utils/hash.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: hash - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: ["SCHEMA_VERSION"]
+ *   hooks: []
+ *   components: []
+ *   functions: ["bundleHash","fileHash","hashesEqual","isValidHash","semanticHashFromAst","sha256Hex","signatureHash","sortObject","stableStringify","structureHash"]
+ *   imports: ["../core/astParser.js","../types/UIFContract.js","node:crypto"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:9c632ee89c97f0b44ce6ae5c (informational)
+ *   file: uif:1f0fa0e2c8958d7fc1696036
+ */
+import type { AstExtract } from '../core/astParser.js';
+import type { LogicSignature, ComponentVersion } from '../types/UIFContract.js';
+/**
+ * Generate a hash from raw file content
+ * Strips the @uif header block before hashing to prevent self-referential churn
+ */
+export declare function fileHash(content: string): string;
+/**
+ * Generate a hash from component structure (variables, hooks, components, functions)
+ * This changes only when structural composition changes
+ */
+export declare function structureHash(ast: AstExtract): string;
+export declare function structureHash(version: ComponentVersion): string;
+/**
+ * Generate a hash from logic signature (props, events, state)
+ * This changes only when the component's API contract changes
+ */
+export declare function signatureHash(signature: LogicSignature): string;
+/**
+ * Generate a semantic hash from AST structure and logic signature
+ * This hash only changes when the component's structural logic changes,
+ * not when comments, formatting, or implementation details change.
+ *
+ * semanticHash = hash(structureHash + signatureHash + schemaVersion)
+ */
+export declare function semanticHashFromAst(ast: AstExtract, signature: LogicSignature): string;
+/**
+ * Compute bundle hash from nodes
+ * Input: ordered array of {entryId, semanticHash} plus depth and schemaVersion
+ * This provides a stable cache key for LLM context bundles
+ */
+export declare function bundleHash(nodes: Array<{
+    entryId: string;
+    semanticHash: string;
+}>, depth: number, schemaVersion?: string): string;
+/**
+ * Stable stringify with sorted keys and arrays
+ * Ensures deterministic JSON output for hashing
+ */
+export declare function stableStringify(obj: unknown): string;
+/**
+ * Verify if a hash matches the expected format
+ */
+export declare function isValidHash(hash: string): boolean;
+/**
+ * Compare two hashes for equality
+ */
+export declare function hashesEqual(hash1: string, hash2: string): boolean;
+//# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;AACvD,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAAC;AAYjE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAQ/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,GAAG,MAAM,CAkBtF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,EACvD,KAAK,EAAE,MAAM,EACb,aAAa,SAAQ,GACpB,MAAM,CAeR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAiBpD;AAwBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/utils/hash.js

@@ -0,0 +1,159 @@
+/**
+ * @uif Contract 0.3
+ *
+ * Description: hash - Presentational component
+ *
+ * Version (Component Composition):
+ *   variables: ["SCHEMA_VERSION"]
+ *   hooks: []
+ *   components: []
+ *   functions: ["bundleHash","fileHash","hashesEqual","isValidHash","semanticHashFromAst","sha256Hex","signatureHash","sortObject","stableStringify","structureHash"]
+ *   imports: ["../core/astParser.js","../types/UIFContract.js","node:crypto"]
+ *
+ * Logic Signature:
+ *   props: {}
+ *   events: {}
+ *   state: {}
+ *
+ * Predictions:
+ *   (none)
+ *
+ * Hashes (informational only - authoritative values in .uif.json):
+ *   semantic: uif:9c632ee89c97f0b44ce6ae5c (informational)
+ *   file: uif:1f0fa0e2c8958d7fc1696036
+ */
+/**
+ * Hash utilities for content and semantic hashing
+ */
+import { createHash } from 'node:crypto';
+const SCHEMA_VERSION = '0.3';
+/**
+ * Generate a hash from raw file content
+ * Strips the @uif header block before hashing to prevent self-referential churn
+ */
+export function fileHash(content) {
+    // Strip @uif header block to prevent self-referential changes
+    const stripped = content.replace(/\/\*\*[\s\S]*?@uif[\s\S]*?\*\/\n*/m, '');
+    // Normalize line endings for cross-platform consistency
+    const normalized = stripped.replace(/\r\n/g, '\n');
+    const hash = createHash('sha256').update(normalized, 'utf8').digest('hex');
+    return `uif:${hash.slice(0, 24)}`;
+}
+export function structureHash(astOrVersion) {
+    const payload = {
+        variables: [...(astOrVersion.variables || [])].sort(),
+        hooks: [...(astOrVersion.hooks || [])].sort(),
+        components: [...(astOrVersion.components || [])].sort(),
+        functions: [...(astOrVersion.functions || [])].sort(),
+    };
+    return sha256Hex(stableStringify(payload));
+}
+/**
+ * Generate a hash from logic signature (props, events, state)
+ * This changes only when the component's API contract changes
+ */
+export function signatureHash(signature) {
+    const payload = {
+        props: sortObject(signature.props),
+        emits: sortObject(signature.emits),
+        state: signature.state ? sortObject(signature.state) : undefined,
+    };
+    return sha256Hex(stableStringify(payload));
+}
+/**
+ * Generate a semantic hash from AST structure and logic signature
+ * This hash only changes when the component's structural logic changes,
+ * not when comments, formatting, or implementation details change.
+ *
+ * semanticHash = hash(structureHash + signatureHash + schemaVersion)
+ */
+export function semanticHashFromAst(ast, signature) {
+    // Combine structure and signature hashes with schema version
+    const payload = {
+        schemaVersion: SCHEMA_VERSION,
+        structure: {
+            variables: [...ast.variables].sort(),
+            hooks: [...ast.hooks].sort(),
+            components: [...ast.components].sort(),
+            functions: [...ast.functions].sort(),
+        },
+        signature: {
+            props: sortObject(signature.props),
+            emits: sortObject(signature.emits),
+            state: signature.state ? sortObject(signature.state) : undefined,
+        },
+    };
+    return sha256Hex(stableStringify(payload));
+}
+/**
+ * Compute bundle hash from nodes
+ * Input: ordered array of {entryId, semanticHash} plus depth and schemaVersion
+ * This provides a stable cache key for LLM context bundles
+ */
+export function bundleHash(nodes, depth, schemaVersion = '0.1') {
+    // Sort nodes by entryId for determinism
+    const ordered = [...nodes].sort((a, b) => a.entryId.localeCompare(b.entryId));
+    const payload = {
+        schemaVersion,
+        depth,
+        nodes: ordered.map(n => ({ entryId: n.entryId, semanticHash: n.semanticHash })),
+    };
+    const hash = createHash('sha256')
+        .update(stableStringify(payload), 'utf8')
+        .digest('hex');
+    return `uifb:${hash.slice(0, 24)}`;
+}
+/**
+ * Stable stringify with sorted keys and arrays
+ * Ensures deterministic JSON output for hashing
+ */
+export function stableStringify(obj) {
+    return JSON.stringify(obj, (k, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            // Sort object keys
+            return Object.keys(v)
+                .sort()
+                .reduce((o, key) => {
+                o[key] = v[key];
+                return o;
+            }, {});
+        }
+        if (Array.isArray(v)) {
+            // Sort arrays for stability
+            return [...v].sort();
+        }
+        return v;
+    });
+}
+/**
+ * Sort object keys for stable hashing
+ */
+function sortObject(obj) {
+    const sorted = Object.keys(obj)
+        .sort()
+        .reduce((acc, key) => {
+        acc[key] = obj[key];
+        return acc;
+    }, {});
+    return sorted;
+}
+/**
+ * Generate SHA256 hash with uif: prefix
+ */
+function sha256Hex(input) {
+    const hash = createHash('sha256').update(input, 'utf8').digest('hex');
+    return `uif:${hash.slice(0, 24)}`;
+}
+/**
+ * Verify if a hash matches the expected format
+ */
+export function isValidHash(hash) {
+    return /^uif:[a-f0-9]{24}$/.test(hash);
+}
+/**
+ * Compare two hashes for equality
+ */
+export function hashesEqual(hash1, hash2) {
+    return hash1 === hash2;
+}
+//# sourceMappingURL=hash.js.map