@songmu/mdhq 0.0.3 → 0.0.4

package/README.md

@@ -30,10 +30,13 @@ mdhq root
 
 `mdhq get` accepts multiple URLs as arguments or one URL per line on standard
 input; both sources are merged. It prints one absolute Markdown path per URL
-to stdout by default. Warnings are written to stderr. `--json` returns one
-result object for a single URL, or an array for multiple URLs. Requests are
-limited to eight in parallel, with requests to the same host serialized and
-spaced one second apart; image downloads use the same limits.
+to stdout by default. Warnings are written to stderr. `--json` writes one
+compact JSON result object per URL as JSON Lines. Results are written as soon
+as each URL finishes, so parallel requests can produce output in completion
+order rather than input order. If a later request fails, results already
+written to stdout remain available.
+Requests are limited to eight in parallel, with requests to the same host
+serialized and spaced one second apart; image downloads use the same limits.
 
 `mdhq list` recursively lists `.md` files below the storage root, one per
 line, in sorted root-relative form. Use `-p` or `--full-path` to print absolute

package/dist/cli.js

@@ -69,7 +69,7 @@ export function createProgram(io = process) {
         .option("--update", "update an existing page")
         .option("--user-agent <value>", "HTTP User-Agent")
         .option("--header <header>", "additional HTTP header", collect, [])
-        .addOption(new Option("--json", "print a structured result"))
+        .addOption(new Option("--json", "print results as JSON Lines"))
         .action(async (urls, options) => {
         const inputUrls = await readStdinUrls(io.stdin);
         const requestedUrls = [...(urls ?? []), ...inputUrls]
@@ -79,7 +79,6 @@ export function createProgram(io = process) {
             throw new MdhqError("INVALID_URL", "At least one URL is required");
         }
         const scheduler = new RequestScheduler();
-        const results = [];
         let nextIndex = 0;
         const worker = async () => {
             while (nextIndex < requestedUrls.length) {
@@ -89,7 +88,7 @@ export function createProgram(io = process) {
                 if (url === undefined) {
                     continue;
                 }
-                results[index] = await getPage({
+                const result = await getPage({
                     url,
                     ...(options.root ? { root: options.root } : {}),
                     ...(options.assets === false ? { assets: false } : {}),
@@ -99,12 +98,21 @@ export function createProgram(io = process) {
                     scheduler,
                     onWarning: (warning) => io.stderr.write(`warning: ${warning.message}\n`)
                 });
+                io.stdout.write(`${options.json ? JSON.stringify(result) : result.path}\n`);
             }
         };
-        await Promise.all(Array.from({ length: Math.min(8, requestedUrls.length) }, () => worker()));
-        io.stdout.write(options.json
-            ? `${JSON.stringify(results.length === 1 ? results[0] : results, null, 2)}\n`
-            : `${results.map((result) => result.path).join("\n")}\n`);
+        const failures = [];
+        await Promise.all(Array.from({ length: Math.min(8, requestedUrls.length) }, async () => {
+            try {
+                await worker();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }));
+        if (failures.length > 0) {
+            throw failures[0];
+        }
     });
     program
         .command("list")

package/docs/specification.md

@@ -21,13 +21,13 @@ Runtime requirements:
 The executable provides three subcommands:
 
 ```text
-mdhq get [options] <url>
+mdhq get [options] [urls...]
 mdhq list [options]
 mdhq root [options]
 ```
 
-`mdhq get` accepts exactly one URL per invocation. Parallel or multi-URL
-processing is delegated to external tools such as `xargs`.
+`mdhq get` accepts multiple URL arguments and one URL per line from standard
+input. Both sources are merged, and up to eight URLs are processed in parallel.
 
 ### `get` options
 
@@ -37,22 +37,19 @@ processing is delegated to external tools such as `xargs`.
 | `--update` | Fetch and replace an existing document with the same URL identity. |
 | `--user-agent <value>` | Override the default HTTP User-Agent. |
 | `--header <header>` | Add an HTTP header. The option is repeatable and uses `Name: value` syntax. |
-| `--json` | Write a structured result instead of only the Markdown path. |
-
-On success without `--json`, stdout contains exactly one absolute Markdown
-path followed by a newline. Warnings are written to stderr.
-
-With `--json`, stdout contains an object with this shape:
-
-```json
-{
-  "requestedUrl": "https://example.com/start",
-  "sourceUrl": "https://example.com/article",
-  "path": "/data/mdhq/example.com/article.md",
-  "status": "saved",
-  "assets": [],
-  "warnings": []
-}
+| `--json` | Write one result per line as JSON Lines instead of only the Markdown path. |
+
+Without `--json`, stdout receives one absolute Markdown path per requested URL,
+with each path followed by a newline. Each result is written as soon as that
+URL finishes, so parallel requests can produce output in completion order
+rather than input order.
+Warnings are written to stderr.
+
+With `--json`, stdout contains one compact JSON object per requested URL,
+also written as soon as the URL finishes. Each line has this shape:
+
+```jsonl
+{"requestedUrl":"https://example.com/start","sourceUrl":"https://example.com/article","path":"/data/mdhq/example.com/article.md","status":"saved","assets":[],"warnings":[]}
 ```
 
 `status` is one of:
@@ -63,7 +60,8 @@ With `--json`, stdout contains an object with this shape:
   body, including an HTTP 304 response.
 - `skipped`: an existing same-identity file was kept.
 
-An error is written to stderr and causes exit status `1`.
+An error is written to stderr and causes exit status `1`. Results written to
+stdout before the error remain available to downstream consumers.
 
 ### `list`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@songmu/mdhq",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Save web pages as Markdown in a ghq-inspired filesystem layout.",
   "type": "module",
   "bin": {
@@ -69,6 +69,6 @@
     "@types/node": "^26.4.0",
     "@types/proper-lockfile": "4.1.4",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   }
 }