Add tsfile-cli: inspect and import .tsfile from the command line

.gitignore

@@ -47,8 +47,19 @@ build/*
 cpp/third_party/zlib-1.3.1/treebuild.xml
 cpp/third_party/zlib-1.3.1/zlib-1.3.1/treebuild.xml
 
-# Claude Code
-.claude/settings.local.json
-.claude/todos/
-.claude/worktrees/
-.claude/scheduled_tasks.json
+# Claude Code (local AI tooling — not uploaded; skill lives in cpp/tools/skills)
+.claude/
+
+# CodeGraph local index
+.codegraph/
+
+# Test-run artifacts (temp .tsfile/.dat written to the working dir or repo root)
+cpp/cwrapper_*.tsfile
+cpp/tsfile_writer_*.tsfile
+cpp/*.dat
+/*.tsfile
+/*.dat
+
+# AI workflow artifacts (kept local, not uploaded)
+docs/superpowers/
+/QA_Log.md

cpp/CMakeLists.txt

@@ -190,6 +190,9 @@ endif ()
 option(BUILD_TEST "Build tests" ON)
 message("cmake using: BUILD_TEST=${BUILD_TEST}")
 
+option(BUILD_TOOLS "Build the tsfile command-line tools" ON)
+message("cmake using: BUILD_TOOLS=${BUILD_TOOLS}")
+
 option(ENABLE_ANTLR4 "Enable ANTLR4 runtime" ON)
 message("cmake using: ENABLE_ANTLR4=${ENABLE_ANTLR4}")
 
@@ -262,6 +265,9 @@ endif ()
 add_subdirectory(third_party)
 
 add_subdirectory(src)
+if (BUILD_TOOLS)
+    add_subdirectory(tools)
+endif ()
 if (BUILD_TEST)
     add_subdirectory(test)
     if (TESTS_ENABLED)
@@ -272,4 +278,3 @@ else()
 endif ()
 
 add_subdirectory(examples)
-

cpp/src/file/read_file.cc

@@ -21,6 +21,8 @@
 
 #include <fcntl.h>
 #include <sys/stat.h>
+
+#include <iostream>
 #ifdef _WIN32
 #include <io.h>
 #include <windows.h>
@@ -49,10 +51,8 @@ int ReadFile::open(const std::string& file_path) {
     file_path_ = file_path;
     fd_ = ::open(file_path_.c_str(), O_RDONLY);
     if (fd_ < 0) {
-        std::cout << "open file " << file_path << "  error :" << fd_
-                  << std::endl;
-        std::cout << "open error" << errno << "  " << strerror(errno)
-                  << std::endl;
+        std::cerr << "open file " << file_path << " error: " << strerror(errno)
+                  << " (errno " << errno << ")" << std::endl;
         return E_FILE_OPEN_ERR;
     }
 

cpp/test/CMakeLists.txt

@@ -110,6 +110,33 @@ if (${DOWNLOADED})
     endif ()
     add_subdirectory("${GTEST_SRC_ROOT}" "${CMAKE_BINARY_DIR}/googletest-build"
             EXCLUDE_FROM_ALL)
+    # AppleClang searches /usr/local/include before CMake's generated -isystem
+    # paths, so a system-installed GTest can shadow the vendored headers. Force
+    # the vendored include dirs ahead for GTest's own sources here; the same is
+    # done for the consuming TsFile_Test target below (where header resolution
+    # actually matters for the test code).
+    foreach (GTEST_TARGET gtest gtest_main gmock gmock_main)
+        if (TARGET ${GTEST_TARGET})
+            target_include_directories(${GTEST_TARGET} BEFORE PRIVATE
+                    ${GTEST_SRC_ROOT}/googletest/include
+                    ${GTEST_SRC_ROOT}/googletest
+                    ${GTEST_SRC_ROOT}/googlemock/include
+                    ${GTEST_SRC_ROOT}/googlemock)
+            if (APPLE AND NOT MSVC)
+                target_compile_options(${GTEST_TARGET} BEFORE PRIVATE
+                        -iquote${GTEST_SRC_ROOT}/googletest/include
+                        -iquote${GTEST_SRC_ROOT}/googletest
+                        -I${GTEST_SRC_ROOT}/googletest/include
+                        -I${GTEST_SRC_ROOT}/googletest
+                        -std=c++14)
+            endif ()
+        endif ()
+    endforeach ()
+    # Remember the vendored GTest header roots so they can be forced ahead of any
+    # system installation when compiling TsFile_Test itself.
+    set(VENDORED_GTEST_INCLUDE_DIRS
+            ${GTEST_SRC_ROOT}/googletest/include
+            ${GTEST_SRC_ROOT}/googlemock/include)
     set(TESTS_ENABLED ON PARENT_SCOPE)
 else ()
     message(WARNING "Failed to download googletest from all provided URLs, setting TESTS_ENABLED to OFF")
@@ -186,6 +213,11 @@ if (ENABLE_ZLIB)
     list(APPEND TEST_SRCS ${ZLIB_TEST_SRCS})
 endif()
 
+if (BUILD_TOOLS)
+    file(GLOB_RECURSE TOOLS_TEST_SRCS "tools/*_test.cc")
+    list(APPEND TEST_SRCS ${TOOLS_TEST_SRCS})
+endif ()
+
 if (${COV_ENABLED})
     message("Enable code cov...")
     add_compile_options(-fprofile-arcs -ftest-coverage)
@@ -197,12 +229,27 @@ if (ENABLE_ANTLR4)
 endif()
 
 add_executable(TsFile_Test ${TEST_SRCS})
+# Force the vendored GTest headers ahead of any system installation so the test
+# code reliably compiles against the vendored 1.12.1 headers.
+if (VENDORED_GTEST_INCLUDE_DIRS)
+    target_include_directories(TsFile_Test BEFORE PRIVATE
+            ${VENDORED_GTEST_INCLUDE_DIRS})
+endif ()
+if (BUILD_TOOLS)
+    target_include_directories(TsFile_Test PRIVATE ${CMAKE_SOURCE_DIR}/tools)
+endif ()
+if (APPLE AND NOT MSVC)
+    target_compile_options(TsFile_Test PRIVATE -std=c++14)
+endif ()
 target_link_libraries(
         TsFile_Test
         GTest::gtest_main
         GTest::gmock
         tsfile
 )
+if (BUILD_TOOLS)
+    target_link_libraries(TsFile_Test tsfile_cli_obj)
+endif ()
 
 set_target_properties(TsFile_Test PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${LIB_TSFILE_SDK_DIR})
 
@@ -232,4 +279,4 @@ if(WIN32)
   gtest_discover_tests(TsFile_Test DISCOVERY_MODE PRE_TEST DISCOVERY_TIMEOUT 120)
 else()
   gtest_discover_tests(TsFile_Test)
-endif()
+endif()

cpp/test/tools/cli_args_test.cc

@@ -0,0 +1,182 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * License); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "cli/cli_args.h"
+
+#include <gtest/gtest.h>
+
+#include <sstream>
+
+#include "cli/run_cli.h"
+
+TEST(RunCliTest, VersionFlagPrintsVersionAndReturnsOk) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"--version"}, out, err);
+    EXPECT_EQ(code, 0);
+    EXPECT_NE(out.str().find("tsfile"), std::string::npos);
+    EXPECT_TRUE(err.str().empty());
+}
+
+TEST(RunCliTest, NoArgsPrintsUsageToErrAndReturnsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Usage"), std::string::npos);
+}
+
+TEST(RunCliTest, UnknownCommandIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"frobnicate", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Unknown command"), std::string::npos);
+}
+
+TEST(RunCliTest, LeadingOptionBeforeCommandIsClearError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"-f", "json", "meta", "data.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("command must come before options"),
+              std::string::npos)
+        << err.str();
+}
+
+TEST(ParseArgsTest, CommandAndFilePositional) {
+    auto p = tsfile_cli::parse_args({"ls", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "ls");
+    EXPECT_EQ(p.file, "data.tsfile");
+}
+
+TEST(ParseArgsTest, FormatFlagParsed) {
+    auto p = tsfile_cli::parse_args({"cat", "-f", "json", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.format, tsfile_cli::ParsedArgs::Format::kJson);
+}
+
+TEST(ParseArgsTest, MeasurementsSplitOnComma) {
+    auto p = tsfile_cli::parse_args({"cat", "-m", "s1,s2,s3", "data.tsfile"});
+    ASSERT_EQ(p.measurements.size(), 3u);
+    EXPECT_EQ(p.measurements[1], "s2");
+}
+
+TEST(ParseArgsTest, LimitOffsetAndTimeRange) {
+    auto p =
+        tsfile_cli::parse_args({"head", "-n", "5", "--offset", "2", "--start",
+                                "100", "--end", "200", "data.tsfile"});
+    EXPECT_EQ(p.limit, 5);
+    EXPECT_EQ(p.offset, 2);
+    EXPECT_TRUE(p.has_start);
+    EXPECT_EQ(p.start, 100);
+    EXPECT_TRUE(p.has_end);
+    EXPECT_EQ(p.end, 200);
+}
+
+TEST(ParseArgsTest, UnknownFlagIsError) {
+    auto p = tsfile_cli::parse_args({"ls", "--bogus", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, BadFormatValueIsError) {
+    auto p = tsfile_cli::parse_args({"cat", "-f", "yaml", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, MissingFileIsAllowedAtParseTime) {
+    auto p = tsfile_cli::parse_args({"ls"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "ls");
+    EXPECT_TRUE(p.file.empty());
+}
+
+TEST(ParseArgsTest, WriteFlagsParsed) {
+    auto p = tsfile_cli::parse_args({"write", "--table", "t1", "--columns",
+                                     "s1:INT64:field", "-o", "out.tsfile", "-v",
+                                     "--header-match", "in.csv"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "write");
+    EXPECT_EQ(p.table, "t1");
+    EXPECT_EQ(p.columns, "s1:INT64:field");
+    EXPECT_EQ(p.output, "out.tsfile");
+    EXPECT_TRUE(p.verbose);
+    EXPECT_TRUE(p.header_match);
+    EXPECT_EQ(p.file, "in.csv");
+}
+
+TEST(ParseArgsTest, OutputFlagNeedsValue) {
+    auto p = tsfile_cli::parse_args({"write", "-o"});
+    EXPECT_FALSE(p.error.empty());
+}
+
+TEST(ParseArgsTest, DashIsStdinPositional) {
+    auto p =
+        tsfile_cli::parse_args({"write", "--table", "t1", "--columns",
+                                "s1:INT64:field", "-o", "out.tsfile", "-"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.file, "-");
+}
+
+TEST(ParseArgsTest, SeedFlagParsed) {
+    auto p = tsfile_cli::parse_args(
+        {"sample", "-m", "s1", "-n", "3", "--seed", "42", "data.tsfile"});
+    EXPECT_TRUE(p.error.empty());
+    EXPECT_EQ(p.command, "sample");
+    EXPECT_EQ(p.limit, 3);
+    EXPECT_TRUE(p.has_seed);
+    EXPECT_EQ(p.seed, 42);
+}
+
+TEST(ParseArgsTest, BadSeedValueIsError) {
+    auto p = tsfile_cli::parse_args(
+        {"sample", "--seed", "not_a_number", "data.tsfile"});
+    EXPECT_FALSE(p.error.empty());
+    EXPECT_NE(p.error.find("Invalid --seed"), std::string::npos);
+}
+
+TEST(RunCliTest, SelectIsNoLongerKnownCommand) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code = tsfile_cli::run_cli({"select", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("Unknown command"), std::string::npos);
+}
+
+TEST(RunCliTest, SeedOnCatIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"cat", "--seed", "7", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--seed is only valid for sample"),
+              std::string::npos);
+}
+
+TEST(RunCliTest, OffsetOnSampleIsUsageError) {
+    std::ostringstream out;
+    std::ostringstream err;
+    int code =
+        tsfile_cli::run_cli({"sample", "--offset", "2", "x.tsfile"}, out, err);
+    EXPECT_EQ(code, 1);
+    EXPECT_NE(err.str().find("--offset is not valid for sample"),
+              std::string::npos);
+}