@machinemetrics/mm-react-components 1.4.2 → 1.5.0

package/dist/preview/SearchInputPreview.d.ts

@@ -0,0 +1,2 @@
+export default function SearchInputPreview(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SearchInputPreview.d.ts.map

package/dist/preview/SearchInputPreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchInputPreview.d.ts","sourceRoot":"","sources":["../../src/preview/SearchInputPreview.tsx"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,kBAAkB,4CAwBzC"}

package/dist/preview/SimplePaginationPreview.d.ts

@@ -0,0 +1,2 @@
+export default function SimplePaginationPreview(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SimplePaginationPreview.d.ts.map

package/dist/preview/SimplePaginationPreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimplePaginationPreview.d.ts","sourceRoot":"","sources":["../../src/preview/SimplePaginationPreview.tsx"],"names":[],"mappings":"AAIA,MAAM,CAAC,OAAO,UAAU,uBAAuB,4CAsC9C"}

package/dist/preview/SpinnerCarbidePreview.d.ts

@@ -0,0 +1,2 @@
+export default function SpinnerCarbidePreview(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=SpinnerCarbidePreview.d.ts.map

package/dist/preview/SpinnerCarbidePreview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpinnerCarbidePreview.d.ts","sourceRoot":"","sources":["../../src/preview/SpinnerCarbidePreview.tsx"],"names":[],"mappings":"AAGA,MAAM,CAAC,OAAO,UAAU,qBAAqB,4CAsC5C"}

package/dist/scripts/init.cjs

@@ -187,10 +187,10 @@ async function main() {
     log('\nDocs: GETTING_STARTED.md, CSS_EXPORTS.md, DEPENDENCIES.md', 'reset');
     log('Repo: https://github.com/machinemetrics/mm-react-components', 'reset');
 
-    // Offer Carbide AI skill installation (mm-install-skill will prompt for target/scope)
-    log('\nOptional: mm-carbide AI skill for Carbide-styled UI generation.', 'yellow');
+    // Offer components AI skill installation (mm-install-skill will prompt for target/scope)
+    log('\nOptional: components AI skill for Carbide-styled UI generation.', 'yellow');
     const installSkillAnswer = await askQuestion(
-      '  Install the Carbide skill for your AI editor? (y/N): ',
+      '  Install the components skill for your AI editor? (y/N): ',
     );
     if (
       installSkillAnswer.toLowerCase() === 'y' ||

package/dist/scripts/install-skill.cjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * MM React Components - Agent Skills installer (mm-carbide)
+ * MM React Components - Agent Skills installer (components)
  *
- * Installs or updates the mm-carbide skill for any Agent Skills–compatible tool.
+ * Installs or updates the components skill for any Agent Skills–compatible tool.
  * Follows the Agent Skills open standard (agentskills.io). Default: Cursor (project).
  *
  * Usage: npx @machinemetrics/mm-react-components mm-install-skill [options]
@@ -12,20 +12,23 @@
  *   --scope=<scope>  project (default) | user
  *   --force          overwrite even when version matches
  *
- * If --target or --scope are omitted, the script prompts interactively for
- * which AI tool and project vs user (global) install.
+ * If BOTH --target and --scope are omitted, the script prompts interactively
+ * for which AI tool and project vs user (global) install. When either flag is
+ * passed, the run is non-interactive and the omitted flag takes its default
+ * (target: cursor, scope: project).
  *
  * Paths by tool (project = cwd, user = home):
- *   cursor:  .cursor/skills/mm-carbide   | ~/.cursor/skills/mm-carbide
- *   copilot: .github/skills/mm-carbide   | ~/.copilot/skills/mm-carbide  (VS Code / GitHub Copilot)
- *   claude:  .claude/skills/mm-carbide   | ~/.claude/skills/mm-carbide    (Claude Code)
- *   gemini:  .gemini/skills/mm-carbide   | ~/.gemini/skills/mm-carbide    (Gemini CLI)
+ *   cursor:  .cursor/skills/components   | ~/.cursor/skills/components
+ *   copilot: .github/skills/components   | ~/.copilot/skills/components  (VS Code / GitHub Copilot)
+ *   claude:  .claude/skills/components   | ~/.claude/skills/components    (Claude Code)
+ *   gemini:  .gemini/skills/components   | ~/.gemini/skills/components    (Gemini CLI)
  */
 
 
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const readline = require('readline');
 
 const { ASCII_LOGO } = require(path.join(__dirname, 'ascii-logo.cjs'));
@@ -48,11 +51,14 @@ function log(message, color = 'reset') {
   console.log(`${colors[color]}${message}${colors.reset}`);
 }
 
+const SKILL_NAME = 'components';
+const LEGACY_SKILL_NAME = 'mm-carbide';
+
 const TARGET_PATHS = {
-  cursor: { project: '.cursor/skills/mm-carbide', user: '.cursor/skills/mm-carbide' },
-  copilot: { project: '.github/skills/mm-carbide', user: '.copilot/skills/mm-carbide' },
-  claude: { project: '.claude/skills/mm-carbide', user: '.claude/skills/mm-carbide' },
-  gemini: { project: '.gemini/skills/mm-carbide', user: '.gemini/skills/mm-carbide' },
+  cursor: { project: '.cursor/skills/components', user: '.cursor/skills/components' },
+  copilot: { project: '.github/skills/components', user: '.copilot/skills/components' },
+  claude: { project: '.claude/skills/components', user: '.claude/skills/components' },
+  gemini: { project: '.gemini/skills/components', user: '.gemini/skills/components' },
 };
 
 function parseArg(name) {
@@ -74,26 +80,315 @@ function askQuestion(question) {
   });
 }
 
-function copyRecursive(src, dest) {
-  const items = fs.readdirSync(src);
-  for (const item of items) {
-    const srcPath = path.join(src, item);
-    const destPath = path.join(dest, item);
-    const stat = fs.lstatSync(srcPath);
+const MANAGED_MANIFEST_NAME = '.mm-skill-manifest.json';
+const DIGEST_FILE_NAME = 'skill-digest.txt';
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// Recursively lists files under `dir`, relative paths with forward slashes,
+// sorted — the shipped skill's file set.
+function listShippedFiles(dir, prefix = '') {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const results = [];
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      results.push(...listShippedFiles(path.join(dir, entry.name), rel));
+    } else if (entry.isFile()) {
+      results.push(rel);
+    }
+  }
+  return results.sort();
+}
+
+// A single content digest over every shipped file (path + content), so
+// "already up to date" reflects actual shipped content, not just the package
+// version string (see VER-DEFER: skill content can change without a bump).
+function computeSkillDigest(skillSource) {
+  const files = listShippedFiles(skillSource);
+  const hash = crypto.createHash('sha256');
+  for (const rel of files) {
+    hash.update(rel);
+    hash.update('\0');
+    hash.update(fs.readFileSync(path.join(skillSource, rel)));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function buildManagedManifest(skillSource) {
+  const files = listShippedFiles(skillSource);
+  const manifest = { files: {} };
+  for (const rel of files) {
+    manifest.files[rel] = sha256(fs.readFileSync(path.join(skillSource, rel)));
+  }
+  return manifest;
+}
+
+// The manifest is self-identifying: it records the shipped version and the
+// aggregate content digest it was written for, so a torn update (version.txt
+// and skill-digest.txt renamed, manifest rename never happened) is detected
+// as a mismatch and repaired instead of accepted as "up to date".
+function manifestIdentityMatches(manifestStatus, packageVersion, currentDigest) {
+  return (
+    manifestStatus.version === packageVersion && manifestStatus.aggregateDigest === currentDigest
+  );
+}
+
+// A manifest key is only usable as a file path if it is a plain relative
+// path that stays inside the skill directory: no absolute paths, no drive
+// letters, no backslashes, no empty/./.. segments. Manifest content is
+// untrusted input (users can edit or corrupt it), and keys are later joined
+// to the destination for pruning.
+function isSafeRelativePath(rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return false;
+  if (rel.includes('\\') || rel.includes('\0')) return false;
+  if (path.isAbsolute(rel) || /^[A-Za-z]:/.test(rel)) return false;
+  return rel.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+
+// Reads the managed-files manifest and reports whether it is present and
+// trustworthy, distinguishing "no manifest yet" (legacy pre-manifest install)
+// from "manifest exists but is corrupt or schema-invalid" so callers can warn
+// appropriately. A manifest with any unsafe key or non-digest value is never
+// partially trusted — it is treated exactly like an unreadable one.
+function readManifestWithStatus(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { files: {}, present: false, corrupted: false, version: null, aggregateDigest: null };
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const files = parsed && typeof parsed === 'object' ? parsed.files : null;
+    if (!files || typeof files !== 'object' || Array.isArray(files)) {
+      return { files: {}, present: true, corrupted: true, version: null, aggregateDigest: null };
+    }
+    for (const [rel, digest] of Object.entries(files)) {
+      if (!isSafeRelativePath(rel) || typeof digest !== 'string' || !SHA256_HEX.test(digest)) {
+        return { files: {}, present: true, corrupted: true, version: null, aggregateDigest: null };
+      }
+    }
+    // Identity fields (absent on legacy manifests): kept only when they carry
+    // the expected shapes — anything else is treated as not-recorded.
+    const version = typeof parsed.version === 'string' ? parsed.version : null;
+    const aggregateDigest =
+      typeof parsed.aggregateDigest === 'string' && SHA256_HEX.test(parsed.aggregateDigest)
+        ? parsed.aggregateDigest
+        : null;
+    return { files, present: true, corrupted: false, version, aggregateDigest };
+  } catch {
+    return { files: {}, present: true, corrupted: true, version: null, aggregateDigest: null };
+  }
+}
+
+// True when `targetPath` resolves strictly beneath `baseDir` — the guard every
+// prune/write target must pass before any fs mutation.
+function isWithin(baseDir, targetPath) {
+  const rel = path.relative(baseDir, targetPath);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Existence check that does NOT follow symlinks: a dangling symlink counts as
+// occupied, so nothing is ever written through it.
+function existsNoFollow(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
+// Lexical containment (isWithin) is not enough on its own: a symlinked file
+// or subdirectory inside the destination would route reads/writes/deletes
+// outside it. Walk every existing component of `targetPath` beneath the
+// (already realpath-resolved) destination and refuse if any is a symlink.
+function assertNoSymlinkedComponents(realBase, targetPath) {
+  const rel = path.relative(realBase, targetPath);
+  let cur = realBase;
+  for (const segment of rel.split(path.sep)) {
+    cur = path.join(cur, segment);
+    let stat;
+    try {
+      stat = fs.lstatSync(cur);
+    } catch {
+      return; // nothing exists from here down: nothing to follow
+    }
     if (stat.isSymbolicLink()) {
-      // Do not follow symlinks (defense-in-depth)
-      continue;
+      throw new Error(
+        `Refusing to operate through a symlink inside the skill directory: ${path.relative(realBase, cur)}`,
+      );
+    }
+  }
+}
+
+// Returns a backup path for `destPath` that does not collide with an
+// existing backup: <path>.bak, then <path>.bak.1, <path>.bak.2, ...
+function nextBackupPath(destPath) {
+  // lstat-based existence: a dangling symlink squatting on a backup name is
+  // treated as occupied instead of being written through.
+  const base = `${destPath}.bak`;
+  if (!existsNoFollow(base)) return base;
+  let i = 1;
+  let candidate = `${base}.${i}`;
+  while (existsNoFollow(candidate)) {
+    i += 1;
+    candidate = `${base}.${i}`;
+  }
+  return candidate;
+}
+
+// Atomic metadata write that cannot be redirected by a pre-planted symlink:
+// the temp name carries a random suffix and is opened with exclusive
+// semantics ('wx'), so an existing entry — symlink included — fails EEXIST
+// and a fresh suffix is tried instead of writing through it.
+function writeFileAtomic(filePath, content, { suffixes } = {}) {
+  const iterator = suffixes ? suffixes[Symbol.iterator]() : null;
+  const nextSuffix = () => {
+    if (!iterator) return crypto.randomBytes(8).toString('hex');
+    const n = iterator.next();
+    if (n.done) throw new Error(`Could not create a temp file for ${filePath}`);
+    return n.value;
+  };
+  for (;;) {
+    const tmpPath = `${filePath}.tmp-${nextSuffix()}`;
+    try {
+      fs.writeFileSync(tmpPath, content, { encoding: 'utf8', flag: 'wx' });
+      fs.renameSync(tmpPath, filePath);
+      return;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+    }
+  }
+}
+
+// Updates `destination` from `skillSource`, using the previous managed-files
+// manifest (if any) to:
+//   - back up a locally modified managed file to <name>.bak (with a warning)
+//     before overwriting it with fresh shipped content;
+//   - prune managed files the current skill source no longer ships;
+//   - leave any file not present in the previous manifest (i.e. not
+//     installer-managed — user-added) completely untouched.
+// Returns the new managed-files manifest to write after this call.
+// `destination` must already be realpath-resolved by the caller so symlink
+// checks compare against the real directory.
+function syncManagedFiles(skillSource, destination) {
+  const shippedFiles = listShippedFiles(skillSource);
+
+  // Pre-pass, before ANY mutation: every write target must be lexically
+  // contained AND free of symlinked components, so a refusal leaves no
+  // partial work behind.
+  for (const rel of shippedFiles) {
+    const destPath = path.join(destination, ...rel.split('/'));
+    if (!isWithin(destination, destPath)) {
+      throw new Error(`Refusing to write outside the skill directory: ${rel}`);
+    }
+    assertNoSymlinkedComponents(destination, destPath);
+  }
+
+  const manifestStatus = readManifestWithStatus(path.join(destination, MANAGED_MANIFEST_NAME));
+  const previousFiles = manifestStatus.files;
+  // The manifest is only trustworthy for pruning decisions when it exists
+  // and parsed cleanly. A missing manifest (legacy install) is a normal,
+  // unremarkable case; a present-but-corrupt manifest is not, so it gets a
+  // notice below.
+  const manifestTrustworthy = manifestStatus.present && !manifestStatus.corrupted;
+
+  if (manifestStatus.corrupted) {
+    log(
+      'Managed-files manifest unreadable; proceeding with byte-comparison fallback for local modification detection.',
+      'yellow',
+    );
+  }
+
+  for (const rel of shippedFiles) {
+    const srcPath = path.join(skillSource, rel);
+    const destPath = path.join(destination, ...rel.split('/'));
+    if (!isWithin(destination, destPath)) {
+      throw new Error(`Refusing to write outside the skill directory: ${rel}`);
     }
-    if (stat.isDirectory()) {
-      if (!fs.existsSync(destPath)) {
-        fs.mkdirSync(destPath, { recursive: true });
+    const destParent = path.dirname(destPath);
+    if (!fs.existsSync(destParent)) {
+      fs.mkdirSync(destParent, { recursive: true });
+    }
+
+    if (fs.existsSync(destPath)) {
+      let userModified;
+      if (Object.prototype.hasOwnProperty.call(previousFiles, rel)) {
+        userModified = sha256(fs.readFileSync(destPath)) !== previousFiles[rel];
+      } else {
+        // No manifest entry for this managed file — either a pre-manifest
+        // (legacy) install, or the manifest is missing/corrupted. Fall back
+        // to comparing against the shipped bytes: a mismatch is treated as
+        // a user modification (conservative false-positive backups are
+        // acceptable; silent overwrites are not).
+        userModified = sha256(fs.readFileSync(destPath)) !== sha256(fs.readFileSync(srcPath));
+      }
+      if (userModified) {
+        const backupPath = nextBackupPath(destPath);
+        fs.copyFileSync(destPath, backupPath);
+        log(
+          `Local modification to ${rel} detected; backed it up to ${path.basename(backupPath)} and overwrote it with the updated skill content.`,
+          'yellow',
+        );
       }
-      copyRecursive(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
     }
+
+    fs.copyFileSync(srcPath, destPath);
   }
+
+  // Prune managed files the current skill no longer ships. A file only
+  // counts as "managed" if the previous manifest recorded it — anything
+  // absent from that manifest (user-added) is left alone. Pruning never
+  // runs off an untrustworthy manifest (missing, corrupted, or
+  // schema-invalid), never reaches outside the skill directory, and never
+  // deletes a file whose current bytes no longer match the recorded digest
+  // (user modifications are kept in place with a notice).
+  if (manifestTrustworthy) {
+    const shippedSet = new Set(shippedFiles);
+    for (const rel of Object.keys(previousFiles)) {
+      if (shippedSet.has(rel)) continue;
+      const stalePath = path.join(destination, ...rel.split('/'));
+      if (!isWithin(destination, stalePath)) continue;
+      try {
+        assertNoSymlinkedComponents(destination, stalePath);
+      } catch {
+        log(`Left ${rel} in place: it resolves through a symlink and was not touched.`, 'yellow');
+        continue;
+      }
+      if (!fs.existsSync(stalePath)) continue;
+      if (sha256(fs.readFileSync(stalePath)) === previousFiles[rel]) {
+        fs.rmSync(stalePath, { force: true });
+        log(`Removed ${rel}: no longer shipped with this skill.`, 'yellow');
+      } else {
+        log(
+          `Left ${rel} in place: no longer shipped with this skill, but it has local modifications.`,
+          'yellow',
+        );
+      }
+    }
+  }
+
+  return buildManagedManifest(skillSource);
+}
+
+function warnOnManagedLegacyInstall(destination) {
+  // A managed legacy install is identified by the version.txt this installer
+  // used to write. User-authored directories (no version.txt) are ignored.
+  const legacyDir = path.join(path.dirname(destination), LEGACY_SKILL_NAME);
+  if (!fs.existsSync(path.join(legacyDir, 'version.txt'))) return;
+  log(
+    `Found a legacy managed ${LEGACY_SKILL_NAME} install at ${legacyDir}.`,
+    'yellow',
+  );
+  log(
+    `This skill is now installed as "${SKILL_NAME}". No files were deleted; remove the old ${LEGACY_SKILL_NAME} directory manually once you no longer need it.`,
+    'yellow',
+  );
 }
 
 function performInstall(target, scope, force) {
@@ -101,7 +396,18 @@ function performInstall(target, scope, force) {
   const relativePath = TARGET_PATHS[target][scope];
   const destination = path.join(baseDir, ...relativePath.split('/'));
 
-  const skillSource = path.join(__dirname, '..', 'cursor-skill', 'mm-carbide');
+  warnOnManagedLegacyInstall(destination);
+
+  // Resolve the destination through any symlinks up front (creating it if
+  // needed): every later containment/symlink check compares against the real
+  // directory, so a destination that IS a symlink is resolved and still
+  // contained.
+  if (!fs.existsSync(destination)) {
+    fs.mkdirSync(destination, { recursive: true });
+  }
+  const realDestination = fs.realpathSync(destination);
+
+  const skillSource = path.join(__dirname, '..', 'cursor-skill', SKILL_NAME);
   // When installed: dist/scripts -> ../../package.json. When in repo: scripts -> ../package.json.
   const packageJsonPath =
     path.join(__dirname, '..', '..', 'package.json');
@@ -126,41 +432,105 @@ function performInstall(target, scope, force) {
     process.exit(1);
   }
 
-  const versionFilePath = path.join(destination, 'version.txt');
+  const versionFilePath = path.join(realDestination, 'version.txt');
+  const digestFilePath = path.join(realDestination, DIGEST_FILE_NAME);
   let installedVersion = null;
-  if (fs.existsSync(destination) && fs.existsSync(versionFilePath)) {
+  let installedDigest = null;
+  if (fs.existsSync(versionFilePath)) {
     try {
       installedVersion = fs.readFileSync(versionFilePath, 'utf8').trim();
     } catch {
       installedVersion = null;
     }
   }
+  if (fs.existsSync(digestFilePath)) {
+    try {
+      installedDigest = fs.readFileSync(digestFilePath, 'utf8').trim();
+    } catch {
+      installedDigest = null;
+    }
+  }
+
+  const currentDigest = computeSkillDigest(skillSource);
+
+  // Ownership of the destination is established only by a present, valid
+  // manifest — the same authority pruning relies on. A torn install (version
+  // and digest written, manifest missing or corrupt) is not owned and not up
+  // to date.
+  const manifestFilePath = path.join(realDestination, MANAGED_MANIFEST_NAME);
+  const preManifestStatus = readManifestWithStatus(manifestFilePath);
+  const ownershipEstablished = preManifestStatus.present && !preManifestStatus.corrupted;
 
-  if (!force && installedVersion !== null && installedVersion === packageVersion) {
-    log(`Already up to date (mm-carbide v${packageVersion}).`, 'green');
+  // "Already up to date" requires the version, the shipped-content digest,
+  // AND a valid manifest whose own recorded identity matches. A
+  // skill-content-only change (no version bump) still reinstalls, since the
+  // digest catches what the version string can't; a torn metadata state (no
+  // valid manifest, or a manifest still carrying the previous update's
+  // identity) repairs instead of early-returning. Legacy manifests without
+  // identity fields keep the previous behavior, with a notice.
+  const manifestHasIdentity =
+    preManifestStatus.version !== null && preManifestStatus.aggregateDigest !== null;
+  const manifestIdentityOk = manifestHasIdentity
+    ? manifestIdentityMatches(preManifestStatus, packageVersion, currentDigest)
+    : true;
+  if (!force && ownershipEstablished && manifestIdentityOk && installedVersion !== null && installedVersion === packageVersion && installedDigest === currentDigest) {
+    if (!manifestHasIdentity) {
+      log(
+        'Manifest was written by an older installer (no recorded version/digest); run with --force to refresh it.',
+        'yellow',
+      );
+    }
+    log(`Already up to date (${SKILL_NAME} v${packageVersion}).`, 'green');
     return;
   }
 
-  const destParent = path.dirname(destination);
-  if (!fs.existsSync(destParent)) {
-    fs.mkdirSync(destParent, { recursive: true });
-  }
-  if (!fs.existsSync(destination)) {
-    fs.mkdirSync(destination, { recursive: true });
+  // Guard the metadata targets BEFORE any file is written so a refusal
+  // leaves no partial work (syncManagedFiles pre-checks its own targets).
+  for (const metadataPath of [versionFilePath, digestFilePath, manifestFilePath]) {
+    assertNoSymlinkedComponents(realDestination, metadataPath);
   }
 
+  const managedManifest = {
+    version: packageVersion,
+    aggregateDigest: currentDigest,
+    ...syncManagedFiles(skillSource, realDestination),
+  };
+
   if (installedVersion !== null) {
-    copyRecursive(skillSource, destination);
     log(
-      `Updated mm-carbide from ${installedVersion ?? 'unknown'} to v${packageVersion}.`,
+      `Updated ${SKILL_NAME} from ${installedVersion ?? 'unknown'} to v${packageVersion}.`,
       'green',
     );
   } else {
-    copyRecursive(skillSource, destination);
-    log(`Installed mm-carbide v${packageVersion}.`, 'green');
+    log(`Installed ${SKILL_NAME} v${packageVersion}.`, 'green');
   }
 
-  fs.writeFileSync(versionFilePath, packageVersion, 'utf8');
+  // Metadata is written via temp-file + rename (atomic on the same
+  // filesystem), with the manifest LAST: a kill mid-update can leave a stale
+  // version/digest, but never a valid manifest over torn content — and the
+  // up-to-date check above requires the manifest, so a torn state repairs on
+  // the next run. Until ownership is established (valid manifest present),
+  // any user-authored file squatting on a metadata name is backed up first.
+  const metadataWrites = [
+    [versionFilePath, packageVersion],
+    [digestFilePath, currentDigest],
+    [manifestFilePath, JSON.stringify(managedManifest, null, 2)],
+  ];
+  for (const [filePath, content] of metadataWrites) {
+    if (
+      !ownershipEstablished &&
+      fs.existsSync(filePath) &&
+      fs.readFileSync(filePath, 'utf8') !== content
+    ) {
+      const backupPath = nextBackupPath(filePath);
+      fs.copyFileSync(filePath, backupPath);
+      log(
+        `Existing ${path.basename(filePath)} was not written by this installer; backed it up to ${path.basename(backupPath)}.`,
+        'yellow',
+      );
+    }
+    writeFileAtomic(filePath, content);
+  }
 
   log(`Location: ${destination}`, 'cyan');
   log('Use when generating UIs with Carbide / mm-react-components.', 'cyan');
@@ -173,7 +543,11 @@ async function main() {
   let target = parseArg('target');
   let scope = parseArg('scope');
 
-  const interactive = target == null || scope == null;
+  // Prompt only when NO flags were passed: any explicit flag signals a
+  // (possibly non-interactive) scripted caller, so the omitted flag falls
+  // back to its default instead of a prompt that would hang or overwrite
+  // the explicitly passed value.
+  const interactive = target == null && scope == null;
   if (interactive) {
     const targetPrompt =
       'Which AI do you use? (1) Cursor  (2) VS Code / GitHub Copilot  (3) Claude Code  (4) Gemini CLI: ';
@@ -221,7 +595,11 @@ async function main() {
   performInstall(target, scope, force);
 }
 
-main().catch((err) => {
-  log(`Error: ${err.message}`, 'red');
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch((err) => {
+    log(`Error: ${err.message}`, 'red');
+    process.exit(1);
+  });
+}
+
+module.exports = { syncManagedFiles, writeFileAtomic };

package/dist/themes/carbide.css

@@ -1,11 +1,11 @@
 /* Note: Font imports are now handled in src/lib/styles.css to avoid @import ordering issues */
 
 :root {
-  --radius: 0.5rem;
-  --radius-sm: 4px;
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
+  --radius: 0.5rem; /* parity-exempt: theme-invariant radius scale */
+  --radius-sm: 4px; /* parity-exempt: theme-invariant radius scale */
+  --radius-md: calc(var(--radius) - 2px); /* parity-exempt: theme-invariant radius scale */
+  --radius-lg: var(--radius); /* parity-exempt: theme-invariant radius scale */
+  --radius-xl: calc(var(--radius) + 4px); /* parity-exempt: theme-invariant radius scale */
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
   --card: oklch(1 0 0);
@@ -35,32 +35,35 @@
   --sidebar-ring: oklch(0.708 0 0);
 
   /* Overlay token (base) */
+  /* parity-exempt: theme-invariant base — dark handling lives in consumer rules via color-mix */
   --overlay-bg: rgba(0, 0, 0, 0.8);
 
   /* --- Typography tokens (shadcn/ui reference) --- */
+  /* parity-exempt: theme-invariant font stack */
   --font-sans:
     ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI',
     Roboto, 'Helvetica Neue', Arial, 'Noto Sans Variable', sans-serif,
     'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+  /* parity-exempt: theme-invariant font stack */
   --font-mono:
     ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
     'Courier New', monospace;
-  --font-heading: var(--font-sans);
-  --font-body: var(--font-sans);
+  --font-heading: var(--font-sans); /* parity-exempt: theme-invariant font stack */
+  --font-body: var(--font-sans); /* parity-exempt: theme-invariant font stack */
 
-  --text-base-size: 1rem; /* 16px */
-  --text-sm-size: 0.875rem; /* 14px */
-  --text-lg-size: 1.125rem; /* 18px */
+  --text-base-size: 1rem; /* 16px */ /* parity-exempt: theme-invariant type scale */
+  --text-sm-size: 0.875rem; /* 14px */ /* parity-exempt: theme-invariant type scale */
+  --text-lg-size: 1.125rem; /* 18px */ /* parity-exempt: theme-invariant type scale */
 
-  --font-weight-normal: 400;
-  --font-weight-medium: 500;
-  --font-weight-bold: 700;
+  --font-weight-normal: 400; /* parity-exempt: theme-invariant weight scale */
+  --font-weight-medium: 500; /* parity-exempt: theme-invariant weight scale */
+  --font-weight-bold: 700; /* parity-exempt: theme-invariant weight scale */
 
-  --leading-tight: 1.25;
-  --leading-normal: 1.5;
+  --leading-tight: 1.25; /* parity-exempt: theme-invariant line-height scale */
+  --leading-normal: 1.5; /* parity-exempt: theme-invariant line-height scale */
 
-  --tracking-tight: -0.015em;
-  --tracking-normal: 0;
+  --tracking-tight: -0.015em; /* parity-exempt: theme-invariant tracking scale */
+  --tracking-normal: 0; /* parity-exempt: theme-invariant tracking scale */
 }
 
 .dark {