@spacefast/common 0.0.2

package/README.md

@@ -0,0 +1,42 @@
+# `@spacefast/common`
+
+Shared TypeScript contracts and utilities used by Spacefast first-party packages.
+
+Most users should install the CLI or framework integrations instead:
+
+```bash
+curl -fsSL https://spacefast.com/install.sh | bash
+```
+
+Use this package directly only when you are building against Spacefast contracts or
+need the same validation helpers used by the CLI and dashboard.
+
+## Install
+
+```bash
+npm install @spacefast/common
+```
+
+## Exports
+
+```ts
+import { spacePatchSchema } from "@spacefast/common/contracts/spaces";
+import { detectSpaFromPaths } from "@spacefast/common/utils/publish-detection";
+```
+
+The public exports are grouped by concern:
+
+- `@spacefast/common/contracts/*` for shared API and CLI schemas.
+- `@spacefast/common/utils/*` for small helpers used across Spacefast packages.
+- `@spacefast/common/docs/*` for agent-facing setup text used by Spacefast surfaces.
+
+This package is public so the Spacefast CLI and plugins can install cleanly from
+npm. It is still an implementation package: prefer documented CLI and API
+surfaces unless you need these exact contracts.
+
+## Documentation
+
+- [Spacefast docs](https://spacefast.com/docs)
+- [CLI docs](https://spacefast.com/docs/cli)
+- [API docs](https://spacefast.com/docs/api)
+- [LLM guide](https://spacefast.com/llms.txt)

package/dist/brand.d.ts

@@ -0,0 +1,15 @@
+export declare const BRAND: {
+    /** Consumer product name shown on every user surface. */
+    readonly productName: "Spacefast";
+    /** Public website/docs origin (`/docs`, `/llms.txt`, install script). */
+    readonly websiteOrigin: string;
+    /** Origin agents should fetch for the canonical `/ai` setup instructions. */
+    readonly agentSetupOrigin: string;
+    /** Canonical public API origin (generated SDK/OpenAPI server, `/skill`). */
+    readonly apiOrigin: string;
+    /** Apex for default space hostnames: `{hostLabel}.<apex>` (OPEN apex decision). */
+    readonly spaceHostnameApex: "view.fast";
+    /** Apex for internal management hostnames: `{siteId}.<apex>` (OPEN apex decision). */
+    readonly managementHostnameApex: "view.fast";
+};
+export declare const ERROR_DOCS_BASE_URL: `${string}/docs/errors`;

package/dist/brand.js

@@ -0,0 +1,24 @@
+// The single home for brand strings. Hostnames are NOT hardcoded here: they
+// derive from the canonical domain registry (`./config/domains`) so the whole
+// rename to spacefast.com is a one-file edit. Consumer surfaces never hardcode
+// these values; they import from here (and `domains` underneath).
+import { serviceOrigin } from "./config/domains.js";
+import { MANAGEMENT_HOSTNAME_APEX, SPACE_HOSTNAME_APEX } from "./config/domains.js";
+export const BRAND = {
+    /** Consumer product name shown on every user surface. */
+    productName: "Spacefast",
+    /** Public website/docs origin (`/docs`, `/llms.txt`, install script). */
+    websiteOrigin: serviceOrigin("www", "prod"),
+    /** Origin agents should fetch for the canonical `/ai` setup instructions. */
+    agentSetupOrigin: serviceOrigin("www", "prod"),
+    /** Canonical public API origin (generated SDK/OpenAPI server, `/skill`). */
+    apiOrigin: serviceOrigin("api", "prod"),
+    /** Apex for default space hostnames: `{hostLabel}.<apex>` (OPEN apex decision). */
+    spaceHostnameApex: SPACE_HOSTNAME_APEX,
+    /** Apex for internal management hostnames: `{siteId}.<apex>` (OPEN apex decision). */
+    managementHostnameApex: MANAGEMENT_HOSTNAME_APEX,
+};
+// Mechanical error-docs derivation base (contract decision locked by the build
+// plan: `${websiteOrigin}/docs/errors/{code}` forever). Lives next to the
+// brand origin it derives from; `error-codes.ts` consumes it.
+export const ERROR_DOCS_BASE_URL = `${BRAND.websiteOrigin}/docs/errors`;

package/dist/config/domains.d.ts

@@ -0,0 +1,30 @@
+/** Deployment environment a URL is being built for. */
+export type DeployEnv = "dev" | "test" | "prod";
+/** Logical services that each get their own host. */
+export type Service = "www" | "api" | "dashboard" | "superadmin" | "cast" | "mcp" | "fieldguide";
+export type EnvDomains = {
+    /** Apex/base origin for the marketing site (the `www` service + bare apex). */
+    readonly apex: string;
+    /** Cookie domain that scopes auth across every subdomain of this env. */
+    readonly cookieDomain: string;
+    /** Scheme used to build origins. SSL everywhere — even local (via portless). */
+    readonly protocol: "http" | "https";
+    /** Fully-qualified hostname per service. */
+    readonly hosts: Readonly<Record<Service, string>>;
+};
+/** The full domain map for an environment. */
+export declare function domainsFor(env: DeployEnv): EnvDomains;
+/** Origin (scheme + host, no trailing slash) for a service in an environment. */
+export declare function serviceOrigin(service: Service, env: DeployEnv): string;
+/** Cookie domain that scopes auth across all subdomains of an environment. */
+export declare function cookieDomainFor(env: DeployEnv): string;
+/** Domain Search Terminal (Fly.io); its web redirects to spacefast.com/domains. */
+export declare const FAST_DOMAIN_SEARCH_APEX: "fastdomainsearch.com";
+/** Atomic infrastructure apex used for public managed/custom domains. */
+export declare const VIEW_FAST_APEX: "view.fast";
+/** Apex for default space hostnames: `{hostLabel}.view.fast`. */
+export declare const SPACE_HOSTNAME_APEX: "view.fast";
+/** Apex for internal management hostnames: `wpc-manage-{siteId}.view.fast`. */
+export declare const MANAGEMENT_HOSTNAME_APEX: "view.fast";
+/** Reserved first-label prefix for the management namespace; users may not register it. */
+export declare const MANAGEMENT_LABEL_PREFIX: "wpc-manage-";

package/dist/config/domains.js

@@ -0,0 +1,75 @@
+// THE single source of truth for Spacefast hostnames and per-service origins,
+// across every environment. Brand strings, app URL builders, CORS allowlists,
+// cookie scope, and redirect rules all derive from here so a domain change is a
+// one-file edit instead of the ~100-site sweep this migration had to untangle.
+//
+// Env-var NAMES intentionally stay `SPACEFAST_*` (see migration plan); only the
+// VALUES they carry are produced from this registry.
+const PROD = {
+    apex: "spacefast.com",
+    cookieDomain: ".spacefast.com",
+    protocol: "https",
+    hosts: {
+        www: "spacefast.com",
+        api: "api.spacefast.com",
+        dashboard: "my.spacefast.com",
+        superadmin: "superadmin.spacefast.com",
+        cast: "cast.spacefast.com",
+        mcp: "mcp.spacefast.com",
+        fieldguide: "fieldguide.view.fast",
+    },
+};
+// Local dev runs every service under *.sf.localhost via portless (HTTPS, no
+// ports in the URL — portless proxies the raw dev ports). `remove all other
+// portless records` per the migration spec: sf.localhost is the only TLD.
+const DEV = {
+    apex: "sf.localhost",
+    cookieDomain: ".sf.localhost",
+    protocol: "https",
+    hosts: {
+        www: "www.sf.localhost",
+        api: "api.sf.localhost",
+        dashboard: "my.sf.localhost",
+        superadmin: "superadmin.sf.localhost",
+        cast: "cast.sf.localhost",
+        mcp: "mcp.sf.localhost",
+        fieldguide: "fieldguide.sf.localhost",
+    },
+};
+// The test stack shares the sf.localhost hostname scheme but runs as its own
+// isolated compose project on its own ports/resources (see ports config), so it
+// can run side-by-side with dev. URL host scheme is identical to dev.
+const TEST = DEV;
+const BY_ENV = {
+    dev: DEV,
+    test: TEST,
+    prod: PROD,
+};
+/** The full domain map for an environment. */
+export function domainsFor(env) {
+    return BY_ENV[env];
+}
+/** Origin (scheme + host, no trailing slash) for a service in an environment. */
+export function serviceOrigin(service, env) {
+    const d = BY_ENV[env];
+    return `${d.protocol}://${d.hosts[service]}`;
+}
+/** Cookie domain that scopes auth across all subdomains of an environment. */
+export function cookieDomainFor(env) {
+    return BY_ENV[env].cookieDomain;
+}
+// --- Apexes that are NOT spacefast.com subdomains -------------------------------
+// These live outside the per-env map because they are stable infra identities.
+/** Domain Search Terminal (Fly.io); its web redirects to spacefast.com/domains. */
+export const FAST_DOMAIN_SEARCH_APEX = "fastdomainsearch.com";
+/** Atomic infrastructure apex used for public managed/custom domains. */
+export const VIEW_FAST_APEX = "view.fast";
+// D-4 resolved 2026-06-26: default space hostnames are
+// `{hostLabel}.view.fast`; internal management hostnames share the same apex
+// under the reserved `wpc-manage-` label prefix and are never public space URLs.
+/** Apex for default space hostnames: `{hostLabel}.view.fast`. */
+export const SPACE_HOSTNAME_APEX = VIEW_FAST_APEX;
+/** Apex for internal management hostnames: `wpc-manage-{siteId}.view.fast`. */
+export const MANAGEMENT_HOSTNAME_APEX = VIEW_FAST_APEX;
+/** Reserved first-label prefix for the management namespace; users may not register it. */
+export const MANAGEMENT_LABEL_PREFIX = "wpc-manage-";

package/dist/config/index.d.ts

@@ -0,0 +1 @@
+export * from "./domains.js";

package/dist/config/index.js

@@ -0,0 +1,3 @@
+// Public entry for the centralized domain/URL registry.
+// Consumers import from "@spacefast/common/config".
+export * from "./domains.js";

package/dist/contracts/abuse.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+export declare const abuseReportCategorySchema: z.ZodEnum<{
+    malware: "malware";
+    phishing: "phishing";
+    spam: "spam";
+    copyright: "copyright";
+    illegal_content: "illegal_content";
+    other: "other";
+}>;
+export declare const abuseReportCreateSchema: z.ZodObject<{
+    url: z.ZodString;
+    category: z.ZodEnum<{
+        malware: "malware";
+        phishing: "phishing";
+        spam: "spam";
+        copyright: "copyright";
+        illegal_content: "illegal_content";
+        other: "other";
+    }>;
+    description: z.ZodString;
+}, z.core.$strip>;
+export declare const abuseReportStatusSchema: z.ZodEnum<{
+    new: "new";
+    reviewing: "reviewing";
+    actioned: "actioned";
+    closed: "closed";
+}>;
+export type AbuseReportStatus = z.infer<typeof abuseReportStatusSchema>;
+export declare const ABUSE_REPORT_STATUS_TRANSITIONS: Record<AbuseReportStatus, readonly AbuseReportStatus[]>;
+export declare const abuseReportSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        new: "new";
+        reviewing: "reviewing";
+        actioned: "actioned";
+        closed: "closed";
+    }>;
+    category: z.ZodEnum<{
+        malware: "malware";
+        phishing: "phishing";
+        spam: "spam";
+        copyright: "copyright";
+        illegal_content: "illegal_content";
+        other: "other";
+    }>;
+    url: z.ZodString;
+    spaceId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const superadminAbuseReportSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        new: "new";
+        reviewing: "reviewing";
+        actioned: "actioned";
+        closed: "closed";
+    }>;
+    category: z.ZodEnum<{
+        malware: "malware";
+        phishing: "phishing";
+        spam: "spam";
+        copyright: "copyright";
+        illegal_content: "illegal_content";
+        other: "other";
+    }>;
+    url: z.ZodString;
+    spaceId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    hostname: z.ZodString;
+    tenantId: z.ZodNullable<z.ZodString>;
+    description: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const superadminAbuseReportListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        new: "new";
+        reviewing: "reviewing";
+        actioned: "actioned";
+        closed: "closed";
+    }>>;
+}, z.core.$strip>;
+export declare const superadminAbuseReportPatchSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        new: "new";
+        reviewing: "reviewing";
+        actioned: "actioned";
+        closed: "closed";
+    }>;
+}, z.core.$strip>;
+export type AbuseReport = z.infer<typeof abuseReportSchema>;
+export type SuperadminAbuseReport = z.infer<typeof superadminAbuseReportSchema>;

