@pure-ds/core 0.3.0

package/packages/pds-cli/bin/postinstall.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * NPM postinstall script for @pure-ds/core
+ * Automatically copies PDS assets to the consuming app's web root
+ */
+
+import { readFile, writeFile, mkdir, copyFile, readdir, stat, access, unlink } from 'fs/promises';
+import { readFileSync } from 'fs';
+import { createHash } from 'crypto';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '../../../');
+const isWin = process.platform === 'win32';
+const normalizePath = (p) => {
+  if (!p) return '';
+  const resolved = path.resolve(p).replace(/[\\/]+$/, '');
+  return isWin ? resolved.toLowerCase() : resolved;
+};
+
+/**
+ * Check if we're installing within the @pure-ds/core repo itself (not a consumer)
+ */
+function isInstallingWithinPureDsRepo() {
+  try {
+    const cwd = process.cwd();
+    const initCwd = process.env.INIT_CWD || cwd;
+    
+    // Check if the INIT_CWD has package.json with name "@pure-ds/core"
+    // This is more reliable than path comparison since repoRoot
+    // points to node_modules/@pure-ds/core when installed as a dependency
+    try {
+      const pkgPath = path.join(initCwd, 'package.json');
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      return pkg.name === '@pure-ds/core' || pkg.name === 'pure-ds';
+    } catch {
+      return false;
+    }
+  } catch (err) {
+    console.log('⚠️  Error checking repo location:', err.message);
+    return false;
+  }
+}
+
+function isNpmLinkInvocation() {
+  const truthy = (value) => {
+    if (value === undefined || value === null) return false;
+    const normalized = String(value).toLowerCase();
+    return normalized === 'true' || normalized === '1';
+  };
+
+  if (truthy(process.env.npm_config_link)) return true;
+  if ((process.env.npm_command || '').toLowerCase() === 'link') return true;
+
+  try {
+    const argvRaw = process.env.npm_config_argv;
+    if (!argvRaw) return false;
+    const argv = JSON.parse(argvRaw);
+    const orig = argv && (argv.original || argv.cooked || []);
+    if (!Array.isArray(orig)) return false;
+    return orig.includes('link');
+  } catch {
+    return false;
+  }
+}
+
+function isLinkedPackagePath(p) {
+  return !/[\\/]+node_modules[\\/]+/i.test(p);
+}
+
+function isGlobalInstall() {
+  const value = process.env.npm_config_global;
+  if (!value) return false;
+  const normalized = String(value).toLowerCase();
+  return normalized === 'true' || normalized === '1';
+}
+
+/**
+ * Find the consumer app root (directory containing the consumer's package.json)
+ * Prefer INIT_CWD (npm sets this to the original cwd) and fallback by walking up from the package dir
+ */
+async function findConsumerRoot() {
+  const tryPaths = [];
+  if (process.env.INIT_CWD) tryPaths.push(process.env.INIT_CWD);
+  // Walk up from the package dir until we exit node_modules
+  let dir = repoRoot;
+  while (dir && path.basename(dir) !== path.dirname(dir)) {
+    if (path.basename(dir) === 'node_modules') {
+      const candidate = path.dirname(dir);
+      tryPaths.push(candidate);
+      break;
+    }
+    dir = path.dirname(dir);
+  }
+
+  for (const p of tryPaths) {
+    try {
+      const pkgPath = path.join(p, 'package.json');
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+      if (pkg && pkg.name && pkg.name !== 'pure-ds') {
+        return p;
+      }
+    } catch {}
+  }
+
+  // Final fallback: INIT_CWD or current working dir
+  return process.env.INIT_CWD || process.cwd();
+}
+
+/**
+ * Ensure consumer package.json contains a handy export script
+ */
+async function ensureExportScript(consumerRoot) {
+  try {
+    const consumerPkgPath = path.join(consumerRoot, 'package.json');
+    const consumerPkgRaw = await readFile(consumerPkgPath, 'utf8');
+    const consumerPkg = JSON.parse(consumerPkgRaw);
+
+    consumerPkg.scripts = consumerPkg.scripts || {};
+
+  const desiredScriptName = 'pds:export';
+  const desiredScriptCmd = 'pds-export';
+
+    if (!consumerPkg.scripts[desiredScriptName]) {
+      consumerPkg.scripts[desiredScriptName] = desiredScriptCmd;
+      await writeFile(consumerPkgPath, JSON.stringify(consumerPkg, null, 2) + '\n');
+      console.log(`🧩 Added "${desiredScriptName}" script to consumer package.json`);
+    } else {
+      console.log(`🔧 Script "${desiredScriptName}" already present in consumer package.json`);
+    }
+  } catch (e) {
+    console.warn('⚠️  Could not ensure pds:export script in consumer package.json:', e.message);
+  }
+}
+
+/**
+ * Discover the web root directory using common patterns
+ */
+async function discoverWebRoot(baseDir) {
+  const cwd = baseDir || process.env.INIT_CWD || process.cwd();
+  
+  // Common web root patterns (in order of preference)
+  const candidates = [
+    'public',
+    'static',
+    'dist',
+    'build',
+    'www',
+    'web',
+    'assets',
+    'src/assets',
+    'app/public',
+    '.'  // fallback to current directory
+  ];
+  
+  console.log('🔍 Discovering web root directory...');
+  
+  for (const candidate of candidates) {
+    const fullPath = path.resolve(cwd, candidate);
+    try {
+      await access(fullPath);
+      const stats = await stat(fullPath);
+      if (stats.isDirectory()) {
+        console.log(`   ✅ Found: ${candidate}/`);
+        return { path: fullPath, relative: candidate };
+      }
+    } catch (e) {
+      // Directory doesn't exist, continue
+    }
+  }
+  
+  // Check package.json for hints
+  try {
+    const packagePath = path.join(cwd, 'package.json');
+    const pkg = JSON.parse(await readFile(packagePath, 'utf8'));
+    
+    // Look for common build/output directories in scripts
+    const scripts = pkg.scripts || {};
+    const scriptText = JSON.stringify(scripts);
+    
+    if (scriptText.includes('--outdir dist') || scriptText.includes('dist/')) {
+      const distPath = path.resolve(cwd, 'dist');
+      console.log(`   💡 Found "dist" in scripts, using: dist/`);
+      return { path: distPath, relative: 'dist' };
+    }
+    
+    if (scriptText.includes('--outdir build') || scriptText.includes('build/')) {
+      const buildPath = path.resolve(cwd, 'build');
+      console.log(`   💡 Found "build" in scripts, using: build/`);
+      return { path: buildPath, relative: 'build' };
+    }
+    
+    // Check for common framework configs
+    if (pkg.dependencies?.['next'] || pkg.devDependencies?.['next']) {
+      const publicPath = path.resolve(cwd, 'public');
+      console.log(`   🔧 Next.js detected, using: public/`);
+      return { path: publicPath, relative: 'public' };
+    }
+    
+    if (pkg.dependencies?.['vite'] || pkg.devDependencies?.['vite']) {
+      const publicPath = path.resolve(cwd, 'public');
+      console.log(`   ⚡ Vite detected, using: public/`);
+      return { path: publicPath, relative: 'public' };
+    }
+    
+  } catch (e) {
+    // No package.json or parsing failed
+  }
+  
+  // Ultimate fallback: create public directory
+  const fallbackPath = path.resolve(cwd, 'public');
+  console.log(`   📁 Creating fallback: public/`);
+  await mkdir(fallbackPath, { recursive: true });
+  return { path: fallbackPath, relative: 'public' };
+}
+
+/**
+ * Copy PDS assets to the discovered web root
+ */
+async function copyPdsAssets() {
+  console.log('📦 PDS postinstall running (no automatic component copy)…');
+  try {
+    const normalizedRepoRoot = normalizePath(repoRoot);
+    const normalizedInitCwd = normalizePath(process.env.INIT_CWD || process.cwd());
+
+    if (isLinkedPackagePath(normalizedRepoRoot)) {
+      console.log('🛑 Skipping PDS postinstall (detected symlinked package path).');
+      return;
+    }
+
+    if (normalizedInitCwd === normalizedRepoRoot) {
+      console.log('🛑 Skipping PDS postinstall (working inside pure-ds repository root).');
+      return;
+    }
+
+    if (isNpmLinkInvocation()) {
+      console.log('🛑 Skipping PDS postinstall (detected npm link invocation).');
+      return;
+    }
+
+    if (isGlobalInstall()) {
+      console.log('🛑 Skipping PDS postinstall (global install detected).');
+      return;
+    }
+
+    const consumerRoot = await findConsumerRoot();
+    console.log('🧪 Consumer root:', consumerRoot);
+
+    // Allow opting out explicitly (useful for local dev / linking)
+    if (
+      process.env.PDS_SKIP_POSTINSTALL === '1' ||
+      process.env.PDS_SKIP_POSTINSTALL === 'true' ||
+      process.env.npm_config_pds_skip_postinstall === 'true'
+    ) {
+      console.log('⏭️  Skipping PDS postinstall (PDS_SKIP_POSTINSTALL set).');
+      return;
+    }
+
+    // If running inside the package repo itself (e.g., during `npm link`), skip
+    const inRepo = normalizePath(consumerRoot) === normalizePath(repoRoot);
+    const withinPureDs = isInstallingWithinPureDsRepo();
+
+    if (inRepo || withinPureDs) {
+      let reason = 'installing within pure-ds repository';
+      if (inRepo) {
+        reason = 'inside the package repo';
+      } else if (withinPureDs) {
+        reason = 'installing within pure-ds repository';
+      }
+      console.log(`🛑 Skipping PDS postinstall (${reason}).`);
+      return;
+    }
+    
+  console.log('📦 Proceeding with asset copying...');
+
+    // Proactively add export & build-icons scripts to consumer package.json (still helpful)
+    await ensureExportScript(consumerRoot);
+    try {
+      const consumerPkgPath = path.join(consumerRoot, 'package.json');
+      const pkgRaw = await readFile(consumerPkgPath, 'utf8');
+      const pkgJson = JSON.parse(pkgRaw);
+      pkgJson.scripts = pkgJson.scripts || {};
+      const buildIconsName = 'pds:build-icons';
+      const buildIconsCmd = 'pds-build-icons';
+      if (!pkgJson.scripts[buildIconsName]) {
+        pkgJson.scripts[buildIconsName] = buildIconsCmd;
+        await writeFile(consumerPkgPath, JSON.stringify(pkgJson, null, 2) + '\n');
+        console.log(`🧩 Added "${buildIconsName}" script to consumer package.json`);
+      }
+    } catch (e) {
+      console.warn('⚠️  Could not ensure pds:build-icons script in consumer package.json:', e?.message || e);
+    }
+
+    // NEW BEHAVIOR: We no longer copy web components automatically to /auto-define/.
+    // Reason: static export (pds:export) is now the single source of truth for placing
+    // components under [static.root]/components/ (see pds.config.js). This reduces
+    // side-effects during npm install and avoids stale/legacy /auto-define/ layout.
+    console.log('🚫 Skipping legacy auto-copy of components to ./public/auto-define/.');
+    
+    // Auto-run pds:export by default (can be disabled with PDS_SKIP_EXPORT)
+    if (
+      process.env.PDS_SKIP_EXPORT === '1' ||
+      process.env.PDS_SKIP_EXPORT === 'true' ||
+      process.env.npm_config_pds_skip_export === 'true'
+    ) {
+      console.log('⏭️  Skipping pds:export (PDS_SKIP_EXPORT set)');
+      console.log('📦 To generate static assets run:   npm run pds:export');
+    } else {
+      console.log('🚀 Running pds:export automatically...');
+      const staticModuleUrl = pathToFileURL(path.join(__dirname, 'pds-static.js')).href;
+      const previousEnv = {
+        PDS_POSTINSTALL: process.env.PDS_POSTINSTALL,
+        PDS_LOG_STREAM: process.env.PDS_LOG_STREAM,
+        PDS_CONSUMER_ROOT: process.env.PDS_CONSUMER_ROOT,
+      };
+
+      try {
+        process.env.PDS_POSTINSTALL = '1';
+        process.env.PDS_LOG_STREAM = 'stderr';
+        process.env.PDS_CONSUMER_ROOT = consumerRoot;
+
+        const { runPdsStatic } = await import(staticModuleUrl);
+        await runPdsStatic({ cwd: consumerRoot });
+      } catch (e) {
+        console.error('❌ Auto-export failed:', e?.message || e);
+        console.log('💡 You can run it manually: npm run pds:export');
+      } finally {
+        if (previousEnv.PDS_POSTINSTALL === undefined) {
+          delete process.env.PDS_POSTINSTALL;
+        } else {
+          process.env.PDS_POSTINSTALL = previousEnv.PDS_POSTINSTALL;
+        }
+
+        if (previousEnv.PDS_LOG_STREAM === undefined) {
+          delete process.env.PDS_LOG_STREAM;
+        } else {
+          process.env.PDS_LOG_STREAM = previousEnv.PDS_LOG_STREAM;
+        }
+
+        if (previousEnv.PDS_CONSUMER_ROOT === undefined) {
+          delete process.env.PDS_CONSUMER_ROOT;
+        } else {
+          process.env.PDS_CONSUMER_ROOT = previousEnv.PDS_CONSUMER_ROOT;
+        }
+      }
+    }
+    
+    console.log('🎨 (Optional) Build custom icons:   npm run pds:build-icons');
+    console.log('ℹ️  If you previously relied on /auto-define/, update references to the new static output.');
+
+    // Tracking file for diagnostics (minimal)
+    try {
+      const webRoot = await discoverWebRoot(consumerRoot);
+      const trackingFile = path.join(webRoot.path, '.pds-install.json');
+      const tracking = {
+        version: '0.1.0',
+        installDate: new Date().toISOString(),
+        webRoot: webRoot.relative,
+        componentsCopied: 0,
+        mode: 'no-copy-postinstall',
+      };
+      await writeFile(trackingFile, JSON.stringify(tracking, null, 2));
+    } catch (e) {
+      console.warn('⚠️  Could not write tracking file:', e?.message || e);
+    }
+  } catch (error) {
+    console.error('❌ PDS postinstall failed (non-fatal):', error.message);
+    console.log('💡 Static export still available via: npm run pds:export');
+    process.exitCode = 1;
+  }
+}
+
+// Only run when called directly (not when imported)
+if (process.argv[1].endsWith('postinstall.js')) {
+  copyPdsAssets().catch(console.error);
+}
+
+export { copyPdsAssets, discoverWebRoot };

