@simpill/utils 1.0.0

package/scripts/github/github-set-all-topics.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Set GitHub repository topics for this monorepo and all @simpill package repos
+ * listed in package.json dependencies. Uses gh API (requires gh CLI authenticated).
+ * Run from repo root.
+ */
+
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+const PACKAGE_JSON = path.join(REPO_ROOT, "package.json");
+const TOPICS_FILE = path.join(REPO_ROOT, ".github", "TOPICS.md");
+const MAX_TOPICS = 20;
+const ACCEPT_HEADER = "Accept: application/vnd.github.mercy-preview+json";
+
+const { BASE_TOPICS, PACKAGE_TOPICS } = require("../lib/package-topics.js");
+
+function run(cmd, options = {}) {
+  try {
+    return execSync(cmd, { encoding: "utf8", ...options });
+  } catch (e) {
+    if (options.ignoreStderr) return e.stdout || "";
+    throw e;
+  }
+}
+
+function getTopicsFromTopicsFile() {
+  const content = fs.readFileSync(TOPICS_FILE, "utf8");
+  const names = [];
+  const re = /^\s*-\s*`([^`]+)`/gm;
+  let m;
+  while ((m = re.exec(content)) !== null) names.push(m[1]);
+  return names.slice(0, MAX_TOPICS);
+}
+
+function setRepoTopics(repo, names) {
+  const payload = JSON.stringify({ names });
+  run(
+    `gh api -X PUT -H "${ACCEPT_HEADER}" "repos/${repo}/topics" --input -`,
+    { input: payload, cwd: REPO_ROOT }
+  );
+}
+
+function getRepoTopics(repo) {
+  const out = run(
+    `gh api "repos/${repo}/topics" -H "${ACCEPT_HEADER}" -q '.names[]'`,
+    { cwd: REPO_ROOT, ignoreStderr: true }
+  );
+  return out
+    .trim()
+    ? out.trim().split("\n").filter(Boolean)
+    : [];
+}
+
+function getPackageRepos() {
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON, "utf8"));
+  const repos = [];
+  const deps = { ...pkg.dependencies, ...(pkg.devDependencies || {}) };
+  for (const spec of Object.values(deps)) {
+    const match = spec && spec.match(/github:([^#]+)/);
+    if (match) repos.push(match[1]);
+  }
+  return [...new Set(repos)];
+}
+
+function topicsForPackageRepo(repoName) {
+  // repoName is like "SkinnnyJay/env.utils" -> package "env.utils"
+  const packageName = repoName.split("/").pop();
+  const extra = PACKAGE_TOPICS[packageName] || [packageName.replace(".utils", "")];
+  const combined = [...BASE_TOPICS, ...extra];
+  return [...new Set(combined)].slice(0, MAX_TOPICS);
+}
+
+function main() {
+  const dryRun = process.argv.includes("--dry-run");
+  const onlyPackages = process.argv.includes("--packages-only");
+
+  console.log("Setting GitHub topics for @simpill repos...\n");
+
+  // 1) This monorepo (e.g. SkinnnyJay/simpill-utils)
+  if (!onlyPackages) {
+    const repo = run("gh repo view --json nameWithOwner -q .nameWithOwner", {
+      cwd: REPO_ROOT,
+      encoding: "utf8",
+    }).trim();
+    const topics = getTopicsFromTopicsFile();
+    console.log(`${repo}: ${topics.length} topics`);
+    if (dryRun) {
+      console.log("  (dry run)", topics.join(", "));
+    } else {
+      setRepoTopics(repo, topics);
+      console.log("  Set:", getRepoTopics(repo).join(", "));
+    }
+    console.log("");
+  }
+
+  // 2) Package repos from package.json
+  const packageRepos = getPackageRepos();
+  console.log(`Found ${packageRepos.length} package repos in package.json\n`);
+
+  for (const repo of packageRepos) {
+    const topics = topicsForPackageRepo(repo);
+    process.stdout.write(`${repo}: ${topics.length} topics ... `);
+    if (dryRun) {
+      console.log("(dry run)", topics.join(", "));
+      continue;
+    }
+    try {
+      setRepoTopics(repo, topics);
+      const current = getRepoTopics(repo);
+      console.log("OK:", current.slice(0, 8).join(", ") + (current.length > 8 ? "..." : ""));
+    } catch (e) {
+      console.log("FAIL:", e.message.split("\n")[0]);
+    }
+  }
+}
+
+main();

package/scripts/github/github-set-repo-topics.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Set this repository's GitHub topics from .github/TOPICS.md using the GitHub API.
+# Requires: gh CLI (authenticated), jq. GitHub allows at most 20 topics.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+TOPICS_FILE="${REPO_ROOT}/.github/TOPICS.md"
+MAX_TOPICS=20
+
+if [[ ! -f "$TOPICS_FILE" ]]; then
+  echo "Missing $TOPICS_FILE" >&2
+  exit 1
+fi
+
+# Extract topic names from lines like: - `topic-name`
+topics_raw=$(grep -E '^\s*-\s*`[^`]+`' "$TOPICS_FILE" | sed -n 's/.*`\([^`]*\)`.*/\1/p')
+# Take first MAX_TOPICS (GitHub limit)
+topics_list=$(echo "$topics_raw" | head -n "$MAX_TOPICS" | jq -R -s -c 'split("\n") | map(select(length > 0))')
+
+payload=$(jq -n --argjson names "$topics_list" '{ names: $names }')
+
+cd "$REPO_ROOT"
+repo=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+
+echo "Setting ${repo} topics (from .github/TOPICS.md, max ${MAX_TOPICS})..."
+gh api -X PUT \
+  -H "Accept: application/vnd.github.mercy-preview+json" \
+  "repos/${repo}/topics" \
+  --input - <<< "$payload"
+echo "Done. Current topics:"
+gh api "repos/${repo}/topics" -H "Accept: application/vnd.github.mercy-preview+json" -q '.names[]' | paste -sd ' ' -
+echo

package/scripts/github/github-set-repos-public.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Set each @simpill package GitHub repo from private to public.
+# Usage: run from repo root. Requires: gh CLI. Set GITHUB_OWNER if not using your user.
+#   DRY_RUN=1 ./scripts/github/github-set-repos-public.sh   # list only, no changes
+set -euo pipefail
+
+GITHUB_OWNER="${GITHUB_OWNER:-$(gh api user -q .login 2>/dev/null || echo '')}"
+if [[ -z "$GITHUB_OWNER" ]]; then
+  echo "Error: Could not get GitHub user. Run: gh auth login or set GITHUB_OWNER"
+  exit 1
+fi
+
+REPOS=(
+  adapters.utils
+  algorithms.utils
+  annotations.utils
+  api.utils
+  array.utils
+  async.utils
+  cache.utils
+  collections.utils
+  crypto.utils
+  data.utils
+  env.utils
+  enum.utils
+  errors.utils
+  events.utils
+  factories.utils
+  file.utils
+  function.utils
+  http.utils
+  logger.utils
+  middleware.utils
+  misc.utils
+  nextjs.utils
+  number.utils
+  object.utils
+  observability.utils
+  patterns.utils
+  protocols.utils
+  react.utils
+  request-context.utils
+  resilience.utils
+  socket.utils
+  string.utils
+  test.utils
+  time.utils
+  token-optimizer.utils
+  uuid.utils
+  zod.utils
+  zustand.utils
+)
+
+echo "Owner: $GITHUB_OWNER"
+[[ -n "${DRY_RUN:-}" ]] && echo "DRY RUN (no visibility changes)"
+
+for repo in "${REPOS[@]}"; do
+  full="$GITHUB_OWNER/$repo"
+  if ! gh repo view "$full" &>/dev/null; then
+    echo "Skip $full (repo not found)"
+    continue
+  fi
+  if [[ -n "${DRY_RUN:-}" ]]; then
+    echo "Would set $full -> public"
+    continue
+  fi
+  gh repo edit "$full" --visibility public --accept-visibility-change-consequences
+  echo "Set $full to public"
+done
+
+echo "Done."

package/scripts/lib/package-topics.js

@@ -0,0 +1,57 @@
+/**
+ * Shared package → topics/keywords for GitHub topics and npm package.json keywords.
+ * Used by github-set-all-topics.js and utils-set-npm-keywords.js.
+ */
+
+const BASE_TOPICS = [
+  "simpill",
+  "typescript",
+  "utilities",
+  "type-safe",
+  "esm",
+  "tree-shakeable",
+];
+
+/** Package short name (e.g. env.utils) → extra topics for that package */
+const PACKAGE_TOPICS = {
+  "adapters.utils": ["adapters", "nodejs"],
+  "algorithms.utils": ["algorithms", "nodejs"],
+  "annotations.utils": ["annotations", "metadata", "nodejs"],
+  "api.utils": ["api", "http", "nodejs"],
+  "array.utils": ["array", "nodejs"],
+  "async.utils": ["async", "promises", "nodejs"],
+  "cache.utils": ["cache", "nodejs"],
+  "collections.utils": ["collections", "data-structures", "nodejs"],
+  "crypto.utils": ["crypto", "security", "nodejs"],
+  "data.utils": ["data", "validation", "nodejs"],
+  "env.utils": ["env", "dotenv", "nodejs", "edge-runtime"],
+  "enum.utils": ["enum", "nodejs"],
+  "errors.utils": ["errors", "nodejs"],
+  "events.utils": ["events", "nodejs"],
+  "factories.utils": ["factories", "nodejs"],
+  "file.utils": ["file", "nodejs"],
+  "function.utils": ["function", "nodejs"],
+  "http.utils": ["http", "nodejs"],
+  "logger.utils": ["logging", "nodejs"],
+  "middleware.utils": ["middleware", "nodejs"],
+  "misc.utils": ["nodejs"],
+  "nextjs.utils": ["nextjs", "react", "nodejs"],
+  "number.utils": ["number", "nodejs"],
+  "object.utils": ["object", "nodejs"],
+  "observability.utils": ["observability", "logging", "nodejs"],
+  "patterns.utils": ["patterns", "nodejs"],
+  "protocols.utils": ["protocols", "nodejs"],
+  "react.utils": ["react", "nodejs"],
+  "request-context.utils": ["request-context", "nodejs"],
+  "resilience.utils": ["resilience", "nodejs"],
+  "socket.utils": ["socket", "websocket", "nodejs"],
+  "string.utils": ["string", "nodejs"],
+  "test.utils": ["testing", "nodejs"],
+  "time.utils": ["time", "date", "nodejs"],
+  "token-optimizer.utils": ["tokens", "nodejs"],
+  "uuid.utils": ["uuid", "nodejs"],
+  "zod.utils": ["zod", "validation", "nodejs"],
+  "zustand.utils": ["zustand", "react", "state", "nodejs"],
+};
+
+module.exports = { BASE_TOPICS, PACKAGE_TOPICS };

package/scripts/lib/publish-order.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Publish order and package.json rewrite for @simpill monorepo.
+ *
+ * Usage:
+ *   node publish-order.js order [REPO_ROOT]
+ *     Prints package directory names in topological publish order (one per line).
+ *
+ *   node publish-order.js rewrite <package-dir> [REPO_ROOT]
+ *     Reads package-dir/package.json, replaces file:../<x> with ^<version> for
+ *     @simpill deps, prints result to stdout. Use with backup/restore when publishing.
+ *
+ * REPO_ROOT defaults to parent of scripts/lib (repo root).
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_REPO_ROOT = path.resolve(__dirname, "../..");
+
+function getPackageDirs(utilsDir) {
+  const dirs = [];
+  try {
+    const entries = fs.readdirSync(utilsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory() && e.name.endsWith(".utils")) {
+        const pkgPath = path.join(utilsDir, e.name, "package.json");
+        if (fs.existsSync(pkgPath)) dirs.push(e.name);
+      }
+    }
+  } catch (err) {
+    console.error("Failed to read utils:", err.message);
+    process.exit(1);
+  }
+  return dirs.sort();
+}
+
+function readPackageJson(utilsDir, dir) {
+  const p = path.join(utilsDir, dir, "package.json");
+  const raw = fs.readFileSync(p, "utf8");
+  return { obj: JSON.parse(raw), raw };
+}
+
+function collectDeps(obj) {
+  const deps = [];
+  for (const key of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const section = obj[key];
+    if (!section || typeof section !== "object") continue;
+    for (const [name, value] of Object.entries(section)) {
+      if (name.startsWith("@simpill/") && typeof value === "string" && value.startsWith("file:../")) {
+        const depDir = value.replace(/^file:\.\.\//, "").replace(/\/$/, "");
+        if (depDir.endsWith(".utils")) deps.push(depDir);
+      }
+    }
+  }
+  return [...new Set(deps)];
+}
+
+function topologicalOrder(utilsDir) {
+  const dirs = getPackageDirs(utilsDir);
+  const dirToDeps = new Map();
+  for (const dir of dirs) {
+    const { obj } = readPackageJson(utilsDir, dir);
+    const depDirs = collectDeps(obj).filter((d) => dirs.includes(d));
+    dirToDeps.set(dir, depDirs);
+  }
+  // inDegree[dir] = number of @simpill deps (must publish deps before dir)
+  const inDegree = new Map();
+  for (const dir of dirs) inDegree.set(dir, dirToDeps.get(dir).length);
+  const order = [];
+  let queue = dirs.filter((d) => inDegree.get(d) === 0);
+  while (queue.length) {
+    const d = queue.shift();
+    order.push(d);
+    for (const [dir, deps] of dirToDeps) {
+      if (deps.includes(d)) {
+        const newDeg = inDegree.get(dir) - 1;
+        inDegree.set(dir, newDeg);
+        if (newDeg === 0) queue.push(dir);
+      }
+    }
+  }
+  const remaining = dirs.filter((d) => !order.includes(d));
+  if (remaining.length) {
+    console.error("Circular dependency among:", remaining.join(", "));
+    process.exit(1);
+  }
+  return order;
+}
+
+function rewritePackageJsonForPublish(utilsDir, packageDir) {
+  const packagePath = path.join(utilsDir, packageDir, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    console.error("Not found:", packagePath);
+    process.exit(1);
+  }
+  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  const dirs = getPackageDirs(utilsDir);
+  const versions = new Map();
+  for (const d of dirs) {
+    const obj = JSON.parse(fs.readFileSync(path.join(utilsDir, d, "package.json"), "utf8"));
+    if (obj.name && obj.version) versions.set(obj.name, obj.version);
+  }
+  for (const key of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const section = pkg[key];
+    if (!section || typeof section !== "object") continue;
+    for (const [name, value] of Object.entries(section)) {
+      if (name.startsWith("@simpill/") && typeof value === "string" && value.startsWith("file:../")) {
+        const ver = versions.get(name);
+        if (ver) section[name] = `^${ver}`;
+      }
+    }
+  }
+  return JSON.stringify(pkg, null, 2);
+}
+
+const cmd = process.argv[2];
+const repoRoot = cmd === "rewrite" ? (process.argv[4] || DEFAULT_REPO_ROOT) : (process.argv[3] || DEFAULT_REPO_ROOT);
+const utilsDir = path.join(repoRoot, "utils");
+
+if (cmd === "order") {
+  topologicalOrder(utilsDir).forEach((d) => console.log(d));
+} else if (cmd === "rewrite") {
+  const packageDir = process.argv[3];
+  if (!packageDir || !packageDir.endsWith(".utils")) {
+    console.error("Usage: node publish-order.js rewrite <package-dir> [REPO_ROOT]");
+    console.error("  package-dir must end with .utils (e.g. async.utils)");
+    process.exit(1);
+  }
+  const dirName = path.basename(packageDir);
+  if (!fs.existsSync(path.join(utilsDir, dirName, "package.json"))) {
+    console.error("Not found:", path.join(utilsDir, dirName, "package.json"));
+    process.exit(1);
+  }
+  console.log(rewritePackageJsonForPublish(utilsDir, dirName));
+} else {
+  console.error("Usage: node publish-order.js order [REPO_ROOT]");
+  console.error("       node publish-order.js rewrite <package-dir> [REPO_ROOT]");
+  process.exit(1);
+}

package/scripts/lib/sync-repo-links.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Set repository, homepage, and bugs to a single monorepo base for all utils packages.
+ * Run from repo root or with REPO_ROOT; writes in place. Commit after running.
+ *
+ * Usage:
+ *   REPO_BASE="https://github.com/owner/repo" [BRANCH=main] node scripts/lib/sync-repo-links.js
+ *
+ * REPO_BASE  Base URL without trailing slash (e.g. https://github.com/SkinnnyJay/simpill-utils).
+ * BRANCH     Default branch for homepage links (default: main).
+ *
+ * If REPO_BASE is not set, exits without changing anything.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_REPO_ROOT = path.resolve(__dirname, "../..");
+const REPO_ROOT = process.env.REPO_ROOT || DEFAULT_REPO_ROOT;
+const UTILS = path.join(REPO_ROOT, "utils");
+const REPO_BASE = process.env.REPO_BASE || "";
+const BRANCH = process.env.BRANCH || "main";
+
+if (!REPO_BASE) {
+  console.error("REPO_BASE is not set. Example:");
+  console.error('  REPO_BASE="https://github.com/SkinnnyJay/simpill-utils" BRANCH=main node scripts/lib/sync-repo-links.js');
+  process.exit(1);
+}
+
+const base = REPO_BASE.replace(/\/$/, "");
+const repoGit = base + ".git";
+const repoIssues = base + "/issues";
+
+let dirs;
+try {
+  dirs = fs.readdirSync(UTILS, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name.endsWith(".utils"))
+    .map((e) => e.name);
+} catch (err) {
+  console.error("Failed to read utils:", err.message);
+  process.exit(1);
+}
+
+let updated = 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"));
+  const repo = {
+    type: "git",
+    url: repoGit,
+    directory: dir,
+  };
+  const homepage = `${base}/tree/${BRANCH}/utils/${dir}#readme`;
+  const bugs = { url: repoIssues };
+  let changed = false;
+  if (JSON.stringify(pkg.repository) !== JSON.stringify(repo)) {
+    pkg.repository = repo;
+    changed = true;
+  }
+  if (pkg.homepage !== homepage) {
+    pkg.homepage = homepage;
+    changed = true;
+  }
+  if (JSON.stringify(pkg.bugs) !== JSON.stringify(bugs)) {
+    pkg.bugs = bugs;
+    changed = true;
+  }
+  if (changed) {
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+    console.log("Updated:", dir);
+    updated++;
+  }
+}
+console.log("Done. Updated", updated, "packages.");

