@url-sanitize/cli 0.1.0 → 0.1.2

package/LICENSE

@@ -19,9 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-Note: this MIT license applies to the @url-sanitize/core, @url-sanitize/cli,
-@url-sanitize/fetch, and @url-sanitize/action packages. The
-@url-sanitize/clearurls package ships a catalog derived from the ClearURLs
-ruleset and is licensed under LGPL-3.0-only for that bundled data. See
-packages/clearurls/LICENSE and docs/license-model.md for details.

package/README.md

@@ -1,6 +1,6 @@
 # @url-sanitize/cli
 
-Command-line URL sanitizer.
+Command-line tool for removing tracking parameters and unwrapping tracking redirects from URLs.
 
 ## Install
 
@@ -18,8 +18,15 @@ url-sanitize "https://example.com/?utm_source=x"
 
 url-sanitize --json "https://example.com/?utm_source=x"
 # {"kind":"cleaned","original":"...","url":"...","strippedParams":["utm_source"],"matchedRules":[...]}
+
+printf '%s\n' "https://example.com/?utm_source=x" | url-sanitize -
+# https://example.com/
 ```
 
+The npm CLI is pure TypeScript so it installs without native package setup. For
+the smallest standalone binary, use `cargo install url-sanitize` or the GitHub
+Release installer from the root README.
+
 ## License
 
 MIT.

package/dist/bin.js

@@ -1,53 +1,177 @@
 #!/usr/bin/env node
 
 // src/bin.ts
-import { clearurlsCatalog } from "@url-sanitize/clearurls";
+import { readFileSync } from "fs";
+import { createRequire } from "module";
+import { clearurlsCatalog, clearurlsMetadata } from "@url-sanitize/clearurls";
 import { compileSanitizer } from "@url-sanitize/core";
 var args = process.argv.slice(2);
-if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
-  printHelp();
-  process.exit(args.length === 0 ? 1 : 0);
+runTypeScriptCli(args);
+function runTypeScriptCli(rawArgs) {
+  if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
+    printHelp(process.stdout);
+    process.exit(0);
+  }
+  if (rawArgs.includes("--version")) {
+    process.stdout.write(
+      `url-sanitize ${packageVersion()} (catalog ${clearurlsMetadata.hash} ${clearurlsMetadata.fetchedAt})
+`
+    );
+    process.exit(0);
+  }
+  const parsed = parseArgs(rawArgs);
+  if (typeof parsed === "string") {
+    process.stderr.write(`error: ${parsed}
+`);
+    process.stderr.write("run `url-sanitize --help` for usage\n");
+    process.exit(1);
+  }
+  const sanitize = compileSanitizer(clearurlsCatalog, parsed.options);
+  let anyBlocked = false;
+  for (const url of parsed.urls) {
+    anyBlocked = emit(sanitize(url), parsed.json, parsed.explain) || anyBlocked;
+  }
+  if (parsed.readStdin || parsed.urls.length === 0 && !process.stdin.isTTY) {
+    const input = readAllStdin();
+    for (const line of input.split(/\r?\n/)) {
+      if (line.length === 0) continue;
+      anyBlocked = emit(sanitize(line), parsed.json, parsed.explain) || anyBlocked;
+    }
+  }
+  if (parsed.urls.length === 0 && !parsed.readStdin && process.stdin.isTTY) {
+    printHelp(process.stderr);
+    process.exit(1);
+  }
+  process.exit(anyBlocked ? 2 : 0);
 }
-var jsonMode = args.includes("--json");
-var stripReferral = args.includes("--keep-referral") ? false : args.includes("--strip-referral");
-var positional = args.filter((a) => !a.startsWith("--") && !a.startsWith("-"));
-var sanitize = compileSanitizer(clearurlsCatalog, {
-  stripReferralMarketing: stripReferral
-});
-for (const url of positional) {
-  const result = sanitize(url);
-  if (jsonMode) {
+function parseArgs(rawArgs) {
+  let json = false;
+  let explain = false;
+  let stripReferral = false;
+  let keepReferralExplicit = false;
+  let unwrapRedirects;
+  let domainBlocking = false;
+  let readStdin = false;
+  const urls = [];
+  for (const arg of rawArgs) {
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--explain":
+        explain = true;
+        break;
+      case "--strip-referral":
+        stripReferral = true;
+        break;
+      case "--keep-referral":
+        keepReferralExplicit = true;
+        break;
+      case "--unwrap-redirects":
+        unwrapRedirects = true;
+        break;
+      case "--no-unwrap-redirects":
+        unwrapRedirects = false;
+        break;
+      case "--block-domains":
+        domainBlocking = true;
+        break;
+      case "-":
+        readStdin = true;
+        break;
+      default:
+        if (arg.startsWith("--") || arg.startsWith("-") && arg.length > 1) {
+          return `unknown flag: ${arg}`;
+        }
+        urls.push(arg);
+    }
+  }
+  if (keepReferralExplicit) {
+    stripReferral = false;
+  }
+  const options = {
+    stripReferralMarketing: stripReferral,
+    domainBlocking
+  };
+  if (unwrapRedirects !== void 0) {
+    options.unwrapRedirects = unwrapRedirects;
+  }
+  return {
+    json,
+    explain,
+    options,
+    readStdin,
+    urls
+  };
+}
+function emit(result, json, explain) {
+  if (json) {
     process.stdout.write(`${JSON.stringify(result)}
 `);
-  } else {
-    switch (result.kind) {
-      case "unchanged":
-        process.stdout.write(`${result.url}
+    return result.kind === "blocked";
+  }
+  switch (result.kind) {
+    case "unchanged":
+      process.stdout.write(`${result.url}
 `);
-        break;
-      case "cleaned":
-      case "redirected":
-        process.stdout.write(`${result.url}
+      return false;
+    case "cleaned":
+      process.stdout.write(`${result.url}
 `);
-        break;
-      case "blocked":
-        process.stderr.write(`blocked: ${result.original} (via ${result.via.provider})
+      if (explain) {
+        const providers = result.matchedRules.map((rule) => rule.provider).join(",");
+        process.stderr.write(`# cleaned: ${result.original} -> ${result.url} [${providers}]
 `);
-        process.exitCode = 2;
-        break;
-    }
+      }
+      return false;
+    case "redirected":
+      process.stdout.write(`${result.url}
+`);
+      if (explain) {
+        process.stderr.write(
+          `# redirected: ${result.original} -> ${result.url} [${result.via.provider}]
+`
+        );
+      }
+      return false;
+    case "blocked":
+      process.stderr.write(`blocked: ${result.original} (via ${result.via.provider})
+`);
+      return true;
   }
 }
