@notionhive/core 0.1.0

package/lib/add-component.js

@@ -0,0 +1,72 @@
+const fs = require("fs");
+const path = require("path");
+const { copyDirectory, pathExists } = require("./copy");
+const { rewriteImports } = require("./rewrite-imports");
+const { parseSharedImports } = require("./parse-imports");
+const { resolvePaths } = require("./paths");
+const { copySharedTree } = require("./copy-shared");
+
+async function addComponent({
+  registryEntry,
+  sourceRoot,
+  targetDir,
+  force = false,
+}) {
+  const paths = resolvePaths(targetDir);
+  const componentSource = path.join(
+    sourceRoot,
+    "components",
+    "organisms",
+    registryEntry.folderName
+  );
+  const componentTarget = path.join(paths.componentsDir, registryEntry.folderName);
+
+  if (!(await pathExists(componentSource))) {
+    throw new Error(`Component source not found: ${componentSource}`);
+  }
+
+  await fs.promises.mkdir(paths.componentsDir, { recursive: true });
+
+  await copyDirectory(componentSource, componentTarget, {
+    force,
+    transformFile: (content) => rewriteImports(content),
+  });
+
+  const sharedImports = parseSharedImports(
+    await fs.promises.readFile(
+      path.join(componentSource, `${registryEntry.folderName}.jsx`),
+      "utf8"
+    )
+  );
+
+  const copiedShared = await copySharedTree({
+    sharedPaths: sharedImports,
+    sourceRoot,
+    sharedDir: paths.sharedDir,
+    targetDir: paths.targetDir,
+    force,
+  });
+
+  const copiedAssets = [];
+
+  if (registryEntry.assets) {
+    const assetSource = path.join(sourceRoot, registryEntry.assets);
+    const assetTarget = path.join(paths.targetDir, registryEntry.assets);
+
+    if (await pathExists(assetSource)) {
+      await copyDirectory(assetSource, assetTarget, { force });
+      copiedAssets.push(path.relative(paths.targetDir, assetTarget));
+    }
+  }
+
+  return {
+    componentPath: path.relative(paths.targetDir, componentTarget),
+    sharedPaths: copiedShared,
+    assetPaths: copiedAssets,
+    importLine: `import { ${registryEntry.exportName} } from "${paths.importPrefix}/${registryEntry.folderName}";`,
+  };
+}
+
+module.exports = {
+  addComponent,
+};

package/lib/category-cli.js

