Add external file listing, asset/attachment folder APIs, and refactor CreateFolderPath

- Add vxcore_folder_list_external API to list unindexed files/folders in bundled notebooks
- Add FolderManager::GetPublicAssetsFolder, GetPublicAttachmentsFolder, GetAssetsFolder, GetAttachmentsFolder for resolving asset/attachment paths
- Move CreateFolderPath from Notebook to FolderManager for better cohesion
- Add IsSingleName utility to check if path has no separators
- Skip assets/attachments folders when listing external nodes
- Extract kMetadataFolderName constant in BundledNotebook

Author: tamlok

include/vxcore/vxcore.h

@@ -108,6 +108,16 @@ VXCORE_API VxCoreError vxcore_folder_list_children(VxCoreContextHandle context,
                                                    const char *notebook_id,
                                                    const char *folder_path,
                                                    char **out_children_json);
+
+// List external (unindexed) nodes in a folder.
+// External nodes exist on filesystem but are not tracked in metadata.
+// folder_path: Path relative to notebook root ("" or "." for root)
+// Output JSON: {"files": [...], "folders": [...]}
+// Each entry contains only "name" field (no ID since not indexed).
+VXCORE_API VxCoreError vxcore_folder_list_external(VxCoreContextHandle context,
+                                                   const char *notebook_id,
+                                                   const char *folder_path,
+                                                   char **out_external_json);
 // ============ File Operations ============
 VXCORE_API VxCoreError vxcore_file_create(VxCoreContextHandle context, const char *notebook_id,
                                           const char *folder_path, const char *file_name,

src/CMakeLists.txt

@@ -24,6 +24,7 @@ set(VXCORE_SOURCES
     core/notebook_manager.cpp
     core/folder.cpp
     core/bundled_folder_manager.cpp
+    core/folder_manager.cpp
     core/raw_folder_manager.cpp
     db/db_manager.cpp
     db/file_db.cpp

src/api/vxcore_folder_api.cpp

@@ -63,7 +63,7 @@ VXCORE_API VxCoreError vxcore_folder_create_path(VxCoreContextHandle context,
     }
 
     std::string folder_id;
-    VxCoreError error = notebook->CreateFolderPath(folder_path, folder_id);
+    VxCoreError error = notebook->GetFolderManager()->CreateFolderPath(folder_path, folder_id);
     if (error != VXCORE_OK) {
       return error;
     }
@@ -248,6 +248,70 @@ VXCORE_API VxCoreError vxcore_folder_list_children(VxCoreContextHandle context,
   }
 }
 
+VXCORE_API VxCoreError vxcore_folder_list_external(VxCoreContextHandle context,
+                                                   const char *notebook_id,
+                                                   const char *folder_path,
+                                                   char **out_external_json) {
+  if (!context || !notebook_id || !out_external_json) {
+    return VXCORE_ERR_INVALID_PARAM;
+  }
+
+  vxcore::VxCoreContext *ctx = reinterpret_cast<vxcore::VxCoreContext *>(context);
+
+  try {
+    vxcore::Notebook *notebook = ctx->notebook_manager->GetNotebook(notebook_id);
+    if (!notebook) {
+      ctx->last_error = "Notebook not found";
+      return VXCORE_ERR_NOT_FOUND;
+    }
+
+    vxcore::FolderManager *folder_manager = notebook->GetFolderManager();
+    if (!folder_manager) {
+      ctx->last_error = "FolderManager not available";
+      return VXCORE_ERR_INVALID_STATE;
+    }
+
+    std::string path = folder_path ? folder_path : ".";
+    vxcore::FolderManager::FolderContents contents;
+
+    VxCoreError error = folder_manager->ListExternalNodes(path, contents);
+    if (error != VXCORE_OK) {
+      return error;
+    }
+
+    // Build JSON response
+    nlohmann::json result;
+    nlohmann::json files_json = nlohmann::json::array();
+    nlohmann::json folders_json = nlohmann::json::array();
+
+    for (const auto &file : contents.files) {
+      // External files only have name (no ID)
+      nlohmann::json file_json;
+      file_json["name"] = file.name;
+      file_json["type"] = "file";
+      files_json.push_back(file_json);
+    }
+
+    for (const auto &folder : contents.folders) {
+      // External folders only have name (no ID)
+      nlohmann::json folder_json;
+      folder_json["name"] = folder.name;
+      folder_json["type"] = "folder";
+      folders_json.push_back(folder_json);
+    }
+
+    result["files"] = files_json;
+    result["folders"] = folders_json;
+
+    *out_external_json = vxcore_strdup(result.dump().c_str());
+    return VXCORE_OK;
+  } catch (const std::exception &e) {
+    ctx->last_error = std::string("Exception: ") + e.what();
+    return VXCORE_ERR_UNKNOWN;
+  }
+}
+
+
 VXCORE_API VxCoreError vxcore_file_import(VxCoreContextHandle context, const char *notebook_id,
                                           const char *folder_path, const char *external_file_path,
                                           char **out_file_id) {

src/core/bundled_folder_manager.cpp

@@ -9,7 +9,7 @@
 #include <unordered_set>
 
 #include "metadata_store.h"
-#include "notebook.h"
+#include "bundled_notebook.h"
 #include "utils/file_utils.h"
 #include "utils/logger.h"
 #include "utils/utils.h"
@@ -1870,10 +1870,6 @@ VxCoreError BundledFolderManager::ImportFolder(const std::string &dest_folder_pa
             continue;
           }
           if (entry.is_directory()) {
-            // Skip vx_notebook metadata folder
-            if (entry_name == "vx_notebook") {
-              continue;
-            }
             copy_filtered(entry.path(), dest / entry_name);
           } else if (entry.is_regular_file()) {
             // Apply suffix filter if allowlist is specified
@@ -1923,14 +1919,15 @@ VxCoreError BundledFolderManager::ImportFolder(const std::string &dest_folder_pa
   std::function<VxCoreError(const std::string &, FolderConfig &)> index_contents =
       [&](const std::string &rel_path, FolderConfig &config) -> VxCoreError {
     std::string abs_path = GetContentPath(rel_path);
+    const bool is_root = (rel_path.empty() || rel_path == ".");
 
     try {
       for (const auto &entry : fs::directory_iterator(abs_path)) {
         std::string entry_name = entry.path().filename().string();
 
         if (entry.is_directory()) {
-          // Skip hidden folders and vx_notebook metadata folder
-          if (entry_name.empty() || entry_name[0] == '.' || entry_name == "vx_notebook") {
+          if (entry_name.empty() || entry_name[0] == '.' ||
+              (is_root && entry_name == BundledNotebook::kMetadataFolderName)) {
             continue;
           }
 
@@ -2230,4 +2227,97 @@ VxCoreError BundledFolderManager::UnindexNode(const std::string &node_path) {
   VXCORE_LOG_WARN("UnindexNode: Node not found in metadata: %s", clean_path.c_str());
   return VXCORE_ERR_NOT_FOUND;
 }
+
+VxCoreError BundledFolderManager::ListExternalNodes(const std::string &folder_path,
+                                                   FolderContents &out_contents) {
+  const auto clean_path = GetCleanRelativePath(folder_path);
+  VXCORE_LOG_INFO("ListExternalNodes: path=%s", clean_path.c_str());
+
+  // Clear output
+  out_contents.files.clear();
+  out_contents.folders.clear();
+
+  // Get folder config (indexed items)
+  FolderConfig *config = nullptr;
+  VxCoreError error = GetFolderConfig(clean_path, &config);
+  if (error != VXCORE_OK) {
+    VXCORE_LOG_ERROR("ListExternalNodes: Failed to get folder config: path=%s, error=%d",
+                     clean_path.c_str(), error);
+    return error;
+  }
+
+  // Build sets of indexed items for fast lookup
+  std::set<std::string> indexed_files;
+  std::set<std::string> indexed_folders;
+  for (const auto &file : config->files) {
+    indexed_files.insert(file.name);
+  }
+  for (const auto &folder_name : config->folders) {
+    indexed_folders.insert(folder_name);
+  }
+
+  // Get filesystem content path
+  std::string content_path = GetContentPath(clean_path);
+  if (!fs::exists(content_path)) {
+    VXCORE_LOG_WARN("ListExternalNodes: Content path does not exist: %s", content_path.c_str());
+    return VXCORE_ERR_NOT_FOUND;
+  }
+
+  // Check if assets/attachments folders should be skipped (only if single name)
+  const NotebookConfig &nb_config = notebook_->GetConfig();
+  const bool need_check_assets_folder = IsSingleName(nb_config.assets_folder);
+  const bool need_check_attachments_folder = IsSingleName(nb_config.attachments_folder);
+
+  const bool is_root = clean_path.empty() || clean_path == ".";
+
+  // Scan filesystem and find unindexed items
+  try {
+    for (const auto &entry : fs::directory_iterator(content_path)) {
+      std::string entry_name = entry.path().filename().string();
+
+      // Skip hidden files/folders (starting with '.')
+      if (entry_name.empty() || entry_name[0] == '.') {
+        continue;
+      }
+
+      // Skip metadata folder (only at root)
+      if (is_root && entry_name == BundledNotebook::kMetadataFolderName) {
+        continue;
+      }
+
+      // Skip assets and attachments folders
+      if ((need_check_assets_folder && entry_name == nb_config.assets_folder) ||
+          (need_check_attachments_folder && entry_name == nb_config.attachments_folder)) {
+        continue;
+      }
+
+      if (entry.is_directory()) {
+        // Check if folder is NOT indexed
+        if (indexed_folders.find(entry_name) == indexed_folders.end()) {
+          // External folder - create a minimal FolderRecord
+          FolderRecord record;
+          record.name = entry_name;
+          // No ID since it's not indexed
+          out_contents.folders.push_back(record);
+        }
+      } else if (entry.is_regular_file()) {
+        // Check if file is NOT indexed
+        if (indexed_files.find(entry_name) == indexed_files.end()) {
+          // External file - create a minimal FileRecord
+          FileRecord record;
+          record.name = entry_name;
+          // No ID since it's not indexed
+          out_contents.files.push_back(record);
+        }
+      }
+    }
+  } catch (const std::exception &e) {
+    VXCORE_LOG_ERROR("ListExternalNodes: Failed to iterate directory: %s", e.what());
+    return VXCORE_ERR_IO;
+  }
+
+  VXCORE_LOG_INFO("ListExternalNodes: Found %zu external files, %zu external folders",
+                  out_contents.files.size(), out_contents.folders.size());
+  return VXCORE_OK;
+}
 }  // namespace vxcore

src/core/bundled_folder_manager.h

@@ -93,6 +93,9 @@ class BundledFolderManager : public FolderManager {
 
   VxCoreError UnindexNode(const std::string &node_path) override;
 
+  VxCoreError ListExternalNodes(const std::string &folder_path,
+                                FolderContents &out_contents) override;
+
   // Syncs the MetadataStore from config files (vx.json)
   // Called on notebook open to rebuild cache from ground truth
   // Returns VXCORE_OK on success

src/core/bundled_notebook.cpp

@@ -9,6 +9,8 @@
 
 namespace vxcore {
 
+const char *BundledNotebook::kMetadataFolderName = "vx_notebook";
+
 BundledNotebook::BundledNotebook(const std::string &local_data_folder,
                                  const std::string &root_folder)
     : Notebook(local_data_folder, root_folder, NotebookType::Bundled) {
@@ -127,7 +129,7 @@ VxCoreError BundledNotebook::Open(const std::string &local_data_folder,
 }
 
 std::string BundledNotebook::GetMetadataFolder() const {
-  return ConcatenatePaths(root_folder_, "vx_notebook");
+  return ConcatenatePaths(root_folder_, kMetadataFolderName);
 }
 
 std::string BundledNotebook::GetConfigPath() const {

src/core/bundled_notebook.h

@@ -22,6 +22,8 @@ class BundledNotebook : public Notebook {
   std::string GetRecycleBinPath() const override;
   VxCoreError EmptyRecycleBin() override;
 
+  static const char *kMetadataFolderName;
+
  private:
   BundledNotebook(const std::string &local_data_folder, const std::string &root_folder);
 

src/core/folder_manager.cpp

@@ -0,0 +1,97 @@
+#include "folder_manager.h"
+
+#include <filesystem>
+
+namespace vxcore {
+
+VxCoreError FolderManager::CreateFolderPath(const std::string &folder_path,
+                                            std::string &out_folder_id) {
+  if (folder_path.empty()) {
+    return VXCORE_ERR_INVALID_PARAM;
+  }
+
+  std::vector<std::string> path_components = SplitPathComponents(folder_path);
+  if (path_components.empty()) {
+    return VXCORE_ERR_INVALID_PARAM;
+  }
+
+  std::string current_parent = ".";
+  std::string folder_id;
+
+  for (size_t i = 0; i < path_components.size(); ++i) {
+    const std::string &folder_name = path_components[i];
+    if (folder_name.empty()) {
+      return VXCORE_ERR_INVALID_PARAM;
+    }
+
+    VxCoreError err = CreateFolder(current_parent, folder_name, folder_id);
+    if (err != VXCORE_OK && err != VXCORE_ERR_ALREADY_EXISTS) {
+      return err;
+    }
+
+    current_parent = ConcatenatePaths(current_parent, folder_name);
+  }
+
+  out_folder_id = folder_id;
+  return VXCORE_OK;
+}
+
+std::string FolderManager::GetPublicAssetsFolder(const std::string &file_path) const {
+  const NotebookConfig &config = notebook_->GetConfig();
+  const std::string &assets_folder = config.assets_folder;
+
+  // If absolute path, return as-is
+  if (!IsRelativePath(assets_folder)) {
+    return CleanPath(assets_folder);
+  }
+
+  // Get parent folder of the file
+  auto [parent_path, _] = SplitPath(file_path);
+  std::string abs_parent = notebook_->GetAbsolutePath(parent_path);
+
+  // Resolve relative to file's parent folder
+  return CleanFsPath(std::filesystem::path(abs_parent) / assets_folder);
+}
+
+std::string FolderManager::GetPublicAttachmentsFolder(const std::string &file_path) const {
+  const NotebookConfig &config = notebook_->GetConfig();
+  const std::string &attachments_folder = config.attachments_folder;
+
+  // If absolute path, return as-is
+  if (!IsRelativePath(attachments_folder)) {
+    return CleanPath(attachments_folder);
+  }
+
+  // Get parent folder of the file
+  auto [parent_path, _] = SplitPath(file_path);
+  std::string abs_parent = notebook_->GetAbsolutePath(parent_path);
+
+  // Resolve relative to file's parent folder
+  return CleanFsPath(std::filesystem::path(abs_parent) / attachments_folder);
+}
+
+std::string FolderManager::GetAssetsFolder(const std::string &file_path) {
+  // Get file's UUID
+  const FileRecord *record = nullptr;
+  VxCoreError err = GetFileInfo(file_path, &record);
+  if (err != VXCORE_OK || !record) {
+    return "";
+  }
+
+  std::string public_folder = GetPublicAssetsFolder(file_path);
+  return ConcatenatePaths(public_folder, record->id);
+}
+
+std::string FolderManager::GetAttachmentsFolder(const std::string &file_path) {
+  // Get file's UUID
+  const FileRecord *record = nullptr;
+  VxCoreError err = GetFileInfo(file_path, &record);
+  if (err != VXCORE_OK || !record) {
+    return "";
+  }
+
+  std::string public_folder = GetPublicAttachmentsFolder(file_path);
+  return ConcatenatePaths(public_folder, record->id);
+}
+
+}  // namespace vxcore