@namingsignal/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zena Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

package/README.md

@@ -0,0 +1,69 @@
+# @namingsignal/cli
+
+CLI for [NamingSignal](https://namingsignal.com): evidence-backed product naming for developers and agents. Local commands are keyless and deterministic; hosted commands call the NamingSignal REST API with your own key.
+
+## Install
+
+```bash
+npm install -g @namingsignal/cli
+# or run without installing
+npx -y @namingsignal/cli help
+```
+
+Requires Node 20 or newer.
+
+## Keyless local commands
+
+No account, no API key, no telemetry. Domain checks talk directly to public RDAP registries from your machine.
+
+```bash
+# Score names and run live registry checks
+namingsignal check offhook nicless --tlds com,app --namespaces --json
+
+# Compile a privacy-bounded naming brief from a repository or file
+namingsignal brief /path/to/project --dry-run
+namingsignal brief /path/to/project --out naming-brief.json
+
+# Deterministic candidate generation from an approved brief (degraded-mode starting set)
+namingsignal generate --brief naming-brief.json --count 40
+
+# Portable decision record from prior evidence
+namingsignal compare offhook quitcore --brief naming-brief.json --evidence prior-check.json --format md
+```
+
+The `brief` scanner is allowlisted and bounded: it reads README/agent instructions/manifests/docs text only, excludes source code, `.env` files, credentials, lockfiles, and build output, and `--dry-run` previews the exact file selection before anything is compiled.
+
+## Hosted commands
+
+`research` and `health` call the hosted API (default `https://namingsignal.com`). Create a free key at https://namingsignal.com/developers/keys and export it; never commit it.
+
+```bash
+export NAMING_SIGNAL_API_KEY=your-user-key
+
+namingsignal research offhook quitcore nicless --brief naming-brief.json
+namingsignal health
+```
+
+`--api <url>` or `NAMING_SIGNAL_API_URL` overrides the API origin (for example `http://localhost:3000` for a local development server).
+
+## JSON mode
+
+Machine-readable JSON is written to stdout whenever `--json` is passed or stdout is not a TTY, so agent pipelines get structured output by default. Diagnostics go to stderr.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Unexpected or network error |
+| 2 | Usage error |
+| 3 | Auth error (401/403) |
+| 4 | Quota or rate limit (402/429) |
+
+## Evidence honesty
+
+RDAP not-found means likely unregistered at check time, not a purchase guarantee. Timeouts, rate limits, and unsupported TLDs stay unknown and are never reported as available. Naming research is preliminary; it is not trademark clearance or legal advice.
+
+## License
+
+MIT, Copyright (c) 2026 Zena Labs LLC.

package/dist/core/batch.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chunkItems = chunkItems;
+exports.classifyCandidate = classifyCandidate;
+exports.bestQualifyingDomain = bestQualifyingDomain;
+exports.sortCandidates = sortCandidates;
+const TAKEN_DOMAIN_STATES = new Set([
+    "registered",
+    "premium",
+    "parked",
+    "active",
+]);
+function normalizeTld(value) {
+    const normalized = value.trim().toLowerCase().replace(/^\.+|\.+$/g, "");
+    return /^[a-z0-9-]+$/.test(normalized) ? normalized : "";
+}
+function selectedTlds(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        const tld = normalizeTld(value);
+        if (!tld || seen.has(tld))
+            continue;
+        seen.add(tld);
+        result.push(tld);
+    }
+    return result;
+}
+function domainTld(domain) {
+    const labels = domain.trim().toLowerCase().replace(/\.$/, "").split(".");
+    return labels.length > 1 ? labels.at(-1) ?? "" : "";
+}
+function stateForTld(domains, tld) {
+    const states = new Set();
+    for (const domain of domains) {
+        if (domainTld(domain.domain) !== tld)
+            continue;
+        if (domain.status === "likely_available")
+            states.add("available");
+        else if (TAKEN_DOMAIN_STATES.has(domain.status))
+            states.add("taken");
+        else
+            states.add("review");
+    }
+    // Missing evidence and conflicting duplicate evidence both require review.
+    if (states.size !== 1)
+        return "review";
+    return states.values().next().value ?? "review";
+}
+function chunkItems(items, chunkSize) {
+    if (!Number.isSafeInteger(chunkSize) || chunkSize < 1) {
+        throw new RangeError("Chunk size must be a positive safe integer.");
+    }
+    const chunks = [];
+    for (let index = 0; index < items.length; index += chunkSize) {
+        chunks.push(items.slice(index, index + chunkSize));
+    }
+    return chunks;
+}
+/**
+ * Classify only against the selected TLDs. Unknown, unsupported, missing, or
+ * conflicting evidence never becomes available or taken by implication.
+ */
+function classifyCandidate(candidate, tlds, rule) {
+    const normalizedTlds = selectedTlds(tlds);
+    if (!normalizedTlds.length)
+        return "review";
+    const states = normalizedTlds.map((tld) => stateForTld(candidate.domains ?? [], tld));
+    if (rule === "any_selected") {
+        if (states.includes("available"))
+            return "available";
+        return states.every((state) => state === "taken") ? "taken" : "review";
+    }
+    if (rule === "all_selected") {
+        if (states.every((state) => state === "available"))
+            return "available";
+        return states.includes("taken") ? "taken" : "review";
+    }
+    throw new TypeError(`Unsupported availability rule: ${String(rule)}`);
+}
+/** Return the highest-priority selected domain that satisfies the rule. */
+function bestQualifyingDomain(candidate, tlds, rule = "any_selected") {
+    if (classifyCandidate(candidate, tlds, rule) !== "available")
+        return undefined;
+    const domains = candidate.domains ?? [];
+    for (const tld of selectedTlds(tlds)) {
+        const result = domains.find((domain) => domainTld(domain.domain) === tld && domain.status === "likely_available");
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function finiteScore(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function scoreForKey(score, key) {
+    if (!score)
+        return undefined;
+    if (key === "overall")
+        return finiteScore(score.overall);
+    return finiteScore(score.dimensions.find((dimension) => dimension.key === key)?.score);
+}
+function compareScoresDescending(left, right) {
+    if (left === undefined && right === undefined)
+        return 0;
+    if (left === undefined)
+        return 1;
+    if (right === undefined)
+        return -1;
+    return right - left;
+}
+/**
+ * Return a new deterministic ranking. The selected score descends first,
+ * followed by overall score, display name, and original order as the final
+ * stable tie-break.
+ */
+function sortCandidates(candidates, key = "overall") {
+    return candidates
+        .map((candidate, index) => ({ candidate, index }))
+        .sort((left, right) => {
+        const primary = compareScoresDescending(scoreForKey(left.candidate.score, key), scoreForKey(right.candidate.score, key));
+        if (primary)
+            return primary;
+        if (key !== "overall") {
+            const overall = compareScoresDescending(finiteScore(left.candidate.score?.overall), finiteScore(right.candidate.score?.overall));
+            if (overall)
+                return overall;
+        }
+        const insensitiveName = left.candidate.name.localeCompare(right.candidate.name, "en", {
+            numeric: true,
+            sensitivity: "base",
+        });
+        if (insensitiveName)
+            return insensitiveName;
+        const exactName = left.candidate.name.localeCompare(right.candidate.name, "en", {
+            numeric: true,
+            sensitivity: "variant",
+        });
+        return exactName || left.index - right.index;
+    })
+        .map(({ candidate }) => candidate);
+}

package/dist/core/brief-constraints.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explicitAvoidTerms = explicitAvoidTerms;
+exports.candidateAvoidViolations = candidateAvoidViolations;
+exports.candidateBriefConflicts = candidateBriefConflicts;
+const normalize_1 = require("./normalize");
+function explicitAvoidTerms(brief) {
+    if (!brief)
+        return [];
+    const terms = new Set();
+    for (const entry of brief.avoid) {
+        const normalized = (0, normalize_1.normalizeName)(entry);
+        const words = normalized.split(" ").filter(Boolean);
+        if (words.length <= 2 && normalized.length <= 28)
+            terms.add((0, normalize_1.comparisonKey)(normalized));
+        const examples = entry.match(/(?:such as|including|brands?\s*:?)\s+(.+)$/i)?.[1];
+        if (examples) {
+            for (const example of examples.split(/[,;/]|\band\b/i)) {
+                const key = (0, normalize_1.comparisonKey)(example);
+                if (key.length >= 3 && key.length <= 24)
+                    terms.add(key);
+            }
+        }
+    }
+    return [...terms].filter((term) => term.length >= 3);
+}
+function candidateAvoidViolations(name, brief) {
+    const key = (0, normalize_1.comparisonKey)(name);
+    return explicitAvoidTerms(brief).filter((term) => key.includes(term));
+}
+function candidateBriefConflicts(name, brief) {
+    if (!brief)
+        return { blockers: [], warnings: [], penalty: 0 };
+    const key = (0, normalize_1.comparisonKey)(name);
+    const context = (0, normalize_1.normalizeName)([
+        brief.product,
+        brief.pain,
+        brief.outcome,
+        brief.mechanism,
+        brief.futureExpansion,
+        ...brief.avoid,
+    ].join(" "));
+    const blockers = [];
+    const warnings = [];
+    let penalty = 0;
+    const avoided = candidateAvoidViolations(name, brief);
+    if (avoided.length) {
+        blockers.push(`${name} contains an explicitly avoided term: ${avoided.join(", ")}.`);
+    }
+    if (/\b(?:audio|audible|voice|announces|calls every rep|podcast|music)\b/.test(context) && /(?:inaudible|voiceless|muted)/.test(key)) {
+        blockers.push(`${name} contradicts the brief's audible-guidance mechanism.`);
+    }
+    if (/\b(?:finish|completion|purpose|useful|guided|carries the workout)\b/.test(context) && /(?:aimless|purposeless)/.test(key)) {
+        blockers.push(`${name} contradicts the brief's purposeful-completion outcome.`);
+    }
+    if (/\b(?:avoid|not aggressive|gym bro|punishment|negative)\b/.test(context) && /(?:mindless|gainz|shred|beast|crush|punish)/.test(key)) {
+        blockers.push(`${name} uses the negative or gym-bro language the brief excludes.`);
+    }
+    if (/\b(?:relief|without managing|low decision|mental overhead|autopilot)\b/.test(context) && /(?:tethered|trapped|bound)/.test(key)) {
+        warnings.push(`${name} implies restriction while the brief promises relief from micromanagement.`);
+        penalty += 18;
+    }
+    if (/\b(?:workout|exercise|reps|sets)\b/.test(context) && !/\b(?:cycling|bike|bicycle|ride)\b/.test(context) && /(?:pedal|bicycle|cycling)/.test(key)) {
+        warnings.push(`${name} suggests cycling even though the brief describes a broader workout product.`);
+        penalty += 22;
+    }
+    return {
+        blockers: [...new Set(blockers)],
+        warnings: [...new Set(warnings)],
+        penalty: Math.min(35, penalty),
+    };
+}