@@ -0,0 +1,166 @@
+const fs = require("fs");
+const path = require("path");
+const { addComponent } = require("./add-component");
+const { findLibraryRoot } = require("./paths");
+
+function createCategoryCli(categoryConfig) {
+  return async function runCategoryCli(packageRoot, argv = process.argv.slice(2)) {
+    const REGISTRY_DIR = path.join(packageRoot, "registry");
+    const {
+      packageName,
+      binName,
+      label,
+      labelPlural,
+      exampleId,
+    } = categoryConfig;
+
+    function printHelp() {
+      console.log(`${packageName}
+
+Add editable ${label} source into your Next.js project.
+
+Usage:
+  npx ${packageName} add <${label}-id> [--dir <path>] [--force]
+  npx ${packageName} list
+
+Examples:
+  npx ${packageName} add ${exampleId}
+  npx ${packageName} add ${exampleId} --dir ../client-site
+  npx ${packageName} list
+`);
+    }
+
+    function loadRegistry() {
+      const indexPath = path.join(REGISTRY_DIR, "index.json");
+      return JSON.parse(fs.readFileSync(indexPath, "utf8"));
+    }
+
+    function resolveSourceRoot() {
+      const fromCwd = findLibraryRoot(process.cwd());
+      if (fromCwd) {
+        return fromCwd;
+      }
+
+      const bundledTemplates = path.join(packageRoot, "templates");
+      if (fs.existsSync(path.join(bundledTemplates, "components", "organisms"))) {
+        return bundledTemplates;
+      }
+
+      throw new Error(
+        `Could not locate component source. Run from the component library repo, or install a published ${packageName} package with bundled templates.`
+      );
+    }
+
+    function parseArgs(args) {
+      const tokens = [...args];
+      const command = tokens.shift();
+
+      if (!command || command === "--help" || command === "-h") {
+        return { command: "help" };
+      }
+
+      if (command === "list") {
+        return { command: "list" };
+      }
+
+      if (command !== "add") {
+        return { command: "unknown", raw: command };
+      }
+
+      const id = tokens.shift();
+      let targetDir = process.cwd();
+      let force = false;
+
+      while (tokens.length > 0) {
+        const flag = tokens.shift();
+        if (flag === "--dir") {
+          targetDir = tokens.shift();
+          continue;
+        }
+        if (flag === "--force") {
+          force = true;
+          continue;
+        }
+        throw new Error(`Unknown flag: ${flag}`);
+      }
+
+      if (!id) {
+        throw new Error(`Missing ${label} id. Example: ${exampleId}`);
+      }
+
+      return { command: "add", id, targetDir, force };
+    }
+
+    async function runList() {
+      const registry = loadRegistry();
+      console.log(`Available ${labelPlural}:\n`);
+      for (const entry of registry.items) {
+        console.log(`  ${entry.id.padEnd(16)} ${entry.exportName}${entry.assets ? " (assets)" : ""}`);
+      }
+      console.log(`\nInstall: npx ${packageName} add ${exampleId}`);
+    }
+
+    async function runAdd({ id, targetDir, force }) {
+      const registry = loadRegistry();
+      const entry = registry.items.find((item) => item.id === id);
+
+      if (!entry) {
+        throw new Error(`Unknown ${label} id "${id}". Run "${binName} list" to see options.`);
+      }
+
+      const sourceRoot = resolveSourceRoot();
+      const result = await addComponent({
+        registryEntry: entry,
+        sourceRoot,
+        targetDir,
+        force,
+      });
+
+      console.log(`Added ${entry.exportName} to ${path.resolve(targetDir)}\n`);
+      console.log("Files:");
+      console.log(`  ${result.componentPath}/`);
+      for (const sharedPath of result.sharedPaths) {
+        console.log(`  ${sharedPath}`);
+      }
+      for (const assetPath of result.assetPaths) {
+        console.log(`  ${assetPath}/`);
+      }
+
+      console.log("\nImport:");
+      console.log(`  ${result.importLine}\n`);
+      console.log("Requirements: Next.js 16+, Tailwind CSS v4, prop-types");
+    }
+
+    try {
+      const parsed = parseArgs(argv);
+
+      if (parsed.command === "help") {
+        printHelp();
+        return;
+      }
+
+      if (parsed.command === "unknown") {
+        throw new Error(`Unknown command "${parsed.raw}"`);
+      }
+
+      if (parsed.command === "list") {
+        await runList();
+        return;
+      }
+
+      if (parsed.command === "add") {
+        await runAdd(parsed);
+        return;
+      }
+
+      printHelp();
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  };
+}
+
+module.exports = {
+  createCategoryCli,
+};

package/lib/copy-shared.js

@@ -0,0 +1,147 @@
+const fs = require("fs");
+const path = require("path");
+const { copyDirectory, pathExists } = require("./copy");
+const { rewriteImports } = require("./rewrite-imports");
+const { parseSharedImports } = require("./parse-imports");
+
+function sharedTargetPath(sharedDir, sharedPath) {
+  const [category, ...rest] = sharedPath.split("/");
+
+  if (category === "atoms") {
+    return path.join(sharedDir, rest.join("/"));
+  }
+
+  if (category === "hooks") {
+    return path.join(sharedDir, "hooks", rest.join("/"));
+  }
+
+  if (category === "molecules") {
+    return path.join(sharedDir, "molecules", rest.join("/"));
+  }
+
+  return path.join(sharedDir, sharedPath.replace(/\//g, "-"));
+}
+
+function sharedSourcePath(sourceRoot, sharedPath) {
+  const [category, ...rest] = sharedPath.split("/");
+
+  if (category === "hooks") {
+    return path.join(sourceRoot, "components", "hooks", `${rest.join("/")}.js`);
+  }
+
+  return path.join(sourceRoot, "components", category, ...rest);
+}
+
+async function copySharedFile(sourceFile, targetFile, force) {
+  if (await pathExists(targetFile)) {
+    return path.relative(path.dirname(targetFile), targetFile);
+  }
+
+  await fs.promises.mkdir(path.dirname(targetFile), { recursive: true });
+
+  if (await pathExists(sourceFile)) {
+    const content = await fs.promises.readFile(sourceFile, "utf8");
+    await fs.promises.writeFile(targetFile, rewriteImports(content), "utf8");
+    return targetFile;
+  }
+
+  throw new Error(`Shared file not found: ${sourceFile}`);
+}
+
+async function copySharedDependency({
+  sharedPath,
+  sourceRoot,
+  sharedDir,
+  targetDir,
+  force,
+  copied,
+  copiedPaths,
+}) {
+  if (copied.has(sharedPath)) {
+    return;
+  }
+
+  copied.add(sharedPath);
+
+  const source = sharedSourcePath(sourceRoot, sharedPath);
+  const target = sharedTargetPath(sharedDir, sharedPath);
+  const [category] = sharedPath.split("/");
+
+  if (category === "hooks") {
+    await copySharedFile(source, `${target}.js`, force);
+    copiedPaths.push(path.relative(targetDir, `${target}.js`));
+    return;
+  }
+
+  if (!(await pathExists(source))) {
+    throw new Error(`Shared dependency not found: ${source}`);
+  }
+
+  if (await pathExists(target)) {
+    copiedPaths.push(path.relative(targetDir, target));
+  } else {
+    await copyDirectory(source, target, {
+      force,
+      transformFile: (content) => rewriteImports(content),
+    });
+    copiedPaths.push(path.relative(targetDir, target));
+  }
+
+  const mainFile = path.join(target, `${path.basename(target)}.jsx`);
+  let parseSource = "";
+
+  if (await pathExists(mainFile)) {
+    parseSource = await fs.promises.readFile(mainFile, "utf8");
+  } else if (await pathExists(`${target}.js`)) {
+    parseSource = await fs.promises.readFile(`${target}.js`, "utf8");
+  } else {
+    const entries = await fs.promises.readdir(target);
+    const jsxFile = entries.find((name) => name.endsWith(".jsx"));
+    if (jsxFile) {
+      parseSource = await fs.promises.readFile(path.join(target, jsxFile), "utf8");
+    }
+  }
+
+  for (const nestedSharedPath of parseSharedImports(parseSource)) {
+    await copySharedDependency({
+      sharedPath: nestedSharedPath,
+      sourceRoot,
+      sharedDir,
+      targetDir,
+      force,
+      copied,
+      copiedPaths,
+    });
+  }
+}
+
+async function copySharedTree({
+  sharedPaths,
+  sourceRoot,
+  sharedDir,
+  targetDir,
+  force,
+}) {
+  const copied = new Set();
+  const copiedPaths = [];
+
+  for (const sharedPath of sharedPaths) {
+    await copySharedDependency({
+      sharedPath,
+      sourceRoot,
+      sharedDir,
+      targetDir,
+      force,
+      copied,
+      copiedPaths,
+    });
+  }
+
+  return [...new Set(copiedPaths)];
+}
+
+module.exports = {
+  copySharedTree,
+  sharedSourcePath,
+  sharedTargetPath,
+};

package/lib/copy.js

@@ -0,0 +1,58 @@
+const fs = require("fs");
+const path = require("path");
+
+async function pathExists(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyDirectory(source, destination, options = {}) {
+  const { force = false, transformFile } = options;
+
+  if (!(await pathExists(source))) {
+    throw new Error(`Source not found: ${source}`);
+  }
+
+  if (await pathExists(destination)) {
+    if (!force) {
+      throw new Error(`Destination already exists: ${destination} (use --force to overwrite)`);
+    }
+    await fs.promises.rm(destination, { recursive: true, force: true });
+  }
+
+  await fs.promises.mkdir(destination, { recursive: true });
+
+  const entries = await fs.promises.readdir(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name.endsWith(".stories.jsx")) {
+      continue;
+    }
+
+    const srcPath = path.join(source, entry.name);
+    const destPath = path.join(destination, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath, options);
+      continue;
+    }
+
+    if (typeof transformFile === "function") {
+      const input = await fs.promises.readFile(srcPath, "utf8");
+      const output = transformFile(input, srcPath);
+      await fs.promises.writeFile(destPath, output, "utf8");
+      continue;
+    }
+
+    await fs.promises.copyFile(srcPath, destPath);
+  }
+}
+
+module.exports = {
+  pathExists,
+  copyDirectory,
+};

package/lib/index.js

@@ -0,0 +1,18 @@
+const { addComponent } = require("./add-component");
+const { copyDirectory } = require("./copy");
+const { copySharedTree } = require("./copy-shared");
+const { createCategoryCli } = require("./category-cli");
+const { findLibraryRoot, resolvePaths } = require("./paths");
+const { rewriteImports } = require("./rewrite-imports");
+const { parseSharedImports } = require("./parse-imports");
+
+module.exports = {
+  addComponent,
+  copyDirectory,
+  copySharedTree,
+  createCategoryCli,
+  findLibraryRoot,
+  resolvePaths,
+  rewriteImports,
+  parseSharedImports,
+};

package/lib/parse-imports.js

@@ -0,0 +1,34 @@
+const SHARED_DEPENDENCY_ROOTS = {
+  SafeImage: "atoms/SafeImage",
+  useCarousel: "hooks/useCarousel",
+};
+
+function parseSharedImports(source) {
+  const deps = new Set();
+
+  const relativePattern =
+    /from\s+["'](?:\.\.\/)+(atoms|hooks|molecules)\/([^"']+)["']/g;
+  let match = relativePattern.exec(source);
+
+  while (match) {
+    deps.add(`${match[1]}/${match[2]}`);
+    match = relativePattern.exec(source);
+  }
+
+  return [...deps];
+}
+
+function sharedFolderName(relativePath) {
+  if (relativePath === "atoms/SafeImage") return "SafeImage";
+  if (relativePath === "hooks/useCarousel") return "hooks/useCarousel";
+  if (relativePath.startsWith("molecules/")) {
+    return `molecules/${relativePath.split("/")[1]}`;
+  }
+  return relativePath.replace(/\//g, "-");
+}
+
+module.exports = {
+  SHARED_DEPENDENCY_ROOTS,
+  parseSharedImports,
+  sharedFolderName,
+};

package/lib/paths.js

@@ -0,0 +1,44 @@
+const fs = require("fs");
+const path = require("path");
+
+const SHARED_MAP = {
+  "atoms/SafeImage": "_shared/SafeImage",
+  "hooks/useCarousel": "_shared/hooks/useCarousel",
+};
+
+function findLibraryRoot(startDir) {
+  let current = startDir;
+  while (current !== path.dirname(current)) {
+    const componentsDir = path.join(current, "components", "organisms");
+    if (fs.existsSync(componentsDir)) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function resolvePaths(targetDir, options = {}) {
+  const componentsDir = path.join(targetDir, "components");
+  const publicDir = path.join(targetDir, "public");
+
+  return {
+    targetDir: path.resolve(targetDir),
+    componentsDir,
+    sharedDir: path.join(componentsDir, "_shared"),
+    publicDir,
+    importPrefix: options.importPrefix ?? "@/components",
+  };
+}
+
+function mapSharedPath(relativeImportPath) {
+  const normalized = relativeImportPath.replace(/\\/g, "/");
+  return SHARED_MAP[normalized] ?? null;
+}
+
+module.exports = {
+  SHARED_MAP,
+  findLibraryRoot,
+  resolvePaths,
+  mapSharedPath,
+};

package/lib/rewrite-imports.js

@@ -0,0 +1,20 @@
+function rewriteImports(source) {
+  return source.replace(
+    /from\s+["'](?:\.\.\/)+(atoms|hooks|molecules)\/([^"']+)["']/g,
+    (_match, category, rest) => {
+      if (category === "atoms") {
+        return `from "@/components/_shared/${rest}"`;
+      }
+
+      if (category === "hooks") {
+        return `from "@/components/_shared/hooks/${rest}"`;
+      }
+
+      return `from "@/components/_shared/molecules/${rest}"`;
+    }
+  );
+}
+
+module.exports = {
+  rewriteImports,
+};

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@notionhive/core",
+  "version": "0.1.0",
+  "description": "Shared utilities for @notionhive category CLIs (copy editable source into projects).",
+  "license": "UNLICENSED",
+  "main": "./lib/index.js",
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}