domainstorm 0.2.0 → 0.2.2

package/README.md

@@ -1,99 +1,150 @@
-# Domainstorm CLI
+# Domainstorm
 
-`domainstorm` is a domain brainstorming + availability CLI for agent products.
-One command can generate naming candidates and check registration status via WHOIS.
+[![npm version](https://img.shields.io/npm/v/domainstorm)](https://www.npmjs.com/package/domainstorm)
+[![npm downloads](https://img.shields.io/npm/dm/domainstorm)](https://www.npmjs.com/package/domainstorm)
+[![CI](https://img.shields.io/github/actions/workflow/status/tanishqsh/domain-cli/npm-publish.yml)](https://github.com/tanishqsh/domain-cli/actions/workflows/npm-publish.yml)
 
-## Install
+Domainstorm is the fastest way to go from "we need a name" to "these are the domains we can buy now."
+
+It is built for AI and agent products where naming cycles happen fast and every good domain disappears quickly.
+
+## Why Domainstorm
+
+- One command for ideation and availability checks
+- Built for agent-native products (`agent`, `mcp`, `ops`, `runtime`, `router` naming patterns)
+- WHOIS-based checks across TLDs with optional registry server override
+- CLI-first output that works cleanly in agent and CI workflows
+- CSV export for founders, marketers, and legal review
 
-From GitHub (works now):
+## Install
 
 ```bash
-npm i -g github:tanishqsh/domain-cli
+npm i -g domainstorm
 ```
 
-From npm (after publish):
+Run instantly without global install:
 
 ```bash
-npm i -g domainstorm
+npx --yes domainstorm --help
 ```
 
-Run without installing globally:
+## Quick Wins
+
+Brainstorm + check + return only likely available:
 
 ```bash
-npx --yes github:tanishqsh/domain-cli#main --help
+domainstorm --brainstorm "agent orchestration" "mcp broker" --tld md --server whois.nic.md --only-available --table
 ```
 
-## One-Command Brainstorm
+Check exact domains:
 
 ```bash
-domainstorm --brainstorm "agent cli" "mcp broker" --tld md --server whois.nic.md --only-available
+domainstorm agentmesh.ai agentmesh.com agentmesh.md
 ```
 
-This command:
-- Generates brandable name candidates from your seed phrases
-- Appends your target TLD
-- Checks registration status
-- Prints a narrative hint (`story=...`) for each candidate
+Default output is plain English (for example: `broker.md is available.`).
+Use `--table` if you want a structured table view.
 
-## Quick Start
+Check from file and export CSV:
 
 ```bash
-domainstorm openai.com example.org --output /tmp/domain-results.csv
+domainstorm --input domains.txt --output /tmp/domainstorm.csv
 ```
 
+Try immediately with the bundled candidate list:
+
 ```bash
-domainstorm --input agent-md-candidates.txt --tld md --server whois.nic.md --output /tmp/md-results.csv
+domainstorm --input agent-candidates.txt --tld md --server whois.nic.md --only-available --table
 ```
 
-`domain-check` is kept as a compatibility alias.
+## Built For Agent Workflows
+
+Use Domainstorm when your coding/research agent needs to propose names and validate them in the same run.
 
-## Input Format
+- Deterministic CLI output
+- Works with shell pipelines
+- No external AI API keys required
+- Easy to trigger in CI on release or branch workflows
+- No seed ideas? Ask your agent of choice (Codex, Claude, etc.) for seed phrases and pass them to `--brainstorm`
 
-- One label/domain per line in a text file
-- `#` comments are ignored
-- Labels without a TLD are converted to `<label>.<tld>` (default: `md`)
-- Comma-separated values are accepted per line
+Compatibility alias:
 
-Example:
+```bash
+domain-check --help
+```
+
+## Example Output
 
 ```txt
-# sample
-broker
-agenthub.md
-mcpbroker,mcprouter
+agentmesh.md    likely_available    availability_pattern_match    low    story=Keyword + product framing
+agentops.md     registered          registration_pattern_match    low    story=Keyword + product framing
 ```
 
-## Output Columns
+Output columns:
 
 - `domain`
-- `status`: `registered`, `likely_available`, or `unknown`
-- `reason`: why the status was chosen
-- `legal_risk`: heuristic trademark risk flag (`low` / `high_tm_risk`)
-- `story`: brainstorm narrative tag for generated names
-- `error`: lookup/system failures when present
+- `status` (`registered`, `likely_available`, `unknown`)
+- `reason`
+- `legal_risk` (`low`, `high_tm_risk`)
+- `story` (brainstorm narrative tag)
+- `error`
 
-## CLI Flags
+## Key Flags
 
+- `--brainstorm` / `--storm`
+- `--max-suggestions <n>` (default: `120`)
+- `--table`
 - `--input <file>`
 - `--output <file>`
-- `--tld <tld>` default `md`
-- `--server <whois-host>` optional (for example `whois.nic.md`)
+- `--tld <tld>` (default: `md`)
+- `--server <whois-host>`
+- `--only-available`
 - `--concurrency <n>`
 - `--timeout-ms <n>`
-- `--brainstorm` / `--storm`
-- `--max-suggestions <n>` default `120`
-- `--only-available`
 - `--raw`
 
-## Notes
+## Add `NPM_TOKEN` In GitHub (2 Minutes)
+
+1. Create an npm Automation token:
+`npmjs.com -> Account Settings -> Access Tokens -> Generate New Token -> Automation`
+2. Open your repo:
+`github.com/tanishqsh/domain-cli`
+3. Go to:
+`Settings -> Secrets and variables -> Actions`
+4. Click:
+`New repository secret`
+5. Set:
+`Name = NPM_TOKEN`
+`Secret = <your npm automation token>`
+6. Save.
+
+Now GitHub Actions can publish with `.github/workflows/npm-publish.yml`.
+
+## GitHub -> npm Auto Publish
+
+The publish workflow triggers on:
 
-- WHOIS formats vary by registry; treat `likely_available` as a pre-check, not final registrar confirmation.
-- Registries can rate-limit bulk lookups; retry unknown rows after cooldown.
-- `whois` must be installed locally (`brew install whois` on macOS).
+- GitHub Release published
+- Manual `workflow_dispatch`
 
-## Publish To npm
+Workflow path:
+
+`/.github/workflows/npm-publish.yml`
+
+Important:
+
+- Bump `package.json` version before publishing a new release
+- npm will reject already-published versions
+
+## Local Publish
 
 ```bash
 npm login
 npm publish --access public
 ```
+
+## Notes
+
+- WHOIS formats vary by registry; treat `likely_available` as a pre-check, not final registrar checkout.
+- Registries can rate-limit bulk lookups; retry `unknown` rows after cooldown.
+- Install `whois` locally (`brew install whois` on macOS).

package/{check-md-domains.mjs → check-domains.mjs}

@@ -75,59 +75,6 @@ const STOP_WORDS = new Set([
   "agents",
 ]);
 
-const DEFAULT_STORM_SEEDS = [
-  "agent",
-  "mcp",
-  "ai",
-  "broker",
-  "router",
-  "runtime",
-  "ops",
-  "stack",
-  "forge",
-  "mesh",
-  "pilot",
-  "flow",
-];
-
-const STORM_SUFFIXES = [
-  "storm",
-  "ops",
-  "hub",
-  "mesh",
-  "forge",
-  "stack",
-  "pilot",
-  "route",
-  "router",
-  "broker",
-  "runtime",
-  "engine",
-  "works",
-  "cloud",
-  "grid",
-  "terminal",
-  "dock",
-  "labs",
-  "studio",
-];
-
-const STORM_PREFIXES = [
-  "agent",
-  "ai",
-  "mcp",
-  "task",
-  "flow",
-  "auto",
-  "tool",
-  "prompt",
-  "context",
-  "trace",
-  "guard",
-  "secure",
-  "fleet",
-];
-
 // Small, non-authoritative heuristic list for quick legal-risk triage.
 const TRADEMARK_KEYWORDS = [
   "openai",
@@ -169,12 +116,16 @@ function printUsage() {
       "  --timeout-ms <n>       WHOIS timeout per domain (default: 12000)",
       "  --brainstorm           Generate domain ideas from seeds, then check availability",
       "  --max-suggestions <n>  Max brainstormed candidates (default: 120)",
+      "  --table                Render results in a readable terminal table",
+      "  --plain                Emit machine-friendly TSV output",
       "  --only-available       Print only likely available domains",
       "  --raw                  Include WHOIS snippet in console output",
       "  --help                 Show this help",
       "",
       "Notes:",
       "  - Labels without a dot are auto-converted to <label>.<tld>",
+      "  - Brainstorm mode uses your seed words only (no hardcoded keyword packs)",
+      "  - No seed ideas? Ask your agent (Codex, Claude, etc.) and pass them to --brainstorm",
       "  - WHOIS-based checks are heuristic; always confirm at registrar checkout",
     ].join("\n"),
   );
@@ -190,6 +141,8 @@ function parseArgs(argv) {
     server: null,
     brainstorm: false,
     maxSuggestions: DEFAULT_MAX_SUGGESTIONS,
+    table: false,
+    plain: false,
     onlyAvailable: false,
     raw: false,
     labels: [],
@@ -226,6 +179,12 @@ function parseArgs(argv) {
       case "--max-suggestions":
         options.maxSuggestions = Number.parseInt(argv[++i], 10);
         break;
+      case "--table":
+        options.table = true;
+        break;
+      case "--plain":
+        options.plain = true;
+        break;
       case "--only-available":
         options.onlyAvailable = true;
         break;
@@ -249,7 +208,9 @@ function parseArgs(argv) {
   }
 
   if (!options.input && options.labels.length === 0 && !options.brainstorm) {
-    throw new Error("Provide --input <file>, one/more labels/domains, or use --brainstorm.");
+    throw new Error(
+      "Provide --input <file>, one/more labels/domains, or use --brainstorm. Tip: ask your agent (Codex, Claude, etc.) for seed phrases.",
+    );
   }
   if (!Number.isInteger(options.concurrency) || options.concurrency < 1 || options.concurrency > 50) {
     throw new Error("--concurrency must be an integer between 1 and 50.");
@@ -349,7 +310,12 @@ function tokenizeSeeds(rawValues) {
 
 function brainstormCandidates(rawSeeds, maxSuggestions) {
   const seedTokens = tokenizeSeeds(rawSeeds);
-  const seedPool = Array.from(new Set([...seedTokens, ...DEFAULT_STORM_SEEDS])).slice(0, 24);
+  if (seedTokens.length === 0) {
+    throw new Error(
+      "Brainstorm mode needs seed words. Ask your agent of choice (Codex, Claude, etc.) for naming seeds, then run: --brainstorm \"seed one\" \"seed two\"",
+    );
+  }
+  const seedPool = Array.from(new Set(seedTokens)).slice(0, 24);
   const scored = new Map();
 
   function add(label, story, bonus = 0) {
@@ -368,24 +334,67 @@ function brainstormCandidates(rawSeeds, maxSuggestions) {
     }
   }
 
+  function shortForm(token) {
+    if (token.length < 5) {
+      return token;
+    }
+    const withoutVowels = token[0] + token.slice(1).replace(/[aeiou]/g, "");
+    if (withoutVowels.length >= 3 && withoutVowels.length < token.length) {
+      return withoutVowels;
+    }
+    return token;
+  }
+
+  const formsBySeed = new Map();
   for (const seed of seedPool) {
-    add(seed, "Keyword brand");
-    for (const suffix of STORM_SUFFIXES) {
-      add(`${seed}${suffix}`, "Keyword + product framing", seed.length < 8 ? 25 : 10);
+    const forms = new Set([seed, shortForm(seed)]);
+    if (seed.length > 8) {
+      forms.add(seed.slice(0, 7));
     }
-    for (const prefix of STORM_PREFIXES) {
-      add(`${prefix}${seed}`, "Platform + keyword framing", 10);
+    formsBySeed.set(seed, Array.from(forms));
+  }
+
+  for (const seed of seedPool) {
+    for (const form of formsBySeed.get(seed)) {
+      add(form, form === seed ? "Seed keyword" : "Compressed variant", form === seed ? 18 : 10);
     }
   }
 
   for (let i = 0; i < seedPool.length; i += 1) {
-    for (let j = i + 1; j < seedPool.length; j += 1) {
-      const a = seedPool[i];
-      const b = seedPool[j];
-      add(`${a}${b}`, "Two-keyword compound", 20);
-      add(`${b}${a}`, "Two-keyword compound", 20);
-      add(`${a}${b}hq`, "Company-style compound", 10);
-      add(`${a}${b}labs`, "Innovation-style compound", 8);
+    for (let j = 0; j < seedPool.length; j += 1) {
+      if (i === j) {
+        continue;
+      }
+      const aForms = formsBySeed.get(seedPool[i]);
+      const bForms = formsBySeed.get(seedPool[j]);
+      for (const a of aForms) {
+        for (const b of bForms) {
+          add(`${a}${b}`, "Two-seed compound", 20);
+        }
+      }
+    }
+  }
+
+  for (let i = 0; i < seedPool.length; i += 1) {
+    for (let j = 0; j < seedPool.length; j += 1) {
+      for (let k = 0; k < seedPool.length; k += 1) {
+        if (i === j || j === k || i === k) {
+          continue;
+        }
+        const a = formsBySeed.get(seedPool[i])[0];
+        const b = formsBySeed.get(seedPool[j])[0];
+        const c = formsBySeed.get(seedPool[k])[0];
+        add(`${a}${b}${c}`, "Three-seed compound", 10);
+      }
+    }
+  }
+
+  const acronym = seedPool.map((token) => token[0]).join("");
+  if (acronym.length >= 3) {
+    add(acronym, "Seed acronym", 16);
+    for (const seed of seedPool) {
+      add(`${acronym}${seed}`, "Acronym + seed", 12);
+      add(`${seed}${acronym}`, "Seed + acronym", 12);
     }
   }
 
@@ -396,7 +405,7 @@ function brainstormCandidates(rawSeeds, maxSuggestions) {
   return {
     labels: sorted.map((item) => item.label),
     storyByLabel: new Map(sorted.map((item) => [item.label, item.story])),
-    usedSeeds: seedTokens.length > 0 ? Array.from(new Set(seedTokens)) : DEFAULT_STORM_SEEDS,
+    usedSeeds: seedPool,
   };
 }
 
@@ -558,6 +567,125 @@ function snippet(raw) {
   return raw.replace(/\s+/g, " ").slice(0, 120);
 }
 
+function verdictForStatus(status) {
+  switch (status) {
+    case "likely_available":
+      return "AVAILABLE";
+    case "registered":
+      return "TAKEN";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+function sentenceForRow(row) {
+  if (row.status === "likely_available") {
+    return `${row.domain} is available.`;
+  }
+  if (row.status === "registered") {
+    return `${row.domain} is not available (already registered).`;
+  }
+  return `${row.domain} availability is unknown (whois could not confirm).`;
+}
+
+function toDisplayRow(row, options) {
+  return {
+    verdict: verdictForStatus(row.status),
+    domain: row.domain,
+    whois: row.status,
+    reason: row.reason,
+    risk: row.legalRisk,
+    story: row.story ?? "",
+    error: row.error ?? "",
+    raw: options.raw ? snippet(row.raw) : "",
+  };
+}
+
+function truncateCell(value, maxWidth) {
+  const text = String(value ?? "");
+  if (text.length <= maxWidth) {
+    return text;
+  }
+  if (maxWidth <= 1) {
+    return text.slice(0, maxWidth);
+  }
+  return `${text.slice(0, maxWidth - 1)}…`;
+}
+
+function printTable(rows, options) {
+  const displayRows = rows.map((row) => toDisplayRow(row, options));
+  const hasStory = displayRows.some((row) => row.story);
+  const hasError = displayRows.some((row) => row.error);
+  const columns = [
+    { key: "verdict", label: "Verdict", maxWidth: 10 },
+    { key: "domain", label: "Domain", maxWidth: 44 },
+    { key: "whois", label: "Whois", maxWidth: 18 },
+    { key: "reason", label: "Reason", maxWidth: 34 },
+    { key: "risk", label: "Risk", maxWidth: 14 },
+    ...(hasStory ? [{ key: "story", label: "Story", maxWidth: 36 }] : []),
+    ...(hasError ? [{ key: "error", label: "Error", maxWidth: 44 }] : []),
+    ...(options.raw ? [{ key: "raw", label: "Raw", maxWidth: 44 }] : []),
+  ];
+
+  const widths = new Map();
+  for (const col of columns) {
+    const maxValueLen = displayRows.reduce((max, row) => Math.max(max, String(row[col.key] ?? "").length), 0);
+    widths.set(col.key, Math.min(Math.max(col.label.length, maxValueLen), col.maxWidth));
+  }
+
+  const formatCell = (value, width) => truncateCell(value, width).padEnd(width, " ");
+  const header = columns.map((col) => formatCell(col.label, widths.get(col.key))).join(" | ");
+  const separator = columns.map((col) => "-".repeat(widths.get(col.key))).join("-+-");
+  console.log(header);
+  console.log(separator);
+  for (const row of displayRows) {
+    const line = columns.map((col) => formatCell(row[col.key], widths.get(col.key))).join(" | ");
+    console.log(line);
+  }
+}
+
+function printDecoratedResults(rows, options) {
+  const title = " DOMAINSTORM RESULTS ";
+  const border = "=".repeat(Math.max(68, title.length + 8));
+  console.log(border);
+  console.log(title);
+  console.log(border);
+  if (rows.length === 0) {
+    console.log("No domains matched your filters.");
+    return;
+  }
+  printTable(rows, options);
+  if (rows.length === 1) {
+    const row = rows[0];
+    console.log("");
+    console.log(`Result: ${row.domain} is ${verdictForStatus(row.status)}.`);
+  }
+}
+
+function printNarrativeResults(rows, options) {
+  if (rows.length === 0) {
+    console.log("No domains matched your filters.");
+    return;
+  }
+
+  for (const row of rows) {
+    console.log(sentenceForRow(row));
+    if (row.status === "unknown" || row.error) {
+      let detail = `  reason: ${row.reason}`;
+      if (row.error) {
+        detail += ` | error: ${row.error}`;
+      }
+      console.log(detail);
+    }
+    if (row.story) {
+      console.log(`  story: ${row.story}`);
+    }
+    if (options.raw) {
+      console.log(`  raw: ${snippet(row.raw)}`);
+    }
+  }
+}
+
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   let rawLabels = await loadLabels(options);
@@ -609,26 +737,30 @@ async function main() {
     ? checked.filter((row) => row.status === "likely_available")
     : checked;
 
-  for (const row of filtered) {
-    let line = `${row.domain}\t${row.status}\t${row.reason}\t${row.legalRisk}`;
-    if (row.story) {
-      line += `\tstory=${row.story}`;
-    }
-    if (row.error) {
-      line += `\terror=${row.error}`;
-    }
-    if (options.raw) {
-      line += `\t${snippet(row.raw)}`;
+  if (options.plain) {
+    for (const row of filtered) {
+      let line = `${row.domain}\t${row.status}\t${row.reason}\t${row.legalRisk}`;
+      if (row.story) {
+        line += `\tstory=${row.story}`;
+      }
+      if (row.error) {
+        line += `\terror=${row.error}`;
+      }
+      if (options.raw) {
+        line += `\t${snippet(row.raw)}`;
+      }
+      console.log(line);
     }
-    console.log(line);
+  } else if (options.table) {
+    printDecoratedResults(filtered, options);
+  } else {
+    printNarrativeResults(filtered, options);
   }
 
   await maybeWriteCsv(checked, options.output);
 
   const counts = summarize(checked);
-  console.error(
-    `Summary: likely_available=${counts.likelyAvailable}, registered=${counts.registered}, unknown=${counts.unknown}`,
-  );
+  console.error(`Summary: ${counts.likelyAvailable} available, ${counts.registered} taken, ${counts.unknown} unknown.`);
   if (options.output) {
     console.error(`CSV written: ${path.resolve(options.output)}`);
   }

package/package.json

@@ -1,27 +1,45 @@
 {
   "name": "domainstorm",
-  "version": "0.2.0",
-  "description": "Domainstorm CLI: brainstorm brandable names and check domain registration via WHOIS",
+  "version": "0.2.2",
+  "description": "Brainstorm and check domain names in one command.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tanishqsh/domain-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tanishqsh/domain-cli/issues"
+  },
+  "homepage": "https://github.com/tanishqsh/domain-cli#readme",
   "type": "module",
   "bin": {
-    "domainstorm": "check-md-domains.mjs",
-    "domain-check": "check-md-domains.mjs"
+    "domainstorm": "check-domains.mjs",
+    "domain-check": "check-domains.mjs"
   },
   "files": [
-    "check-md-domains.mjs",
-    "agent-md-candidates.txt",
+    "check-domains.mjs",
+    "agent-candidates.txt",
     "README.md"
   ],
   "scripts": {
-    "start": "node check-md-domains.mjs --help"
+    "check": "node check-domains.mjs --help > /dev/null",
+    "start": "node check-domains.mjs --help"
   },
   "keywords": [
     "domain",
+    "domains",
     "whois",
     "cli",
-    "availability"
+    "availability",
+    "brainstorm",
+    "branding",
+    "agents",
+    "naming"
   ],
   "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "engines": {
     "node": ">=18"
   }