package/scripts/monorepo/install-hooks.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Install git hooks at repo root. Pre-commit runs per-package checks when
+# utils/ is present. This script is the source of truth; generated hook
+# always uses a valid "then exit 1" block to avoid bash syntax errors.
+# =============================================================================
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+HOOKS_DIR="$REPO_ROOT/.git/hooks"
+
+if [ ! -d "$REPO_ROOT/.git" ] || [ ! -d "$HOOKS_DIR" ]; then
+  echo "Not a git repository or .git/hooks missing. Skipping hook installation."
+  exit 0
+fi
+
+# Package dir names from root package.json (@simpill/name.utils -> @simpill-name.utils)
+PKG_NAMES=""
+if [ -f "$REPO_ROOT/package.json" ]; then
+  PKG_NAMES=$(node -e "
+    const p = require('$REPO_ROOT/package.json');
+    const deps = p.dependencies || {};
+    const names = Object.keys(deps)
+      .filter(k => k.startsWith('@simpill/') && k.endsWith('.utils'))
+      .map(k => '@simpill-' + k.replace('@simpill/', '').replace('.utils', '') + '.utils');
+    console.log(names.sort().join('\n'));
+  " 2>/dev/null || true)
+fi
+
+# Build pre-commit hook. Each block must have "exit 1" in the then clause (no empty then).
+PRE_COMMIT="$HOOKS_DIR/pre-commit"
+cat > "$PRE_COMMIT" << 'HEADER'
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Package Pre-Commit Hook (generated by scripts/monorepo/install-hooks.sh)
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+HEADER
+
+while IFS= read -r dir; do
+  [ -z "$dir" ] && continue
+  # Use a single, valid block template: then clause always contains exit 1
+  name="${dir#@simpill-}"
+  name="${name%.utils}"
+  cat >> "$PRE_COMMIT" << BLOCK
+
+# --- BEGIN ${name}.utils ---
+if [ -f "\$REPO_ROOT/utils/${dir}/scripts/pre-commit.sh" ]; then
+  if git diff --cached --name-only | grep -q "^utils/${dir}/"; then
+    if ! "\$REPO_ROOT/utils/${dir}/scripts/pre-commit.sh"; then
+      exit 1
+    fi
+  fi
+fi
+# --- END ${name}.utils ---
+BLOCK
+done << EOF
+$PKG_NAMES
+EOF
+
+echo "exit 0" >> "$PRE_COMMIT"
+chmod +x "$PRE_COMMIT"
+echo "Git hooks installed (pre-commit)."

package/scripts/monorepo/monorepo-clean.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Clean monorepo root: node_modules, lockfile, and build artifacts.
+set -euo pipefail
+REPO_ROOT="${1:-$(cd "$(dirname "$0")/../.." && pwd)}"
+cd "$REPO_ROOT"
+rm -rf node_modules package-lock.json dist coverage .next .jest-cache 2>/dev/null || true
+echo "Monorepo root cleaned (node_modules, package-lock.json, dist, coverage, .next, .jest-cache)."

package/scripts/monorepo/monorepo-sync-deps.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * Sync monorepo root package.json @simpill dependencies to npm versions.
+ * If utils/@simpill-*.utils exists, uses each package's version (^version); otherwise uses ^1.0.0.
+ * Run from repo root. Use npm run use:local to switch to file:./utils/ for local development.
+ */
+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");
+
+function getPackageDirs() {
+  if (!fs.existsSync(UTILS)) return [];
+  return fs
+    .readdirSync(UTILS, { withFileTypes: true })
+    .filter(
+      (d) =>
+        d.isDirectory() &&
+        d.name.startsWith("@simpill-") &&
+        d.name.endsWith(".utils")
+    )
+    .map((d) => d.name)
+    .sort();
+}
+
+const dirs = getPackageDirs();
+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;
+  const version = (pkg.version && String(pkg.version).trim()) || "1.0.0";
+  if (name && name.startsWith("@simpill/")) {
+    deps[name] = `^${version}`;
+  }
+}
+
+// If no utils/ or empty, preserve existing @simpill names with ^1.0.0
+const rootPkg = JSON.parse(fs.readFileSync(ROOT_PKG, "utf8"));
+const existing = rootPkg.dependencies || {};
+if (Object.keys(deps).length === 0) {
+  for (const [name, spec] of Object.entries(existing)) {
+    if (name.startsWith("@simpill/")) {
+      const v = spec.match(/^\^?([0-9.]+)/);
+      deps[name] = v ? `^${v[1]}` : "^1.0.0";
+    }
+  }
+}
+
+const rootDeps = rootPkg.dependencies || {};
+let changed = false;
+for (const [name, spec] of Object.entries(deps)) {
+  if (rootDeps[name] !== spec) {
+    rootDeps[name] = spec;
+    changed = true;
+  }
+}
+const utilNames = new Set(Object.keys(deps));
+for (const name of Object.keys(rootDeps)) {
+  if (name.startsWith("@simpill/") && !utilNames.has(name)) {
+    delete rootDeps[name];
+    changed = true;
+  }
+}
+rootPkg.dependencies = rootDeps;
+
+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("Updated root package.json dependencies to npm versions.");
+} else {
+  console.log("Root package.json already in sync.");
+}
+console.log("Monorepo deps:", Object.keys(deps).length, "packages (npm ^version).");

package/scripts/monorepo/monorepo-verify-deps.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Verify all @simpill dependencies: resolve and load each package.
+ * Run from repo root after npm install.
+ */
+const path = require("path");
+const pkg = require(path.join(process.cwd(), "package.json"));
+const deps = Object.keys(pkg.dependencies || {}).filter((d) => d.startsWith("@simpill/"));
+
+let resolved = 0;
+let loaded = 0;
+const loadErrors = [];
+
+for (const d of deps) {
+  try {
+    require.resolve(d);
+    resolved++;
+  } catch (e) {
+    console.error("Resolve failed:", d, e.message);
+    continue;
+  }
+  try {
+    require(d);
+    loaded++;
+  } catch (e) {
+    loadErrors.push({ name: d, message: e.message });
+  }
+}
+
+console.log("Resolvable:", resolved + "/" + deps.length);
+console.log("Loadable (require):", loaded + "/" + deps.length);
+if (loadErrors.length > 0) {
+  console.error("Packages that did not load (may be ESM-only or need build):");
+  loadErrors.forEach(({ name, message }) => console.error("  ", name, message));
+}
+const ok = resolved === deps.length;
+process.exit(ok ? 0 : 1);