@spacefast/common 0.0.5 → 0.0.7

package/dist/docs/search.js

@@ -0,0 +1,96 @@
+// Pure, offline search + tier filtering over a docs index. Shared by the CLI's
+// `sf docs` (offline, against the bundled JSON) and the control-plane's
+// GET /v1/docs (in memory, against the catalog-derived index) so both rank and
+// gate identically. Tier-aware — ESSENTIAL by default, widening to FULL
+// (`--full`) and REFERENCE (`--all`).
+import { tierVisibleAt } from "../vocabulary.js";
+function toResult(entry) {
+    return {
+        slug: entry.slug,
+        title: entry.title,
+        kind: entry.kind,
+        tier: entry.tier,
+        summary: entry.summary,
+        url: entry.url,
+    };
+}
+function toTopic(entry) {
+    return { ...toResult(entry), body: entry.body };
+}
+/** Entries visible at `viewTier`, in catalog order. */
+export function visibleEntries(index, viewTier) {
+    return index.entries.filter((entry) => tierVisibleAt(viewTier, entry.tier));
+}
+/** Exact topic lookup by slug (case-insensitive). Ignores tier — explicit intent wins. */
+export function findTopic(index, slug) {
+    const needle = slug.trim().toLowerCase();
+    if (!needle)
+        return undefined;
+    return index.entries.find((entry) => entry.slug.toLowerCase() === needle);
+}
+function scoreEntry(entry, tokens) {
+    const slug = entry.slug.toLowerCase();
+    const title = entry.title.toLowerCase();
+    const keywords = entry.keywords.map((keyword) => keyword.toLowerCase());
+    let total = 0;
+    for (const token of tokens) {
+        let tokenScore = 0;
+        if (slug === token)
+            tokenScore = Math.max(tokenScore, 5);
+        else if (slug.includes(token))
+            tokenScore = Math.max(tokenScore, 3);
+        if (title.includes(token))
+            tokenScore = Math.max(tokenScore, 3);
+        if (keywords.some((keyword) => keyword.includes(token)))
+            tokenScore = Math.max(tokenScore, 2);
+        if (tokenScore === 0 && entry.haystack.includes(token))
+            tokenScore = 1;
+        // AND semantics: every query token must match somewhere.
+        if (tokenScore === 0)
+            return 0;
+        total += tokenScore;
+    }
+    return total;
+}
+/**
+ * Ranked query results are capped so a broad term (e.g. one that hits a chunk
+ * of the ~390 generated error-reference entries) can never return the whole
+ * catalog in one response. Listing a tier with no query is unaffected — that's
+ * an intentional "show me everything at this tier" request, not a search.
+ */
+export const SEARCH_DOCS_RESULT_LIMIT = 25;
+/**
+ * Rank docs matching `query` within the tier. Empty query returns the full tier
+ * listing (catalog order), uncapped. A non-empty query ranks matches and caps
+ * the result count at {@link SEARCH_DOCS_RESULT_LIMIT}.
+ */
+export function searchDocs(index, options) {
+    const pool = visibleEntries(index, options.tier);
+    const tokens = (options.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return pool;
+    return pool
+        .map((entry) => ({ entry, score: scoreEntry(entry, tokens) }))
+        .filter((scored) => scored.score > 0)
+        .toSorted((a, b) => b.score - a.score || a.entry.slug.localeCompare(b.entry.slug))
+        .slice(0, SEARCH_DOCS_RESULT_LIMIT)
+        .map((scored) => scored.entry);
+}
+/**
+ * Resolve the `sf docs [query]` request: an exact-slug query prints that topic;
+ * any other query searches; an empty query lists the tier. Pure + offline.
+ */
+export function resolveDocsCommand(index, options) {
+    const trimmed = (options.query ?? "").trim();
+    const exact = trimmed ? findTopic(index, trimmed) : undefined;
+    if (exact) {
+        return {
+            query: trimmed || null,
+            tier: options.tier,
+            topic: toTopic(exact),
+            results: [toResult(exact)],
+        };
+    }
+    const results = searchDocs(index, { query: trimmed, tier: options.tier }).map(toResult);
+    return { query: trimmed || null, tier: options.tier, topic: null, results };
+}

package/dist/docs/skill-distribution.d.ts

@@ -3,10 +3,12 @@ export declare const spacefastSkillRepoOwner = "spacefast";
 export declare const spacefastSkillRepoName = "plugins";
 export declare const spacefastSkillRepoRef = "spacefast/plugins";
 export declare const spacefastSkillUrl: string;
-export declare const spacefastSkillInstallCommand: string;
+export declare const spacefastSkillFetchCommand: string;
+export declare const spacefastSkillInstallCommand = "npx -y skills add spacefast/plugins --skill spacefast -g -y";
 export declare const spacefastInstallCurlCommand: string;
 export declare const spacefastInstallPowerShellCommand: string;
 export declare const spacefastClaudePluginAddCommand = "claude plugin marketplace add spacefast/plugins";
 export declare const spacefastClaudePluginInstallCommand = "claude plugin install spacefast@spacefast";
-export declare const spacefastCodexSkillInstallCommand = "npx skills add spacefast/plugins --skill spacefast -g";
-export declare const spacefastAgentSetupPrompt: string;
+export declare const spacefastCodexPluginAddCommand = "codex plugin marketplace add spacefast/plugins";
+export declare const spacefastCodexPluginInstallCommand = "codex plugin add spacefast@spacefast";
+export declare const spacefastCodexSkillInstallCommand = "npx -y skills add spacefast/plugins --skill spacefast -g -a codex -y";

package/dist/docs/skill-distribution.js

@@ -4,15 +4,15 @@ export const spacefastSkillRepoOwner = "spacefast";
 export const spacefastSkillRepoName = "plugins";
 export const spacefastSkillRepoRef = `${spacefastSkillRepoOwner}/${spacefastSkillRepoName}`;
 export const spacefastSkillUrl = `${BRAND.apiOrigin}/skill`;
-export const spacefastSkillInstallCommand = `curl -fsSL ${spacefastSkillUrl}`;
+export const spacefastSkillFetchCommand = `curl -fsSL ${spacefastSkillUrl}`;
+export const spacefastSkillInstallCommand = `npx -y skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -y`;
 export const spacefastInstallCurlCommand = `curl -fsSL ${BRAND.websiteOrigin}/install.sh | bash`;
 export const spacefastInstallPowerShellCommand = `irm ${BRAND.websiteOrigin}/install.ps1 | iex`;
 export const spacefastClaudePluginAddCommand = `claude plugin marketplace add ${spacefastSkillRepoRef}`;
 export const spacefastClaudePluginInstallCommand = `claude plugin install ${spacefastSkillName}@${spacefastSkillName}`;
-export const spacefastCodexSkillInstallCommand = `npx skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g`;
-export const spacefastAgentSetupPrompt = `I'd like you to set up ${BRAND.websiteOrigin}, the static host for AI agents.
-
-Install the ${BRAND.productName} CLI with: ${spacefastInstallCurlCommand}
-On Windows PowerShell, use: ${spacefastInstallPowerShellCommand}
-
-If your environment supports manual skill import, fetch the official ${BRAND.productName} skill from: ${spacefastSkillUrl}`;
+// Codex mirrors the Claude plugin commands (same marketplace repo, same
+// plugin name); the release workflow validates both installs against the
+// assembled dist/plugins tree.
+export const spacefastCodexPluginAddCommand = `codex plugin marketplace add ${spacefastSkillRepoRef}`;
+export const spacefastCodexPluginInstallCommand = `codex plugin add ${spacefastSkillName}@${spacefastSkillName}`;
+export const spacefastCodexSkillInstallCommand = `npx -y skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -a codex -y`;

package/dist/slug-policy/blocklist.d.ts

@@ -0,0 +1,4 @@
+export declare const INFRA_SLUG_BLOCKLIST: readonly ["www", "www1", "www2", "www3", "web", "mail", "webmail", "smtp", "imap", "pop", "mx", "mx1", "mx2", "ns", "ns1", "ns2", "ns3", "ns4", "dns", "ftp", "ssh", "vpn", "git", "svn", "cdn", "assets", "static", "img", "images", "files", "media", "local", "localhost", "host", "server", "remote", "portal", "owa", "exchange", "gov", "nic", "whois"];
+export declare const PRODUCT_PLATFORM_SLUG_BLOCKLIST: readonly ["spacefast", "stattic", "viewfast", "view-fast", "sf", "my", "api", "app", "apps", "admin", "superadmin", "dashboard", "console", "login", "logout", "auth", "oauth", "sso", "signup", "signin", "register", "claim", "billing", "checkout", "mcp", "cli", "sdk", "cast", "preview", "previews", "internal", "ops", "handbook"];
+export declare const TRADEMARK_EXACT_SLUG_BLOCKLIST: readonly ["automattic", "wordpress", "woocommerce", "jetpack", "wpcloud", "google", "facebook", "instagram", "twitter", "x", "tiktok", "youtube", "amazon", "apple", "microsoft", "netflix", "paypal", "stripe", "visa", "mastercard", "coinbase", "metamask", "openai", "anthropic", "claude", "github", "gitlab", "vercel", "netlify", "cloudflare"];
+export declare const SUBSTRING_SLUG_BLOCKLIST: readonly ["spacefast", "stattic", "automattic", "wordpress", "paypal"];

package/dist/slug-policy/blocklist.js

@@ -0,0 +1,122 @@
+// Infrastructure hostnames reserved by WordPress.com managed-subdomain policy.
+export const INFRA_SLUG_BLOCKLIST = [
+    "www",
+    "www1",
+    "www2",
+    "www3",
+    "web",
+    "mail",
+    "webmail",
+    "smtp",
+    "imap",
+    "pop",
+    "mx",
+    "mx1",
+    "mx2",
+    "ns",
+    "ns1",
+    "ns2",
+    "ns3",
+    "ns4",
+    "dns",
+    "ftp",
+    "ssh",
+    "vpn",
+    "git",
+    "svn",
+    "cdn",
+    "assets",
+    "static",
+    "img",
+    "images",
+    "files",
+    "media",
+    "local",
+    "localhost",
+    "host",
+    "server",
+    "remote",
+    "portal",
+    "owa",
+    "exchange",
+    "gov",
+    "nic",
+    "whois",
+];
+// Spacefast product, platform, and public surface names.
+export const PRODUCT_PLATFORM_SLUG_BLOCKLIST = [
+    "spacefast",
+    "stattic",
+    "viewfast",
+    "view-fast",
+    "sf",
+    "my",
+    "api",
+    "app",
+    "apps",
+    "admin",
+    "superadmin",
+    "dashboard",
+    "console",
+    "login",
+    "logout",
+    "auth",
+    "oauth",
+    "sso",
+    "signup",
+    "signin",
+    "register",
+    "claim",
+    "billing",
+    "checkout",
+    "mcp",
+    "cli",
+    "sdk",
+    "cast",
+    "preview",
+    "previews",
+    "internal",
+    "ops",
+    "handbook",
+];
+// Exact trademark and impersonation names reserved in every managed namespace.
+export const TRADEMARK_EXACT_SLUG_BLOCKLIST = [
+    "automattic",
+    "wordpress",
+    "woocommerce",
+    "jetpack",
+    "wpcloud",
+    "google",
+    "facebook",
+    "instagram",
+    "twitter",
+    "x",
+    "tiktok",
+    "youtube",
+    "amazon",
+    "apple",
+    "microsoft",
+    "netflix",
+    "paypal",
+    "stripe",
+    "visa",
+    "mastercard",
+    "coinbase",
+    "metamask",
+    "openai",
+    "anthropic",
+    "claude",
+    "github",
+    "gitlab",
+    "vercel",
+    "netlify",
+    "cloudflare",
+];
+// Minimal substring rules for high-risk product and impersonation strings.
+export const SUBSTRING_SLUG_BLOCKLIST = [
+    "spacefast",
+    "stattic",
+    "automattic",
+    "wordpress",
+    "paypal",
+];

package/dist/slug-policy/index.d.ts

@@ -0,0 +1,17 @@
+export { INFRA_SLUG_BLOCKLIST, PRODUCT_PLATFORM_SLUG_BLOCKLIST, SUBSTRING_SLUG_BLOCKLIST, TRADEMARK_EXACT_SLUG_BLOCKLIST, } from "./blocklist.js";
+export type SlugPolicyOptions = {
+    maxLength?: number;
+};
+export type SlugPolicyVerdict = {
+    ok: true;
+    normalized: string;
+} | {
+    ok: false;
+    reason: "slug_invalid" | "slug_reserved";
+    detail: string;
+};
+export declare const SLUG_MIN_LENGTH = 3;
+export declare const TEAM_SLUG_MAX_LENGTH = 63;
+export declare const SPACE_SLUG_MAX_LENGTH = 55;
+export declare function evaluateSlugCandidate(input: string, options?: SlugPolicyOptions): SlugPolicyVerdict;
+export declare function slugPolicyFailureSurvivesSuffix(normalized: string): boolean;

package/dist/slug-policy/index.js

@@ -0,0 +1,86 @@
+import { MANAGEMENT_LABEL_PREFIX } from "../config/domains.js";
+import { INFRA_SLUG_BLOCKLIST, PRODUCT_PLATFORM_SLUG_BLOCKLIST, SUBSTRING_SLUG_BLOCKLIST, TRADEMARK_EXACT_SLUG_BLOCKLIST, } from "./blocklist.js";
+export { INFRA_SLUG_BLOCKLIST, PRODUCT_PLATFORM_SLUG_BLOCKLIST, SUBSTRING_SLUG_BLOCKLIST, TRADEMARK_EXACT_SLUG_BLOCKLIST, } from "./blocklist.js";
+export const SLUG_MIN_LENGTH = 3;
+export const TEAM_SLUG_MAX_LENGTH = 63;
+export const SPACE_SLUG_MAX_LENGTH = 55;
+const infraReservedSlugs = new Set(INFRA_SLUG_BLOCKLIST);
+const productPlatformReservedSlugs = new Set(PRODUCT_PLATFORM_SLUG_BLOCKLIST);
+const trademarkExactReservedSlugs = new Set(TRADEMARK_EXACT_SLUG_BLOCKLIST);
+export function evaluateSlugCandidate(input, options = {}) {
+    const maxLength = options.maxLength ?? TEAM_SLUG_MAX_LENGTH;
+    // Explicit user choices are rejected rather than silently reshaped. Case,
+    // surrounding whitespace, and diacritics are the only accepted canonicalization.
+    const casefolded = input
+        .trim()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase();
+    if (!/^[a-z0-9-]+$/.test(casefolded)) {
+        return invalid("Slug may only contain lowercase letters, numbers, and dashes.");
+    }
+    const structuralCandidate = casefolded;
+    if (structuralCandidate.includes("--")) {
+        return invalid("Slug cannot contain -- because it is the version/branch hostname separator.");
+    }
+    const normalized = casefolded.replace(/^-+|-+$/g, "");
+    const structuralVerdict = evaluateStructuralRules(normalized, structuralCandidate, maxLength);
+    if (!structuralVerdict.ok) {
+        return structuralVerdict;
+    }
+    const reservedVerdict = evaluateReservedRules(normalized);
+    if (!reservedVerdict.ok) {
+        return reservedVerdict;
+    }
+    return { ok: true, normalized };
+}
+function evaluateStructuralRules(normalized, structuralCandidate, maxLength) {
+    if (normalized.length < SLUG_MIN_LENGTH) {
+        return invalid(`Slug must be at least ${SLUG_MIN_LENGTH} characters.`);
+    }
+    if (normalized.length > maxLength) {
+        return invalid(`Slug must be ${maxLength} characters or fewer.`);
+    }
+    if (structuralCandidate.startsWith("-") || structuralCandidate.endsWith("-")) {
+        return invalid("Slug cannot start or end with a dash.");
+    }
+    if (/^[0-9]+$/.test(normalized)) {
+        return invalid("Slug cannot be all numeric.");
+    }
+    if (normalized.startsWith(MANAGEMENT_LABEL_PREFIX)) {
+        return reserved(`Slug cannot start with reserved prefix ${MANAGEMENT_LABEL_PREFIX}.`);
+    }
+    return { ok: true, normalized };
+}
+// A substring reservation survives numeric suffixing (`paypal-2` still
+// contains `paypal`). Suggestion generators use this structured signal to
+// abandon the base instead of exhausting every suffix.
+function matchingReservedSubstring(normalized) {
+    return SUBSTRING_SLUG_BLOCKLIST.find((reservedSubstring) => normalized.includes(reservedSubstring));
+}
+export function slugPolicyFailureSurvivesSuffix(normalized) {
+    return (matchingReservedSubstring(normalized) !== undefined ||
+        normalized.startsWith(MANAGEMENT_LABEL_PREFIX));
+}
+function evaluateReservedRules(normalized) {
+    if (infraReservedSlugs.has(normalized)) {
+        return reserved("Slug is reserved for infrastructure.");
+    }
+    if (productPlatformReservedSlugs.has(normalized)) {
+        return reserved("Slug is reserved for Spacefast product and platform use.");
+    }
+    if (trademarkExactReservedSlugs.has(normalized)) {
+        return reserved("Slug is reserved for trademark and impersonation protection.");
+    }
+    const substringRule = matchingReservedSubstring(normalized);
+    if (substringRule) {
+        return reserved(`Slug contains reserved substring ${substringRule}.`);
+    }
+    return { ok: true, normalized };
+}
+function invalid(detail) {
+    return { ok: false, reason: "slug_invalid", detail };
+}
+function reserved(detail) {
+    return { ok: false, reason: "slug_reserved", detail };
+}

package/dist/utils/access-match.d.ts

@@ -0,0 +1,39 @@
+export declare function filterGrantsByNamespace(grants: string[], namespaces: string[]): string[];
+export declare function grantGlobMatches(pattern: string, grant: string): boolean;
+export declare function grantsIntersect(grants: string[], requiredGrants: string[]): boolean;
+export declare function grantsSatisfyRule(input: {
+    grants: string[];
+    requiredGrants: string[];
+    grantNamespaces: string[];
+}): boolean;
+export declare function canonicalizeHost(host: string): string;
+export declare function hostGlobMatches(pattern: string, host: string): boolean;
+export declare function hostTemplateMatches(template: string, host: string): boolean;
+export declare function pathGlobMatches(pattern: string, path: string): boolean;
+export declare function agentMatches(needle: string, agent: string): boolean;
+export declare function ipInCidr(ip: string, cidr: string): boolean;
+export declare function ipInAnyCidr(ip: string, cidrs: string[]): boolean;
+export type RuleMatchContext = {
+    host: string;
+    path: string;
+    channel?: string | undefined;
+    ip?: string | undefined;
+    agent?: string | undefined;
+    country?: string | undefined;
+    headers?: Record<string, string> | undefined;
+};
+export type RuleMatchInput = {
+    host?: string | undefined;
+    hostPattern?: string | undefined;
+    hostTemplate?: string | undefined;
+    pathPattern?: string | undefined;
+    channel?: string | undefined;
+    ipCidrs?: string[] | undefined;
+    agent?: string | undefined;
+    country?: string | undefined;
+    header?: {
+        name: string;
+        value: string;
+    } | undefined;
+};
+export declare function ruleMatchApplies(match: RuleMatchInput, context: RuleMatchContext): boolean;