package/dist/contracts/abuse.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { cursorListQuerySchema } from "./common.js";
+export const abuseReportCategorySchema = z
+    .enum(["malware", "phishing", "spam", "copyright", "illegal_content", "other"])
+    .describe("Reported abuse category.");
+export const abuseReportCreateSchema = z.object({
+    url: z.string().url().describe("Full URL of the content being reported."),
+    category: abuseReportCategorySchema,
+    description: z
+        .string()
+        .trim()
+        .min(10)
+        .max(5000)
+        .describe("What the reporter saw; 10-5000 characters."),
+});
+export const abuseReportStatusSchema = z
+    .enum(["new", "reviewing", "actioned", "closed"])
+    .describe("Triage status of the report.");
+// Triage state machine: reports move forward through review; `closed` reports
+// can be reopened into `reviewing` (and only there) when new evidence lands.
+export const ABUSE_REPORT_STATUS_TRANSITIONS = {
+    new: ["reviewing", "actioned", "closed"],
+    reviewing: ["actioned", "closed"],
+    actioned: ["closed"],
+    closed: ["reviewing"],
+};
+export const abuseReportSchema = z.object({
+    id: z.string().describe("Abuse report id."),
+    status: abuseReportStatusSchema,
+    category: abuseReportCategorySchema,
+    url: z.string().describe("Reported URL."),
+    spaceId: z
+        .string()
+        .nullable()
+        .describe("Space the reported hostname resolved to, when it could be resolved."),
+    createdAt: z.string().datetime().describe("When the report was filed."),
+});
+// Operator triage view: includes intake details the public receipt omits.
+export const superadminAbuseReportSchema = abuseReportSchema.extend({
+    hostname: z.string().describe("Normalized hostname extracted from the reported URL."),
+    tenantId: z.string().nullable().describe("Tenant owning the resolved space, when resolved."),
+    description: z.string().describe("Reporter-supplied description."),
+    updatedAt: z.string().datetime().describe("Last triage update."),
+});
+export const superadminAbuseReportListQuerySchema = cursorListQuerySchema.extend({
+    status: abuseReportStatusSchema.optional().describe("Filter the triage list by status."),
+});
+export const superadminAbuseReportPatchSchema = z.object({
+    status: abuseReportStatusSchema.describe("New triage status; must be a valid transition from the current status."),
+});