@spacefast/common 0.0.2

package/dist/vocabulary.js

@@ -0,0 +1,218 @@
+// THE single source of truth for Spacefast product vocabulary. Every label,
+// CLI command name, MCP tool name, API field description, and doc string that
+// names a core concept should trace back to here, and a drift-guard can compare
+// shipped strings against this registry to catch leaks (e.g. "deployment" in a
+// dashboard label, or "E2B" in marketing copy).
+//
+// This module is intentionally pure data + types: no side effects, no imports.
+// It is additive — wiring consumers (CLI, MCP, dashboard, docs generators) onto
+// it happens in later chunks. The decisions encoded here are LOCKED:
+//
+//   - `space` is the primitive noun on every user surface. `site` survives only
+//     as the platform-API term for the shared-pool host a space is placed on
+//     (see contracts/sites.ts, internal-docs/platform.md "Site").
+//   - `publish` is the verb. "deployment" is NOT a product noun — it means
+//     "publishing a version" and is retired from user-facing surfaces (drop the
+//     `dep_*` framing). It stays only inside the GitHub integration and the
+//     platform API (see EXTERNAL_TERM_ALLOWLIST).
+//   - `version` / `channel` / `build` are the lifecycle nouns.
+//   - `API key` — never "access token".
+//   - `Collab` is the feature; `comment` is the unit.
+//   - `Superpowers` is the page-enhancement feature.
+//   - Provider names never leak externally: never "E2B" (say "Spacefast
+//     Builds" / "Spacefast CI"), never "WP.Cloud" (say "infra", except the
+//     platform API or the fixed phrase "built on WP.Cloud"), never
+//     "code.storage" / "Pierre" (see PROVIDER_HYGIENE).
+export const CONCEPTS = {
+    space: {
+        id: "space",
+        canonicalNoun: "space",
+        aliases: [],
+        externalTerms: ["site"],
+        deprecated: ["project"],
+        description: "The primitive noun everywhere a user works. 'Site' is the platform-API " +
+            "term for the shared host a space lands on; 'project' is never the primitive.",
+    },
+    publish: {
+        id: "publish",
+        canonicalNoun: "publish",
+        verb: "publish",
+        aliases: ["go live"],
+        externalTerms: ["deployment", "deploy"],
+        deprecated: ["dep_", "dep_build_", "dep_version_"],
+        description: "The verb for making a version live. 'Deployment' is not a product noun " +
+            "(it just means publishing a version); allowed only in GitHub + platform API.",
+    },
+    version: {
+        id: "version",
+        canonicalNoun: "version",
+        verb: "publish",
+        aliases: [],
+        deprecated: ["deployment"],
+        description: "An immutable snapshot of a space's content. Publishing promotes a version " +
+            "to a channel; the thing once mislabeled a 'deployment' is a version.",
+    },
+    channel: {
+        id: "channel",
+        canonicalNoun: "channel",
+        aliases: [],
+        description: "A named serving lane a version is published to (e.g. production, preview).",
+    },
+    build: {
+        id: "build",
+        canonicalNoun: "build",
+        verb: "build",
+        aliases: [],
+        externalTerms: ["E2B"],
+        description: "The CI step that turns source into a publishable version. User-facing name " +
+            "for the build provider is 'Spacefast Builds' / 'Spacefast CI', never 'E2B'.",
+    },
+    apiKey: {
+        id: "apiKey",
+        canonicalNoun: "API key",
+        aliases: [],
+        deprecated: ["access token", "access-token", "accessToken"],
+        description: "The credential users create to authenticate the API/CLI. Never 'access token'.",
+    },
+    collab: {
+        id: "collab",
+        canonicalNoun: "Collab",
+        aliases: [],
+        description: "The collaboration feature (the comment surface). Capital-C as a feature name.",
+    },
+    comment: {
+        id: "comment",
+        canonicalNoun: "comment",
+        aliases: [],
+        description: "A single unit posted within Collab. Lowercase as a common noun.",
+    },
+    superpowers: {
+        id: "superpowers",
+        canonicalNoun: "Superpowers",
+        aliases: [],
+        description: "The page-enhancement feature. Capital-S as a feature name.",
+    },
+    infra: {
+        id: "infra",
+        canonicalNoun: "infra",
+        aliases: ["infrastructure"],
+        externalTerms: ["WP.Cloud"],
+        deprecated: ["code.storage", "Pierre"],
+        description: "The hosting substrate. Say 'infra' externally; 'WP.Cloud' only in the " +
+            "platform API or the phrase 'built on WP.Cloud'. Never 'code.storage'/'Pierre'.",
+    },
+};
+export const EXTERNAL_TERM_ALLOWLIST = [
+    {
+        term: "deployment",
+        concept: "publish",
+        allowedContexts: ["github-integration", "platform-api"],
+        replacement: "version / publish",
+        reason: "GitHub speaks 'deployment'; the platform API keeps it for contract " +
+            "stability. Everywhere else say 'publish a version'.",
+    },
+    {
+        term: "deploy",
+        concept: "publish",
+        allowedContexts: ["github-integration", "platform-api"],
+        replacement: "publish",
+        reason: "Push-deploys and the deploy status come from the GitHub integration.",
+    },
+    {
+        term: "site",
+        concept: "space",
+        allowedContexts: ["platform-api"],
+        replacement: "space",
+        reason: "'Site' is the platform-API host primitive (shared pool capacity); user " +
+            "surfaces always say 'space'.",
+    },
+    {
+        term: "WP.Cloud",
+        concept: "infra",
+        allowedContexts: ["platform-api", "fixed-phrase"],
+        allowedPhrases: ["built on WP.Cloud"],
+        replacement: "infra",
+        reason: "Only the platform API or the exact phrase 'built on WP.Cloud' may name " +
+            "the provider; general copy says 'infra'.",
+    },
+];
+export const PROVIDER_HYGIENE = {
+    e2b: {
+        internalName: "E2B",
+        replacement: "Spacefast Builds / Spacefast CI",
+        allowedContexts: [],
+        reason: "The build sandbox vendor is never named; it is 'Spacefast Builds'.",
+    },
+    wpcloud: {
+        internalName: "WP.Cloud",
+        replacement: "infra",
+        allowedContexts: ["platform-api", "fixed-phrase"],
+        allowedPhrases: ["built on WP.Cloud"],
+        reason: "Hosting substrate; externally 'infra' except the platform API or the " +
+            "phrase 'built on WP.Cloud'.",
+    },
+    codeStorage: {
+        internalName: "code.storage",
+        replacement: "infra",
+        allowedContexts: [],
+        reason: "Internal storage layer; never surfaced.",
+    },
+    pierre: {
+        internalName: "Pierre",
+        replacement: "Spacefast Builds / Spacefast CI",
+        allowedContexts: [],
+        reason: "Internal git/CI dependency; never surfaced.",
+    },
+};
+/* -------------------------------------------------------------------------- */
+/* MCP tool naming                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Canonical MCP tool naming. Tools are exposed under a namespaced canonical id
+ * (`spacefast_<verb>`) plus a bare alias (`<verb>`) for clients where per-server
+ * namespacing is already guaranteed.
+ *
+ * This replaces the current inverted form (`execute_spacefast`,
+ * `resume_spacefast`) and the un-namespaced verbs (`publish`, `prepare_publish`).
+ */
+export const MCP_TOOL_NAMING = {
+    /** Prefix that makes a tool id unambiguous across servers. */
+    namespacePrefix: "spacefast_",
+    /** Canonical, namespaced tool id for a verb (e.g. "publish" → "spacefast_publish"). */
+    canonical: (verb) => `spacefast_${verb}`,
+    /** Bare alias for a verb, valid only where per-server namespacing is guaranteed. */
+    alias: (verb) => verb,
+    /** Both names a verb should register under. */
+    names: (verb) => ({
+        canonical: `spacefast_${verb}`,
+        alias: verb,
+    }),
+};
+/**
+ * Verbs that have a locked canonical MCP tool name. Generators should emit
+ * `spacefast_<verb>` as the primary id and `<verb>` as the bare alias.
+ */
+export const MCP_CANONICAL_VERBS = [
+    "publish",
+    "execute",
+    "prepare_publish",
+    "resume_publish",
+    "finalize_publish",
+];
+/* -------------------------------------------------------------------------- */
+/* CLI command aliases                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Canonical CLI verb → accepted aliases. Reused across command groups so every
+ * `list`/`remove`/`create` command exposes the same shorthands. A command file
+ * spreads `CLI_ALIASES[canonical]` into its `aliases` array.
+ */
+export const CLI_ALIASES = {
+    list: ["ls"],
+    remove: ["rm", "delete"],
+    create: ["add"],
+};
+/** Aliases registered for a canonical CLI verb (empty for unknown verbs). */
+export function cliAliasesFor(verb) {
+    return CLI_ALIASES[verb];
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@spacefast/common",
+  "version": "0.0.2",
+  "description": "Shared TypeScript contracts and utilities for Spacefast packages.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": "^1.3.11",
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./brand": {
+      "types": "./dist/brand.d.ts",
+      "import": "./dist/brand.js",
+      "default": "./dist/brand.js"
+    },
+    "./contracts/*": {
+      "types": "./dist/contracts/*.d.ts",
+      "import": "./dist/contracts/*.js",
+      "default": "./dist/contracts/*.js"
+    },
+    "./docs/*": {
+      "types": "./dist/docs/*.d.ts",
+      "import": "./dist/docs/*.js",
+      "default": "./dist/docs/*.js"
+    },
+    "./utils/*": {
+      "types": "./dist/utils/*.d.ts",
+      "import": "./dist/utils/*.js",
+      "default": "./dist/utils/*.js"
+    },
+    "./domain-exploration": {
+      "types": "./dist/domain-exploration.d.ts",
+      "import": "./dist/domain-exploration.js",
+      "default": "./dist/domain-exploration.js"
+    },
+    "./domain-normalize": {
+      "types": "./dist/domain-normalize.d.ts",
+      "import": "./dist/domain-normalize.js",
+      "default": "./dist/domain-normalize.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    }
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.101.1",
+    "smol-toml": "^1.6.1",
+    "zod": "^4.3.6"
+  }
+}