@simpill/utils 1.0.0

package/scripts/monorepo/use-local-utils-at-root.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Rewrite root package.json so @simpill deps point to local utils (file:./utils/@simpill-*.utils).
+ * Run from repo root. After this, run npm install so root uses built local packages.
+ * Use npm run sync:deps to restore npm ^version deps.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const REPO_ROOT = path.join(__dirname, "..", "..");
+const UTILS = path.join(REPO_ROOT, "utils");
+const ROOT_PKG = path.join(REPO_ROOT, "package.json");
+
+const dirs = fs
+  .readdirSync(UTILS, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name.startsWith("@simpill-") && d.name.endsWith(".utils"))
+  .map((d) => d.name)
+  .sort();
+
+const deps = {};
+for (const dir of dirs) {
+  const pkgPath = path.join(UTILS, dir, "package.json");
+  if (!fs.existsSync(pkgPath)) continue;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const name = pkg.name;
+  if (name && name.startsWith("@simpill/")) {
+    deps[name] = `file:./utils/${dir}`;
+  }
+}
+
+const rootPkg = JSON.parse(fs.readFileSync(ROOT_PKG, "utf8"));
+rootPkg.dependencies = rootPkg.dependencies || {};
+let changed = false;
+for (const [name, spec] of Object.entries(deps)) {
+  if (rootPkg.dependencies[name] !== spec) {
+    rootPkg.dependencies[name] = spec;
+    changed = true;
+  }
+}
+if (changed) {
+  const keys = Object.keys(rootPkg.dependencies).sort();
+  const sorted = {};
+  for (const k of keys) sorted[k] = rootPkg.dependencies[k];
+  rootPkg.dependencies = sorted;
+  fs.writeFileSync(ROOT_PKG, JSON.stringify(rootPkg, null, 2) + "\n", "utf8");
+  console.log("Root package.json now uses file:./utils/@simpill-*.utils. Run: npm install");
+} else {
+  console.log("Root already points to local utils.");
+}