-function printHelp() {
-  process.stdout.write(
+function readAllStdin() {
+  return readFileSync(0, "utf8");
+}
+function packageVersion() {
+  const require2 = createRequire(import.meta.url);
+  const pkg = require2("../package.json");
+  return pkg.version ?? "0.0.0";
+}
+function printHelp(stream) {
+  stream.write(
     [
-      "url-sanitize <url> [<url>...]",
+      `url-sanitize ${packageVersion()} (catalog ${clearurlsMetadata.hash})`,
+      "",
+      "Strip tracking parameters from URLs.",
+      "",
+      "USAGE:",
+      "    url-sanitize [OPTIONS] [URL]...",
+      "    url-sanitize [OPTIONS] -          read URLs from stdin (one per line)",
+      "    url-sanitize [OPTIONS] < file     same",
+      "",
+      "OPTIONS:",
+      "    --json                  Emit one JSON SanitizeResult per input line",
+      "    --explain               Default mode, plus a matched-rule line on stderr",
+      "    --strip-referral        Strip affiliate / referral marketing params",
+      "    --keep-referral         Explicitly keep referral params (default)",
+      "    --unwrap-redirects      Unwrap redirector URLs (default)",
+      "    --no-unwrap-redirects   Leave redirector URLs untouched",
+      "    --block-domains         Emit blocked for domain-blocked URLs",
+      "    --version               Print version + catalog hash",
+      "    -h, --help              Show this help",
       "",
-      "Options:",
-      "  --json              Emit JSON result objects (one per line)",
-      "  --strip-referral    Strip affiliate / referral marketing params (off by default)",
-      "  --keep-referral     Explicitly keep referral params (default)",
-      "  -h, --help          Show this help",
+      "Runtime: TypeScript",
       ""
     ].join("\n")
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@url-sanitize/cli",
-  "version": "0.1.0",
-  "description": "Command-line URL sanitizer for cleaning, explaining, and validating tracking-heavy URLs.",
+  "version": "0.1.2",
+  "description": "Command-line tool to remove tracking parameters and unwrap tracking redirects from URLs.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -11,8 +11,8 @@
     "dist"
   ],
   "dependencies": {
-    "@url-sanitize/clearurls": "0.1.0",
-    "@url-sanitize/core": "0.1.0"
+    "@url-sanitize/clearurls": "0.1.2",
+    "@url-sanitize/core": "0.1.2"
   },
   "keywords": [
     "cli",