package/packages/pds-cli/bin/sync-assets.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, mkdir, copyFile, readdir, stat } from 'fs/promises';
+import { createHash } from 'crypto';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Find the PDS package root, whether we're running from the package itself or from node_modules
+async function findPdsRoot() {
+  const currentDir = __dirname;
+  
+  // If running from the package itself (development)
+  if (currentDir.includes('packages/pds-cli/bin')) {
+    return path.resolve(currentDir, '../../../');
+  }
+  
+  // If running from node_modules (consumer app)
+  // The structure would be: node_modules/@pure-ds/core/packages/pds-cli/bin
+  if (currentDir.includes('node_modules')) {
+    let dir = currentDir;
+    while (dir !== path.dirname(dir)) {
+      // Support both legacy scoped name and new unscoped name
+      // node_modules/@pure-ds/core/... OR node_modules/pure-ds/...
+      const base = path.basename(dir);
+      const parent = path.basename(path.dirname(dir));
+      if ((base === 'core' && parent === '@pure-ds') || base === 'pure-ds') {
+        return dir;
+      }
+      dir = path.dirname(dir);
+    }
+  }
+  
+  // Fallback - navigate up to find package.json with correct name
+  let dir = currentDir;
+  while (dir !== path.dirname(dir)) {
+    try {
+      const packagePath = path.join(dir, 'package.json');
+      const pkg = JSON.parse(await readFile(packagePath, 'utf8'));
+      if (pkg.name === '@pure-ds/core' || pkg.name === 'pure-ds') {
+        return dir;
+      }
+    } catch (e) {
+      // Continue searching
+    }
+    dir = path.dirname(dir);
+  }
+  
+  throw new Error('Could not find PDS package root');
+}
+
+/**
+ * Sync PDS assets to consuming app's public directory
+ * Copies:
+ * - public/pds/components/* (or legacy public/auto-define/*) -> <targetDir>/components/*
+ * - (icons no longer synced; static export focuses on components and styles)
+ * 
+ * Usage: node node_modules/pure-ds/packages/pds-cli/bin/sync-assets.js [options]
+ * Options:
+ *   --target=<path>  Target directory (default: ./public)
+ *   --force          Overwrite user-modified files
+ *   --dry-run        Show what would be synced without copying
+ *   --verbose, -v    Show detailed sync information
+ */
+
+async function syncAssets(options = {}) {
+  const {
+  targetDir = './public',
+    force = false,
+    dryRun = false,
+    verbose = false
+  } = options;
+
+  console.log('🔄 Syncing PDS assets...');
+  
+  // Find PDS package root
+  const pdsRoot = await findPdsRoot();
+  
+  // Prefer new packaged location; fall back to legacy paths
+  let autoDefineSource = path.join(pdsRoot, 'public/assets/pds/components');
+  try {
+    await stat(autoDefineSource);
+  } catch {
+    try {
+      autoDefineSource = path.join(pdsRoot, 'public/pds/components');
+      await stat(autoDefineSource);
+    } catch {
+      autoDefineSource = path.join(pdsRoot, 'public/auto-define');
+    }
+  }
+  
+  // Target directories
+  const autoDefineTarget = path.join(process.cwd(), targetDir, 'components');
+  
+  // Load or create asset tracking file
+  const trackingFile = path.join(process.cwd(), '.pds-assets.json');
+  let tracking = {};
+  
+  try {
+    const trackingData = await readFile(trackingFile, 'utf-8');
+    tracking = JSON.parse(trackingData);
+  } catch (e) {
+    // First run or corrupted file
+    tracking = {
+      version: '0.1.0',
+      lastSync: null,
+      checksums: {},
+      userModified: {}
+    };
+  }
+  
+  const newChecksums = {};
+  const conflicts = [];
+  const synced = [];
+  
+  // Helper to calculate file hash
+  const getFileHash = async (filePath) => {
+    try {
+      const content = await readFile(filePath);
+      return createHash('sha256').update(content).digest('hex');
+    } catch (e) {
+      return null;
+    }
+  };
+  
+  // Helper to sync a single file
+  const syncFile = async (sourcePath, targetPath, relativeKey) => {
+    try {
+      // Ensure target directory exists
+      await mkdir(path.dirname(targetPath), { recursive: true });
+      
+      const sourceHash = await getFileHash(sourcePath);
+      const targetHash = await getFileHash(targetPath);
+      const knownHash = tracking.checksums[relativeKey];
+      
+      newChecksums[relativeKey] = sourceHash;
+      
+      // Conflict detection
+      if (targetHash && targetHash !== sourceHash && targetHash !== knownHash) {
+        conflicts.push({
+          file: relativeKey,
+          path: targetPath,
+          reason: 'User modified file conflicts with PDS update'
+        });
+        
+        if (!force) {
+          if (verbose) {
+            console.log(`⚠️  Skipping ${relativeKey} (user modified)`);
+          }
+          tracking.userModified[relativeKey] = targetHash;
+          return;
+        }
+      }
+      
+      // Copy file if needed
+      if (!targetHash || targetHash !== sourceHash || force) {
+        if (!dryRun) {
+          await copyFile(sourcePath, targetPath);
+        }
+        synced.push(relativeKey);
+        
+        if (verbose) {
+          console.log(`📁 ${dryRun ? '[DRY RUN] ' : ''}Synced ${relativeKey}`);
+        }
+      }
+    } catch (e) {
+      console.warn(`⚠️  Could not sync ${relativeKey}:`, e.message);
+    }
+  };
+
+  // Helper to sync a directory
+  const syncDirectory = async (sourceDir, targetDir, prefix = '') => {
+    try {
+      await mkdir(targetDir, { recursive: true });
+      const files = await readdir(sourceDir);
+      
+      for (const file of files) {
+        const sourcePath = path.join(sourceDir, file);
+        const targetPath = path.join(targetDir, file);
+        const relativeKey = `${prefix}${file}`;
+        
+        const sourceStat = await stat(sourcePath);
+        if (sourceStat.isDirectory()) {
+          await syncDirectory(sourcePath, targetPath, `${relativeKey}/`);
+          continue;
+        }
+        
+        await syncFile(sourcePath, targetPath, relativeKey);
+      }
+    } catch (e) {
+      console.warn(`⚠️  Could not sync ${sourceDir}:`, e.message);
+    }
+  };
+  
+  // Sync components directory
+  if (verbose) {
+    console.log('📁 Syncing components...');
+  }
+  await syncDirectory(autoDefineSource, autoDefineTarget, 'components/');
+  
+  // Note: icons are not synced in this flow; use pds:export if needed
+  
+  // Update tracking file
+  if (!dryRun) {
+    tracking.checksums = { ...tracking.checksums, ...newChecksums };
+    tracking.lastSync = new Date().toISOString();
+    await writeFile(trackingFile, JSON.stringify(tracking, null, 2));
+  }
+  
+  // Report results
+  console.log(`✅ Sync complete: ${synced.length} files updated`);
+  
+  if (conflicts.length > 0) {
+    console.log(`⚠️  ${conflicts.length} conflicts detected:`);
+    conflicts.forEach(c => {
+      console.log(`   - ${c.file}: ${c.reason}`);
+    });
+    console.log('   Use --force to overwrite user modifications');
+  }
+  
+  if (verbose) {
+    console.log(`📊 Tracking file: ${trackingFile}`);
+    console.log(`📁 Components: ${autoDefineTarget}`);
+  }
+  
+  return {
+    synced: synced.length,
+    conflicts: conflicts.length,
+    tracking
+  };
+}
+
+// CLI interface
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const options = {
+    force: args.includes('--force'),
+    dryRun: args.includes('--dry-run'),
+    verbose: args.includes('--verbose') || args.includes('-v'),
+    targetDir: args.find(arg => arg.startsWith('--target='))?.split('=')[1] || './public'
+  };
+  
+  try {
+    await syncAssets(options);
+  } catch (error) {
+    console.error('❌ Sync failed:', error.message);
+    process.exit(1);
+  }
+}
+
+export { syncAssets };