package/scripts/publish/publish-all.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Publish all @simpill packages to GitHub (push) and npm in dependency order.
+# Requires: gh (GitHub CLI) and npm logged in with access to @simpill scope.
+# =============================================================================
+# Usage:
+#   ./scripts/publish/publish-all.sh              # GitHub push + npm publish (prompts)
+#   ./scripts/publish/publish-all.sh --dry-run   # No push, npm publish --dry-run
+#   ./scripts/publish/publish-all.sh --skip-github   # Only npm publish
+#   ./scripts/publish/publish-all.sh --yes       # Skip confirmations
+# =============================================================================
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LIB_DIR="$REPO_ROOT/scripts/lib"
+
+DRY_RUN=false
+SKIP_GITHUB=false
+YES=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run)      DRY_RUN=true ;;
+    --skip-github) SKIP_GITHUB=true ;;
+    --npm-only)    SKIP_GITHUB=true ;;
+    --yes|-y)      YES=true ;;
+    *)
+      echo "Unknown option: $arg"
+      echo "Usage: $0 [--dry-run] [--skip-github|--npm-only] [--yes|-y]"
+      exit 1
+      ;;
+  esac
+done
+
+echo "============================================"
+echo "Publish all @simpill packages"
+echo "============================================"
+echo "  --dry-run:     $DRY_RUN"
+echo "  --skip-github: $SKIP_GITHUB"
+echo "  --yes:         $YES"
+echo "============================================"
+
+# -----------------------------------------------------------------------------
+# 1. Check GitHub CLI and auth (unless skipped)
+# -----------------------------------------------------------------------------
+if [ "$SKIP_GITHUB" = false ]; then
+  if ! command -v gh &>/dev/null; then
+    echo "Error: GitHub CLI (gh) not found. Install it or use --skip-github."
+    exit 1
+  fi
+  if ! gh auth status &>/dev/null; then
+    echo "Error: Not logged in to GitHub. Run: gh auth login"
+    exit 1
+  fi
+  if [ "$DRY_RUN" = false ] && [ "$YES" = false ]; then
+    echo "GitHub: will push current branch. Continue? [y/N]"
+    read -r ans
+    if [ "$ans" != "y" ] && [ "$ans" != "Y" ]; then
+      echo "Aborted."
+      exit 0
+    fi
+  fi
+  if [ "$DRY_RUN" = false ]; then
+    echo "Pushing to GitHub..."
+    git -C "$REPO_ROOT" push
+    echo "GitHub push done."
+  else
+    echo "[dry-run] Skipping GitHub push."
+  fi
+fi
+
+# -----------------------------------------------------------------------------
+# 2. Check npm auth and @simpill scope
+# -----------------------------------------------------------------------------
+if ! command -v npm &>/dev/null; then
+  echo "Error: npm not found."
+  exit 1
+fi
+if ! npm whoami &>/dev/null; then
+  echo "Error: Not logged in to npm. Run: npm login"
+  exit 1
+fi
+if [ "$DRY_RUN" = false ] && [ "$YES" = false ]; then
+  echo "Publish all packages to npm under @simpill? [y/N]"
+  read -r ans
+  if [ "$ans" != "y" ] && [ "$ans" != "Y" ]; then
+    echo "Aborted."
+    exit 0
+  fi
+fi
+
+# -----------------------------------------------------------------------------
+# 3. Get publish order (topological)
+# -----------------------------------------------------------------------------
+ORDER=()
+while IFS= read -r line; do
+  [ -n "$line" ] && ORDER+=("$line")
+done < <(node "$LIB_DIR/publish-order.js" order "$REPO_ROOT")
+
+echo "Publish order (${#ORDER[@]} packages):"
+for d in "${ORDER[@]}"; do
+  echo "  - $d"
+done
+
+# -----------------------------------------------------------------------------
+# 4. Publish each package: backup package.json, rewrite file: -> ^ver, publish, restore
+# -----------------------------------------------------------------------------
+FAILED=()
+for dir in "${ORDER[@]}"; do
+  pkg_path="$REPO_ROOT/utils/$dir/package.json"
+  if [ ! -f "$pkg_path" ]; then
+    echo "  Skip $dir (no package.json)"
+    continue
+  fi
+  name=$(node -e "console.log(require('$pkg_path').name)")
+  echo "----------------------------------------"
+  echo "Publishing: $name ($dir)"
+  echo "----------------------------------------"
+  backup="$pkg_path.publish-backup"
+  cp "$pkg_path" "$backup"
+  trap "mv -f '$backup' '$pkg_path'" EXIT
+  node "$LIB_DIR/publish-order.js" rewrite "$dir" "$REPO_ROOT" > "$pkg_path"
+  set +e
+  if [ "$DRY_RUN" = true ]; then
+    (cd "$REPO_ROOT/utils/$dir" && npm publish --access public --dry-run)
+  else
+    (cd "$REPO_ROOT/utils/$dir" && npm publish --access public)
+  fi
+  ret=$?
+  set -e
+  mv -f "$backup" "$pkg_path"
+  trap - EXIT
+  if [ $ret -ne 0 ]; then
+    echo "  FAILED: $name"
+    FAILED+=("$name")
+  else
+    echo "  OK: $name"
+  fi
+done
+
+echo ""
+echo "============================================"
+echo "Publish summary"
+echo "============================================"
+if [ ${#FAILED[@]} -eq 0 ]; then
+  echo "All packages published successfully."
+  exit 0
+fi
+echo "Failed: ${FAILED[*]}"
+exit 1

package/scripts/utils/utils-fix-repo-metadata.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Fix repository, bugs, homepage in each utils package for standalone GitHub repos.
+ * Replaces file:../@simpill-*.utils deps with github:SkinnnyJay/<name>.utils.
+ * Run from repo root. Requires utils/@simpill-*.utils to exist.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const REPO_ROOT = path.join(__dirname, "..", "..");
+const UTILS = path.join(REPO_ROOT, "utils");
+const OWNER = "SkinnnyJay";
+
+const dirs = fs.readdirSync(UTILS, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name.startsWith("@simpill-") && d.name.endsWith(".utils"))
+  .map((d) => d.name);
+
+for (const dir of dirs) {
+  const shortName = dir.replace(/^@simpill-/, "");
+  const pkgPath = path.join(UTILS, dir, "package.json");
+  if (!fs.existsSync(pkgPath)) continue;
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  let changed = false;
+
+  if (!pkg.repository || pkg.repository.url.includes("simpill.git")) {
+    pkg.repository = { type: "git", url: `https://github.com/${OWNER}/${shortName}.git` };
+    changed = true;
+  }
+  if (pkg.repository && pkg.repository.directory && pkg.repository.directory !== ".") {
+    pkg.repository.directory = ".";
+    changed = true;
+  }
+  if (!pkg.bugs || pkg.bugs.url.includes("simpill/issues")) {
+    pkg.bugs = { url: `https://github.com/${OWNER}/${shortName}/issues` };
+    changed = true;
+  }
+  if (!pkg.homepage || pkg.homepage.includes("simpill/tree")) {
+    pkg.homepage = `https://github.com/${OWNER}/${shortName}#readme`;
+    changed = true;
+  }
+
+  if (pkg.dependencies) {
+    for (const [dep, spec] of Object.entries(pkg.dependencies)) {
+      if (dep.startsWith("@simpill/") && typeof spec === "string" && spec.startsWith("file:../")) {
+        const match = spec.match(/file:\.\.\/@simpill-(.+\.utils)/);
+        if (match) {
+          pkg.dependencies[dep] = `github:${OWNER}/${match[1]}`;
+          changed = true;
+        }
+      }
+    }
+  }
+
+  if (changed) {
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+    console.log("Updated:", dir);
+  }
+}
+
+console.log("Done. Check utils/@simpill-*.utils/package.json and commit + push each repo.");

package/scripts/utils/utils-prepare-all.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# =============================================================================
+# Prepare all utils packages for npm: install, audit --fix, typecheck, test, build
+# =============================================================================
+# Run from repo root: ./scripts/utils/utils-prepare-all.sh
+# Exits 0 only if every package passes all steps.
+# Fix any reported failures in the failing package, then re-run.
+# =============================================================================
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+UTILS_DIR="$REPO_ROOT/utils"
+SCRIPTS_LIB="$REPO_ROOT/scripts/lib"
+cd "$REPO_ROOT"
+
+FAILED_PACKAGES=()
+TOTAL=0
+PASSED=0
+
+# Process in dependency order so typecheck/build can resolve file:../@simpill-*.utils
+ORDERED_DIRS=()
+while IFS= read -r line; do
+  [ -n "$line" ] && ORDERED_DIRS+=("$UTILS_DIR/$line")
+done < <(node "$SCRIPTS_LIB/publish-order.js" order "$REPO_ROOT" 2>/dev/null)
+if [ ${#ORDERED_DIRS[@]} -eq 0 ]; then
+  # Fallback: alphabetical
+  for d in "$UTILS_DIR"/@simpill-*.utils; do
+    [ -d "$d" ] && [ -f "$d/package.json" ] && ORDERED_DIRS+=("$d")
+  done
+fi
+
+for d in "${ORDERED_DIRS[@]}"; do
+  [ -d "$d" ] || continue
+  [ -f "$d/package.json" ] || continue
+  name=$(basename "$d")
+  TOTAL=$((TOTAL + 1))
+  echo "----------------------------------------"
+  echo "  $name"
+  echo "----------------------------------------"
+
+  failed=false
+  if ! (cd "$d" && npm install --no-audit --no-fund --silent 2>&1) >/dev/null; then
+    echo "  install   ✗"
+    failed=true
+  else
+    echo "  install   ✓"
+  fi
+
+  if [ "$failed" = false ]; then
+    if (cd "$d" && npm audit fix --force 2>&1) >/dev/null; then
+      echo "  audit     ✓"
+    else
+      echo "  audit     ⚠ (issues remain; run 'npm audit' in $d)"
+      # Do not set failed=true: audit often exits 1 for unfixable issues; still run typecheck/test/build
+    fi
+  fi
+
+  if [ "$failed" = false ]; then
+    if ! (cd "$d" && npm run typecheck --if-present 2>&1) >/dev/null; then
+      echo "  typecheck ✗"
+      failed=true
+    else
+      echo "  typecheck ✓"
+    fi
+  fi
+
+  if [ "$failed" = false ]; then
+    if ! (cd "$d" && npm test --silent 2>&1) >/dev/null; then
+      echo "  test     ✗"
+      failed=true
+    else
+      echo "  test     ✓"
+    fi
+  fi
+
+  if [ "$failed" = false ]; then
+    if ! (cd "$d" && npm run build --silent 2>&1) >/dev/null; then
+      echo "  build    ✗"
+      failed=true
+    else
+      echo "  build    ✓"
+    fi
+  fi
+
+  if [ "$failed" = true ]; then
+    FAILED_PACKAGES+=("$name")
+  else
+    PASSED=$((PASSED + 1))
+  fi
+  echo ""
+done
+
+echo "============================================"
+echo "Prepare all utils – summary"
+echo "============================================"
+echo "  Passed: $PASSED / $TOTAL"
+if [ ${#FAILED_PACKAGES[@]} -gt 0 ]; then
+  echo "  Failed:  ${FAILED_PACKAGES[*]}"
+  echo ""
+  echo "Fix issues in each package above, then re-run: ./scripts/utils/utils-prepare-all.sh"
+  echo "============================================"
+  exit 1
+fi
+echo "  All packages ready for npm."
+echo "============================================"
+exit 0

package/scripts/utils/utils-set-npm-keywords.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Set npm package.json "keywords" from each package's TOPICS.md (if present)
+ * or from the shared package-topics list. Run from repo root.
+ * Requires utils/@simpill-*.utils to exist.
+ *
+ * Usage:
+ *   node scripts/utils/utils-set-npm-keywords.js           # update package.json from TOPICS.md or fallback
+ *   node scripts/utils/utils-set-npm-keywords.js --write-topics-md   # write TOPICS.md in each package, then update keywords
+ *   node scripts/utils/utils-set-npm-keywords.js --dry-run # print what would be set
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+const UTILS_DIR = path.join(REPO_ROOT, "utils");
+const MAX_KEYWORDS = 20;
+
+const { BASE_TOPICS, PACKAGE_TOPICS } = require("../lib/package-topics.js");
+
+function getPackageDirs() {
+  if (!fs.existsSync(UTILS_DIR)) return [];
+  return fs
+    .readdirSync(UTILS_DIR, { withFileTypes: true })
+    .filter(
+      (d) =>
+        d.isDirectory() &&
+        d.name.startsWith("@simpill-") &&
+        d.name.endsWith(".utils")
+    )
+    .map((d) => ({ dir: d.name, shortName: d.name.replace(/^@simpill-/, "") }));
+}
+
+/**
+ * Parse TOPICS.md format: lines like `- \`topic\``
+ */
+function parseTopicsMd(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, "utf8");
+  const names = [];
+  const re = /^\s*-\s*`([^`]+)`/gm;
+  let m;
+  while ((m = re.exec(content)) !== null) names.push(m[1]);
+  return names.length ? names : null;
+}
+
+function getKeywordsFromFallback(shortName) {
+  const extra = PACKAGE_TOPICS[shortName] || [shortName.replace(".utils", "")];
+  const combined = [...BASE_TOPICS, ...extra];
+  return [...new Set(combined)].slice(0, MAX_KEYWORDS);
+}
+
+function getKeywordsForPackage(pkgDir, shortName) {
+  const topicsPath = path.join(UTILS_DIR, pkgDir, "TOPICS.md");
+  const fromFile = parseTopicsMd(topicsPath);
+  if (fromFile && fromFile.length > 0) {
+    return [...new Set(["simpill", ...fromFile])].slice(0, MAX_KEYWORDS);
+  }
+  return getKeywordsFromFallback(shortName);
+}
+
+function writeTopicsMd(pkgDir, shortName) {
+  const keywords = getKeywordsFromFallback(shortName);
+  const topicsPath = path.join(UTILS_DIR, pkgDir, "TOPICS.md");
+  const lines = [
+    "# npm keywords (and GitHub topics)",
+    "",
+    "Used by `scripts/utils/utils-set-npm-keywords.js` to set package.json keywords.",
+    "Edit this file to customize; one topic per line in backticks.",
+    "",
+    ...keywords.map((k) => `- \`${k}\``),
+    "",
+  ];
+  fs.writeFileSync(topicsPath, lines.join("\n"), "utf8");
+  return keywords;
+}
+
+function main() {
+  const dryRun = process.argv.includes("--dry-run");
+  const writeTopicsMdFlag = process.argv.includes("--write-topics-md");
+
+  const packages = getPackageDirs();
+  if (packages.length === 0) {
+    console.log("No utils/@simpill-*.utils packages found. Exiting.");
+    process.exit(0);
+  }
+
+  console.log(
+    writeTopicsMdFlag
+      ? "Writing TOPICS.md per package and updating package.json keywords...\n"
+      : "Updating package.json keywords from each package's TOPICS.md (or fallback)...\n"
+  );
+
+  for (const { dir, shortName } of packages) {
+    const pkgPath = path.join(UTILS_DIR, dir, "package.json");
+    if (!fs.existsSync(pkgPath)) continue;
+
+    let keywords;
+    if (writeTopicsMdFlag) {
+      keywords = writeTopicsMd(dir, shortName);
+      console.log(`  ${dir}: wrote TOPICS.md, keywords (${keywords.length})`);
+    } else {
+      keywords = getKeywordsForPackage(dir, shortName);
+    }
+
+    if (dryRun) {
+      console.log(`  ${dir}: (dry run) ${keywords.slice(0, 8).join(", ")}${keywords.length > 8 ? "..." : ""}`);
+      continue;
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const prev = pkg.keywords || [];
+    const same =
+      Array.isArray(prev) &&
+      prev.length === keywords.length &&
+      prev.every((k, i) => k === keywords[i]);
+    if (same) continue;
+
+    pkg.keywords = keywords;
+    fs.writeFileSync(
+      pkgPath,
+      JSON.stringify(pkg, null, 2) + "\n",
+      "utf8"
+    );
+    console.log(`  ${dir}: updated keywords (${keywords.length})`);
+  }
+
+  console.log("\nDone.");
+}
+
+main();

package/scripts/utils/utils-update-readme-badges.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Updates each utils package README.md:
+ * - Puts an Install section at the very top (npm + GitHub)
+ * - Adds npm and GitHub badges after the first line (banner) if missing
+ * - Removes duplicate ## Installation section from the body
+ *
+ * Usage: node scripts/utils/utils-update-readme-badges.js
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const REPO = "SkinnnyJay/simpill-utils";
+const REPO_URL = `https://github.com/${REPO}`;
+
+const utilsDir = path.join(__dirname, "..", "..", "utils");
+const dirs = fs
+  .readdirSync(utilsDir, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name.startsWith("@simpill-"))
+  .map((d) => d.name);
+
+function removeSection(readme, heading) {
+  const idx = readme.indexOf(heading);
+  if (idx === -1) return readme;
+  const afterHeading = readme.slice(idx);
+  const nextH2 = afterHeading.slice(heading.length).match(/\n## /);
+  const end = nextH2 ? idx + heading.length + nextH2.index : readme.length;
+  const before = readme.slice(0, idx).trimEnd();
+  let after = readme.slice(end).trimStart();
+  after = after.replace(/^---\s*\n?/, "");
+  return before + (after ? "\n\n---\n\n" + after : "");
+}
+
+for (const dir of dirs) {
+  const pkgPath = path.join(utilsDir, dir, "package.json");
+  const readmePath = path.join(utilsDir, dir, "README.md");
+  if (!fs.existsSync(pkgPath) || !fs.existsSync(readmePath)) continue;
+
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  const name = pkg.name;
+  const npmName = name.replace("/", "%2f");
+  let readme = fs.readFileSync(readmePath, "utf8");
+
+  // Remove existing ## Installation / ## Install so we don't duplicate
+  readme = removeSection(readme, "## Installation");
+  readme = removeSection(readme, "## Install");
+
+  // Install block at the very top
+  const installBlock = `## Install
+
+**npm**
+\`\`\`bash
+npm install ${name}
+\`\`\`
+
+**GitHub** (from monorepo)
+\`\`\`bash
+git clone https://github.com/${REPO}.git && cd simpill/utils/${dir} && npm install && npm run build
+\`\`\`
+Then in your project: \`npm install /path/to/simpill/utils/${dir}\` or \`npm link\` from that directory.
+
+---
+
+`;
+
+  // Badges after first line (banner) if not already present
+  const npmBadge = `[![npm version](https://img.shields.io/npm/v/${npmName}.svg)](https://www.npmjs.com/package/${name})`;
+  const ghBadge = `[![GitHub](https://img.shields.io/badge/GitHub-source-blue?logo=github)](${REPO_URL}/tree/main/utils/${dir})`;
+  const badgeLine = `\n<p align="center">\n  ${npmBadge}\n  ${ghBadge}\n</p>\n`;
+
+  let out = installBlock + readme.trimStart();
+
+  if (!out.includes("img.shields.io/npm/v/")) {
+    const firstLineEnd = out.indexOf("\n");
+    out = out.slice(0, firstLineEnd + 1) + badgeLine + out.slice(firstLineEnd + 1);
+  }
+
+  fs.writeFileSync(readmePath, out, "utf8");
+  console.log("Updated:", dir);
+}
+
+console.log("Done.");

package/scripts/utils/utils-use-local-deps.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Rewrite each utils package to use file:../@simpill-<name>.utils for @simpill deps
+ * so that build/test use local packages. Run from repo root.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const REPO_ROOT = path.join(__dirname, "..", "..");
+const UTILS = path.join(REPO_ROOT, "utils");
+const OWNER = "SkinnnyJay";
+
+const dirs = fs
+  .readdirSync(UTILS, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && d.name.startsWith("@simpill-") && d.name.endsWith(".utils"))
+  .map((d) => d.name)
+  .sort();
+
+let changed = 0;
+for (const dir of dirs) {
+  const pkgPath = path.join(UTILS, dir, "package.json");
+  if (!fs.existsSync(pkgPath)) continue;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+  for (const key of ["dependencies", "devDependencies"]) {
+    const section = pkg[key];
+    if (!section || typeof section !== "object") continue;
+    for (const [name, spec] of Object.entries(section)) {
+      if (!name.startsWith("@simpill/") || typeof spec !== "string") continue;
+      const m = spec.match(/^github:([^/]+)\/(.+)$/);
+      if (m && m[1] === OWNER && m[2].endsWith(".utils")) {
+        const depDir = `@simpill-${m[2]}`;
+        if (depDir !== dir && dirs.includes(depDir)) {
+          section[name] = `file:../${depDir}`;
+          changed++;
+        }
+      }
+    }
+  }
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+}
+console.log("Updated", changed, "dependency entries to file:../ in utils packages.");
+process.exit(0);

package/scripts/utils/utils-verify-all.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# =============================================================================
+# Verify all utils – build and test every package under utils/@simpill-*.utils
+# =============================================================================
+# Run from repo root: ./scripts/utils/utils-verify-all.sh
+# Exits 0 if all packages build and test pass; 1 otherwise.
+# =============================================================================
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+FAILED_BUILD=()
+FAILED_TEST=()
+
+for d in utils/@simpill-*.utils; do
+  name=$(basename "$d")
+  if (cd "$d" && npm run build --silent 2>&1) >/dev/null; then
+    echo "  build $name ✓"
+  else
+    echo "  build $name ✗"
+    FAILED_BUILD+=("$name")
+  fi
+  if (cd "$d" && npm test --silent 2>&1) >/dev/null; then
+    echo "  test  $name ✓"
+  else
+    echo "  test  $name ✗"
+    FAILED_TEST+=("$name")
+  fi
+done
+
+echo ""
+echo "============================================"
+echo "Verify all utils – summary"
+echo "============================================"
+if [ ${#FAILED_BUILD[@]} -eq 0 ] && [ ${#FAILED_TEST[@]} -eq 0 ]; then
+  echo "All packages: build and test passed."
+  echo "============================================"
+  exit 0
+fi
+[ ${#FAILED_BUILD[@]} -gt 0 ] && echo "Build failed: ${FAILED_BUILD[*]}"
+[ ${#FAILED_TEST[@]} -gt 0 ] && echo "Test failed:  ${FAILED_TEST[*]}"
+echo "============================================"
+exit 1

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "resolveJsonModule": true
+  },
+  "include": ["index.ts", "scripts/**/*.js", "__tests__/**/*.ts"],
+  "exclude": ["node_modules", "utils"]
+}