@spacefast/common 0.0.26 → 0.2.1

package/dist/docs/page-context-prompt.js

@@ -0,0 +1,131 @@
+/*
+ * "Copy for AI" for a dashboard page: what Spacefast is, what the user is
+ * looking at, the state of the thing on screen, the values already typed into
+ * the open form, the docs, the API operations, and the equivalent CLI commands.
+ *
+ * The output is a pasted prompt an agent reads whole, not a manual. Three rules
+ * keep it useful rather than decorative:
+ *
+ *   1. **Positioning first.** An agent that has never heard of Spacefast is
+ *      told what it is before it is handed endpoints (`SPACEFAST_POSITIONING`).
+ *   2. **Every reference is specific.** Docs entries, API operations and CLI
+ *      commands each carry their own deep link. Three commands never share one
+ *      link to a section root.
+ *   3. **Nothing here is written twice.** Commands, usage lines, URLs and
+ *      schema locations come from the registries that own them — the oclif
+ *      manifest, the OpenAPI document, ./skill-distribution.ts,
+ *      ./agent-setup.ts and ./reference-urls.ts. This module formats; it does
+ *      not remember.
+ *
+ * Filtering secrets is the caller's job: the dashboard picks which form fields
+ * are safe to include.
+ */
+import { BRAND, SPACEFAST_POSITIONING, SPACEFAST_POSITIONING_SHORT } from "../brand.js";
+import { serviceOrigin } from "../config/domains.js";
+import { agentSetupUrl } from "./agent-setup.js";
+import { spacefastInstallCurlCommand } from "./skill-distribution.js";
+const FORM_HYGIENE_NOTE = "These values exclude secrets. Never ask the user to paste a credential, and never echo one back.";
+/** One form value as a single line. Untouched fields return null so they are dropped. */
+function formatValue(value) {
+    if (Array.isArray(value)) {
+        const items = value.filter((item) => item.trim() !== "");
+        return items.length > 0 ? items.join(", ") : null;
+    }
+    const text = String(value);
+    return text.trim() === "" ? null : text;
+}
+function formLines(form) {
+    return Object.entries(form.values).flatMap(([key, value]) => {
+        const formatted = formatValue(value);
+        return formatted === null ? [] : [`- ${key}: ${formatted}`];
+    });
+}
+/**
+ * `sf builds ls --space docs --json  # List builds. Docs: https://…#sf-builds-ls`
+ *
+ * One line per command, so a page with eight commands still fits on a screen.
+ * A command with neither summary nor link is just the invocation.
+ */
+function cliLine(entry) {
+    const notes = [entry.summary, entry.docsUrl ? `Docs: ${entry.docsUrl}` : undefined].filter((part) => part !== undefined && part.trim() !== "");
+    return notes.length === 0 ? entry.command : `${entry.command}  # ${notes.join(" ")}`;
+}
+/** Builds the copy-ready markdown prompt for one dashboard page. Pure: same input, same bytes. */
+export function buildPageContextPrompt(input) {
+    const lines = [
+        `# ${input.page.title}`,
+        "",
+        SPACEFAST_POSITIONING,
+        "",
+        `The user is on this ${BRAND.productName} dashboard page: ${input.page.url}`,
+    ];
+    if (input.page.description)
+        lines.push(input.page.description);
+    if (input.facts && input.facts.items.length > 0) {
+        lines.push("", `## ${input.facts.title}`, "");
+        for (const fact of input.facts.items)
+            lines.push(`- ${fact.label}: ${fact.value}`);
+    }
+    const values = input.form ? formLines(input.form) : [];
+    if (input.form && values.length > 0) {
+        lines.push("", "## Continue what's in progress", "", `${input.form.surface}:`, ...values);
+        lines.push("", FORM_HYGIENE_NOTE);
+    }
+    if (input.docs.length > 0) {
+        lines.push("", "## Read the docs", "");
+        for (const doc of input.docs)
+            lines.push(`- ${doc.title} — ${doc.url}`);
+    }
+    if (input.operations.length > 0) {
+        lines.push("", "## Call the API", "");
+        for (const operation of input.operations) {
+            // A spec without a summary for this operation ends the line at the path,
+            // rather than at a dash pointing to nothing.
+            const call = `- ${operation.method} ${operation.path}`;
+            lines.push(operation.summary.trim() === "" ? call : `${call} — ${operation.summary}`);
+            // The reference page carries the parameters and the request/response
+            // schemas, so the prompt links there instead of copying a shape that
+            // would drift from the spec on the next deploy.
+            if (operation.docsUrl)
+                lines.push(`  Schema: ${operation.docsUrl}`);
+        }
+    }
+    if (input.cli.length > 0) {
+        lines.push("", "## Run the CLI", "", "```bash");
+        for (const entry of input.cli)
+            lines.push(cliLine(entry));
+        lines.push("```", "", "## Get the CLI", "", "```bash");
+        lines.push(spacefastInstallCurlCommand, "sf login", "```");
+    }
+    if (input.mcp) {
+        lines.push("", "## Or connect over MCP", "", `Hosted MCP endpoint: ${serviceOrigin("mcp", "prod")} — per-client setup: ${agentSetupUrl}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Adds one private exchange to the safe page brief. The caller must send this
+ * result only to the clipboard. The private URL must not enter a rendered node,
+ * a query string, a log, or a cache key.
+ *
+ * The wording is calibrated on fresh-agent evals. First person — the user is
+ * the one pasting it, so the user is speaking. It says what the link is BEFORE
+ * asking for the fetch, because an unexplained "fetch this and obey it" reads
+ * as a phishing template to a careful agent. And it names the right mechanics:
+ * the naive `curl <url>` puts the bearer in argv and shell history, so the
+ * prompt says to use a URL-fetch tool.
+ */
+export function buildPrivatePageContextPrompt(input) {
+    const context = input.context.trimEnd();
+    const closing = input.closing ??
+        "Then continue the page task with the references above. Publish or change data only when the task requires it.";
+    return `${context}
+
+## Connect ${input.targetLabel} privately
+
+${SPACEFAST_POSITIONING_SHORT} I made you a one-use sign-in link. Fetch it with your URL-fetch tool and follow the document it returns: ${input.handoffUrl}
+
+Keep the link out of shell commands, logs, and replies. Fetching is read-only and leaves the link live. Expires: ${input.expiresAt}.
+
+${closing}
+`;
+}

package/dist/docs/reference-urls.d.ts

@@ -0,0 +1,46 @@
+/** The single CLI reference page. Every command is an anchor on it. */
+export declare const CLI_DOCS_URL: string;
+/** The API reference index. Every operation is a page under it. */
+export declare const API_REFERENCE_URL: string;
+/**
+ * The partner API reference index. The docs exporter publishes two reference
+ * trees from two OpenAPI documents — the consumer spec under
+ * {@link API_REFERENCE_URL} and the partner spec here — with the same
+ * `<tag>/<operationid>` page shape under each. Partner-visibility operations
+ * exist only in the second tree, so linking them at the consumer base lands on
+ * a page that was never generated.
+ */
+export declare const PARTNER_API_REFERENCE_URL: string;
+/** Which of the two published reference trees an operation's page lives in. */
+export type ApiDocsVisibility = "public" | "partner";
+/**
+ * The docs site's heading-anchor slug: lowercase, every run of anything that
+ * is not a letter or digit collapsed to one dash, no leading or trailing dash.
+ * `sf api METHODORPATH [PATH]` → `sf-api-methodorpath-path`.
+ */
+export declare function docsHeadingAnchor(heading: string): string;
+/**
+ * Deep link to one CLI command's section of the CLI reference.
+ *
+ * `commandName` is the manifest's rendered invocation — `sf builds ls`,
+ * `sf domains add HOSTNAME` — exactly as the docs exporter prints it in the
+ * heading. Anything that does not slugify to something (an empty name) falls
+ * back to the page rather than emitting a `#` that scrolls nowhere.
+ */
+export declare function cliCommandDocsUrl(commandName: string): string;
+/**
+ * Deep link to one API operation's reference page, which is also where its
+ * request and response schemas are rendered.
+ *
+ * `tag` is the operation's first OpenAPI tag; the reference groups pages by it.
+ * An untagged operation has no page of its own, so it gets the index.
+ *
+ * `visibility` picks the tree. It defaults to `"public"`, which is right for
+ * every caller reading the consumer spec; pass `"partner"` for an operation
+ * that only appears in the partner document.
+ */
+export declare function apiOperationDocsUrl(operation: {
+    readonly operationId: string;
+    readonly tag?: string;
+    readonly visibility?: ApiDocsVisibility;
+}): string;

package/dist/docs/reference-urls.js

@@ -0,0 +1,79 @@
+/*
+ * Deep links into the published documentation, derived rather than written.
+ *
+ * The docs site freezes two generated route shapes (they are public contracts
+ * and can never move):
+ *
+ *   - `/docs/cli` is one page per CLI, with one `## \`sf <command>\`` heading
+ *     per command. Its anchors are the heading text slugified, so
+ *     `## \`sf builds cancel BUILD\`` is `#sf-builds-cancel-build`.
+ *   - `/docs/api/reference/<tag>/<operationid>` is one page per API operation,
+ *     carrying that operation's parameters and request/response schemas. Both
+ *     segments are lowercased.
+ *
+ * Everything here is a pure function of what a registry already holds — the
+ * oclif manifest's command name, the OpenAPI operation's id and tag. Nothing
+ * in this file is a second copy of a URL that could drift from the docs; a
+ * caller that cannot produce the registry value gets the section root instead
+ * of a guess.
+ *
+ * This module deliberately imports only the domain registry. The dashboard
+ * resolves references against the megabyte-scale docs catalog and CLI manifest
+ * behind a dynamic import, and a URL helper that dragged the catalog in with it
+ * would undo that.
+ */
+import { DOCS_BASE_URL } from "../config/domains.js";
+/** The single CLI reference page. Every command is an anchor on it. */
+export const CLI_DOCS_URL = `${DOCS_BASE_URL}/cli`;
+/** The API reference index. Every operation is a page under it. */
+export const API_REFERENCE_URL = `${DOCS_BASE_URL}/api/reference`;
+/**
+ * The partner API reference index. The docs exporter publishes two reference
+ * trees from two OpenAPI documents — the consumer spec under
+ * {@link API_REFERENCE_URL} and the partner spec here — with the same
+ * `<tag>/<operationid>` page shape under each. Partner-visibility operations
+ * exist only in the second tree, so linking them at the consumer base lands on
+ * a page that was never generated.
+ */
+export const PARTNER_API_REFERENCE_URL = `${DOCS_BASE_URL}/partners/api/reference`;
+/**
+ * The docs site's heading-anchor slug: lowercase, every run of anything that
+ * is not a letter or digit collapsed to one dash, no leading or trailing dash.
+ * `sf api METHODORPATH [PATH]` → `sf-api-methodorpath-path`.
+ */
+export function docsHeadingAnchor(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Deep link to one CLI command's section of the CLI reference.
+ *
+ * `commandName` is the manifest's rendered invocation — `sf builds ls`,
+ * `sf domains add HOSTNAME` — exactly as the docs exporter prints it in the
+ * heading. Anything that does not slugify to something (an empty name) falls
+ * back to the page rather than emitting a `#` that scrolls nowhere.
+ */
+export function cliCommandDocsUrl(commandName) {
+    const anchor = docsHeadingAnchor(commandName);
+    return anchor === "" ? CLI_DOCS_URL : `${CLI_DOCS_URL}#${anchor}`;
+}
+/**
+ * Deep link to one API operation's reference page, which is also where its
+ * request and response schemas are rendered.
+ *
+ * `tag` is the operation's first OpenAPI tag; the reference groups pages by it.
+ * An untagged operation has no page of its own, so it gets the index.
+ *
+ * `visibility` picks the tree. It defaults to `"public"`, which is right for
+ * every caller reading the consumer spec; pass `"partner"` for an operation
+ * that only appears in the partner document.
+ */
+export function apiOperationDocsUrl(operation) {
+    const base = operation.visibility === "partner" ? PARTNER_API_REFERENCE_URL : API_REFERENCE_URL;
+    const tag = operation.tag?.trim() ?? "";
+    if (tag === "" || operation.operationId.trim() === "")
+        return base;
+    return `${base}/${tag.toLowerCase()}/${operation.operationId.toLowerCase()}`;
+}

package/dist/docs/search.d.ts

@@ -26,19 +26,17 @@ export interface DocsCommandResult {
 }
 /** Entries visible at `viewTier`, in catalog order. */
 export declare function visibleEntries(index: DocsIndex, viewTier: CliDisclosureTier): DocIndexEntry[];
-/** Exact topic lookup by slug (case-insensitive). Ignores tier — explicit intent wins. */
+/** Exact topic lookup by slug (case-insensitive). Ignores tier, because explicit intent wins. */
 export declare function findTopic(index: DocsIndex, slug: string): DocIndexEntry | undefined;
 /**
- * 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.
+ * Caps ranked query results so a broad term cannot return the whole catalog
+ * (~390 entries are generated error references). An empty query is a listing,
+ * not a search, and stays uncapped.
  */
 export declare 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}.
+ * Rank docs matching `query` within the tier. An empty query returns the full
+ * tier listing in catalog order.
  */
 export declare function searchDocs(index: DocsIndex, options: {
     query?: string;

package/dist/docs/search.js

@@ -1,8 +1,7 @@
-// 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`).
+// Pure, offline search + tier filtering over a docs index. The CLI's `sf docs`
+// (bundled JSON) and the control-plane's GET /v1/docs (in-memory, catalog-
+// derived) both use it, so they rank and gate identically. ESSENTIAL by default;
+// `--full` and `--all` widen the tier.
 import { tierVisibleAt } from "../vocabulary.js";
 function toResult(entry) {
     return {
@@ -21,7 +20,7 @@ function toTopic(entry) {
 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. */
+/** Exact topic lookup by slug (case-insensitive). Ignores tier, because explicit intent wins. */
 export function findTopic(index, slug) {
     const needle = slug.trim().toLowerCase();
     if (!needle)
@@ -53,16 +52,14 @@ function scoreEntry(entry, tokens) {
     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.
+ * Caps ranked query results so a broad term cannot return the whole catalog
+ * (~390 entries are generated error references). An empty query is a listing,
+ * not a search, and stays uncapped.
  */
 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}.
+ * Rank docs matching `query` within the tier. An empty query returns the full
+ * tier listing in catalog order.
  */
 export function searchDocs(index, options) {
     const pool = visibleEntries(index, options.tier);

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

@@ -5,12 +5,15 @@ export declare const spacefastSkillRepoRef = "spacefast/plugins";
 export declare const spacefastSkillUrl: string;
 export declare const spacefastSkillFetchCommand: string;
 export declare const spacefastSkillInstallCommand = "npx -y skills add spacefast/plugins --skill spacefast -g -y";
+export declare const publishedSkillsCliPackageSpec = "skills@1.5.23";
+export declare const spacefastPublishedSkillInstallCommand = "npx -y skills@1.5.23 add spacefast/plugins --skill spacefast -g -y";
 export declare const spacefastInstallCurlCommand: string;
 export declare const spacefastInstallPowerShellCommand: string;
 export declare const spacefastInstallNpmCommand = "npm install -g spacefast";
+/** Runs the CLI with no install wherever npx exists; same commands as `sf`. */
+export declare const spacefastNpxCommand = "npx -y spacefast";
 export declare const spacefastClaudePluginAddCommand = "claude plugin marketplace add spacefast/plugins";
 export declare const spacefastClaudePluginInstallCommand = "claude plugin install spacefast@spacefast";
 export declare const spacefastClaudeDesktopExtensionUrl = "https://github.com/spacefast/plugins/releases/latest/download/claude-desktop.mcpb";
 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

@@ -1,3 +1,4 @@
+import { SKILLS_CLI_PACKAGE_SPEC } from "../agents/registry/core.js";
 import { serviceOrigin } from "../config/domains.js";
 export const spacefastSkillName = "spacefast";
 export const spacefastSkillRepoOwner = "spacefast";
@@ -5,17 +6,21 @@ export const spacefastSkillRepoName = "plugins";
 export const spacefastSkillRepoRef = `${spacefastSkillRepoOwner}/${spacefastSkillRepoName}`;
 export const spacefastSkillUrl = `${serviceOrigin("api", "prod")}/skill`;
 export const spacefastSkillFetchCommand = `curl -fsSL ${spacefastSkillUrl}`;
-export const spacefastSkillInstallCommand = `npx -y skills add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -y`;
+export const spacefastSkillInstallCommand = `npx -y ${SKILLS_CLI_PACKAGE_SPEC} add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -y`;
+// Published plugin and marketplace artifacts are scanned as executable supply-chain inputs.
+// Keep their installer exact even though interactive setup instructions intentionally track latest.
+export const publishedSkillsCliPackageSpec = "skills@1.5.23";
+export const spacefastPublishedSkillInstallCommand = `npx -y ${publishedSkillsCliPackageSpec} add ${spacefastSkillRepoRef} --skill ${spacefastSkillName} -g -y`;
 export const spacefastInstallCurlCommand = `curl -fsSL ${serviceOrigin("www", "prod")}/install.sh | bash`;
 export const spacefastInstallPowerShellCommand = `irm ${serviceOrigin("www", "prod")}/install.ps1 | iex`;
 // The npm lane: the `spacefast` package ships both the `sf` and `spacefast` bins.
 export const spacefastInstallNpmCommand = "npm install -g spacefast";
+/** Runs the CLI with no install wherever npx exists; same commands as `sf`. */
+export const spacefastNpxCommand = "npx -y spacefast";
 export const spacefastClaudePluginAddCommand = `claude plugin marketplace add ${spacefastSkillRepoRef}`;
 export const spacefastClaudePluginInstallCommand = `claude plugin install ${spacefastSkillName}@${spacefastSkillName}`;
 export const spacefastClaudeDesktopExtensionUrl = `https://github.com/${spacefastSkillRepoRef}/releases/latest/download/claude-desktop.mcpb`;
-// Codex mirrors the Claude plugin commands (same marketplace repo, same
-// plugin name); the release workflow validates both installs against the
-// assembled dist/plugins tree.
+// Codex mirrors the Claude plugin commands: same marketplace repo, same plugin
+// name. The release workflow validates both installs against dist/plugins.
 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`;