package/packages/pds-cli/lib/asset-roots.js

@@ -0,0 +1,47 @@
+import path from 'path';
+import { resolvePublicAssetURL, getPublicRootCandidate, __internal } from '../../../src/js/pds-core/pds-paths.js';
+
+const URL_PATTERN = __internal.URL_PATTERN;
+const PDS_SEGMENT = __internal.DEFAULT_SEGMENT;
+
+function trimTrailingSeparators(value) {
+  return value.replace(/[\\/]+$/, '');
+}
+
+export function ensurePdsPath(input) {
+  if (!input || typeof input !== 'string') return input;
+  let target = trimTrailingSeparators(input);
+  if (/[\\/]pds$/i.test(target)) {
+    return target;
+  }
+  return path.join(target, PDS_SEGMENT);
+}
+
+export function resolvePublicAssetDirectory(config, options = {}) {
+  const webRootPath = options.webRootPath;
+  const cwd = options.cwd || process.cwd();
+  const overrideRoot = options.overrideRoot;
+  const candidate = (overrideRoot ?? getPublicRootCandidate(config)) || '';
+
+  if (candidate && typeof candidate === 'string' && !URL_PATTERN.test(candidate.trim())) {
+    let target = candidate.trim();
+    if (target) {
+      if (!path.isAbsolute(target)) {
+        target = path.resolve(cwd, target);
+      }
+      return ensurePdsPath(target);
+    }
+  }
+
+  if (webRootPath) {
+    return ensurePdsPath(path.join(webRootPath, 'assets'));
+  }
+
+  return ensurePdsPath(path.resolve(cwd, 'public', 'assets'));
+}
+
+export function isUrlLike(value) {
+  return typeof value === 'string' && URL_PATTERN.test(value.trim());
+}
+
+export { resolvePublicAssetURL, getPublicRootCandidate };