@tailglow/cli 0.6.5 → 0.8.1

package/README.md

@@ -1,8 +1,8 @@
 # @tailglow/cli
 
-`tglow` is the Tailglow command line. Every command is generated from the API's own routes and
-validations, so the CLI, the docs site, `llms.txt` and the in-product AI assistant all describe the
-same API by construction.
+`tglow` is the Tailglow command line. API resource commands are generated from the API's own
+routes and validations, so the CLI, docs site and in-product AI assistant describe the same API.
+Local commands also support sign-in, bundled documentation and file imports.
 
 ```bash
 npm install -g @tailglow/cli
@@ -10,7 +10,7 @@ tglow login
 tglow projects list
 ```
 
-Node 18.3 or newer. `bun add -g` and `pnpm add -g` work the same way.
+Node 22 or newer. `bun add -g` and `pnpm add -g` work the same way.
 
 Prefer a shorter name? Alias it rather than installing over one:
 
@@ -33,8 +33,8 @@ tglow metrics create --project prj_x --name "API Latency" --view-id view_x
 tglow metrics delete --project prj_x --metric-id met_x
 ```
 
-Field names are snake_case on the wire and kebab-case on the command line: `time_window_minutes`
-becomes `--time-window-minutes`. Object and array fields take JSON:
+Field names are snake_case on the wire and kebab-case on the command line: `repeat_window_minutes`
+becomes `--repeat-window-minutes`. Object and array fields take JSON:
 
 ```bash
 tglow views create-join --project prj_x --joins '[{"view_id":"view_b","on":"user_id"}]'
@@ -135,8 +135,89 @@ Pages print as markdown even when piped; `--json` returns `{ path, url, content
 bun run tglow <resource> <command>   # run from source, without installing
 bun run test:cli                     # unit tests, no network
 bun run build:llms                   # regenerate src/commands.generated.js and src/docs.generated.js
+bun run build:import                 # regenerate the bundled importer and its XML worker
 ```
 
 `src/commands.generated.js` and `src/docs.generated.js` are written by `scripts/build/llms.build.js`
 and are never edited by hand. Adding a route to the API adds its command here with no change to this
-package, and editing a guide changes the bundled page the same way.
+package, and editing a guide changes the bundled page the same way. `src/import.generated.js`, its
+declarations and `src/import-worker.generated.js` are self-contained bundles of the workspace
+importer written by `scripts/build/import.build.js`.
+
+## Import files
+
+Scan and validate locally without credentials:
+
+```bash
+tglow import scan export.xml
+tglow import scan export.xml --record-path /HealthData/Record --full
+tglow import validate events.jsonl --timestamp-field /event/created_at
+```
+
+Content detection supports XML, JSONL, JSON, CSV and TSV; use `--format` to resolve ambiguity.
+Scan defaults to a bounded sample, reports its coverage, and discovers literal XML element paths.
+XML automatically imports every direct child of the document root, including different record
+types. Root attributes and meaningful direct text become a separate document record; a root-only
+document becomes one record. `--record-path` is an optional filter for importing just part of a
+file. Rows preserve the `{name, attributes, children}` tree, strings, qualified names and child
+order. Line-break indentation in element-only containers is removed. Mixed text, inline spaces,
+whitespace-only values, CDATA, character references and inherited `xml:space="preserve"` stay intact;
+formatting separators between top-level records are omitted.
+There is no Apple-specific flattening. DTDs use the documented ignore profile; declarations are not
+applied and declared entities are not expanded. JSON documents have a 50 MiB limit; the other
+formats stream in bounded memory. Every serialized row must fit within 1 MiB including its
+newline.
+
+Upload using an exact project, source and ingest key, with normal CLI authentication:
+
+```bash
+tglow import events.jsonl --project prj_x --source-id src_x --ingest-key-id ik_x --collection events
+```
+
+Alternatively pass an explicit `--ingest-url` containing its key and `--project prj_x` to verify
+the expected project. Treat the URL as a credential: passing it on the command line exposes it
+to shell history and process listings. The CLI never prints the URL or API credential. The
+project can come from the existing environment/config default; `--project-id` is an alias for
+`--project`. Source and ingest-key IDs never default or select themselves. A localhost API cannot
+automatically direct an upload to a remote URL; use an explicit ingest URL for that destination.
+
+Upload reads a bounded preview, checks destination readiness, then validates records and sends
+batches as it reads. It holds one file descriptor and checks for file changes before every request
+and at EOF. These checks detect ordinary replacement, edits, append and truncation; they are not
+an immutable snapshot guarantee. Do not edit the input during import. No full temporary copy is
+needed by default. A late parse error can leave earlier batches accepted.
+
+Add `--validate-first` to copy the file into a private temporary directory and check the whole
+snapshot before any upload. This needs free temporary disk space approximately equal to the input
+size. The same snapshot is used for checking and delivery, then removed on completion, failure or
+graceful Ctrl-C. A cleanup failure is reported separately as `cleanup_error` and a warning; it does
+not change delivery status or acknowledged counts. Changes to the original after copying do not change the uploaded bytes. A failed
+full check sends no rows; successful checking cannot prevent a later delivery failure.
+
+`--timestamp-field` accepts a JSON pointer or an exact top-level field name. Source fields remain
+unchanged; the selected value sets request-level `ts`. Missing, invalid or timezone-ambiguous
+values fail validation. Selected dates must be between 1970-01-01 UTC and the current time, since earlier or future ingest timestamps cannot be preserved by the server. No timestamp field is selected automatically. Batches split whenever
+the exact parsed timestamp changes, which can produce one request per row, and otherwise stay
+within 500 rows and 1 MiB.
+
+Only HTTP 202 acknowledges a batch. Upload stops on rejection or uncertain delivery and never
+retries automatically. The report includes `accepted_count` and the affected batch's inclusive
+`first_row`/`last_row`; these indices refer to the selected output rows, not physical file lines.
+A timeout, cancellation during a request, or missing acknowledgement may mean that batch arrived.
+Do not blindly rerun a partial upload: import idempotency is not provided yet.
+
+Full scans, validation and upload read large XML files with worker threads. `--workers auto`, the
+default, starts two for files of 32 MiB or more on machines with at least four logical processors;
+`--workers 0` reads on the main thread, and `--workers 1` to `16` sets the count for any XML file.
+Each pass checks that its workers start and answer before reading, falls back to the main thread
+if they cannot, and reports what ran on stderr (`XML workers: 2.`). Reports, rows, batches and
+errors are identical with any worker count; JSONL, JSON, CSV, TSV and sampled scans read on the
+main thread.
+
+Progress is written to stderr. In `--json` mode or when piped, import always writes its final
+JSON report to stdout, including failures and partial uploads. `total_rows` is `null` until a full
+check or clean EOF establishes it. `accepted_count` counts only acknowledged rows. The `outcome`
+field distinguishes validation failures, changed files, destination failures, rejected batches,
+uncertain delivery and cancellation. Exit code is 0 on success, 1 on
+failure, and 130 after cancellation. Other CLI commands retain the standard failure-to-stderr
+behavior described above. See `tglow import --help` for all flags.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailglow/cli",
-  "version": "0.6.5",
+  "version": "0.8.1",
   "type": "module",
   "description": "The Tailglow command line. Every command is generated from the Tailglow API reference, so the CLI and the documentation can never describe different APIs.",
   "bin": {
@@ -15,7 +15,7 @@
     "src"
   ],
   "engines": {
-    "node": ">=18.3.0"
+    "node": ">=22.0.0"
   },
   "homepage": "https://docs.tailglow.io",
   "bugs": {