@spacefast/common 0.0.26 → 0.2.1

package/dist/docs/agent-prose.js

@@ -1,25 +1,22 @@
+import { SPACEFAST_POSITIONING } from "../brand.js";
 import { serviceOrigin } from "../config/domains.js";
-// Single home for the agent-facing prose that was triplicated across the three
-// surfaces that teach an agent how to publish:
+// Single home for the agent-facing prose the three publish-teaching surfaces
+// share:
 //
 //   - packages/cli/skill.template.md  (the SKILL.md router + copies)
 //   - packages/common/src/docs/agent-setup.ts (the /ai and /ai.txt page body)
 //   - spacefast/www                           (the agent-card / discovery prose)
 //
-// Each surface re-stated the publish sequence, the secret rules, and the receipt
-// shape in its own words, so they drifted. These fragments are the one source of
-// truth. They are plain Markdown strings (no surface-specific framing) so any
-// surface can splice them in: the skill template substitutes the `{{prose.*}}`
-// placeholders during generation, and the TS surfaces import the strings.
-//
-// Keep these grounded in the real API receipt and the real /v1/publish flow. If
-// the receipt shape or secret handling changes, change it here once.
+// These are plain Markdown strings with no surface-specific framing: the skill
+// template substitutes the `{{prose.*}}` placeholders during generation, and the
+// TS surfaces import them. Keep them grounded in the real API receipt and the
+// real /v1/publish flow; if either changes, change it here once.
 const API_ORIGIN = serviceOrigin("api", "prod");
 const PUBLISH_ENDPOINT = `${API_ORIGIN}/v1/publish`;
 const EXCHANGE_ENDPOINT = `${API_ORIGIN}/v1/claim/exchange`;
-// Centralized secret/credential patterns excluded from a publish archive. The
-// `find` preflight and the `zip -x` exclusions are derived from the same list so
-// they can never disagree, and the no-install / skill copies stay identical.
+// Secret/credential patterns excluded from a publish archive. The `find`
+// preflight and the `zip -x` exclusions both derive from this list, so the
+// no-install and skill copies cannot disagree.
 export const ARCHIVE_SECRET_GLOBS = [
     ".env*",
     ".npmrc",
@@ -58,10 +55,7 @@ function findExpr(globs) {
         .map((glob) => (glob.includes("/") ? `-path "${glob}"` : `-name "${glob}"`))
         .join(" -o ");
 }
-/**
- * The credential rules every surface must repeat. Treat tokens as secrets, keep
- * them out of logs and transcripts, and never echo them back.
- */
+/** The credential rules every surface must repeat. */
 export const SECRET_RULES_PROSE = [
     "Treat space keys, upload tokens, device codes, and API keys as credentials. Do not print",
     "them, paste them into chat, commit them, archive them, or include them in shared logs. Avoid",
@@ -70,6 +64,10 @@ export const SECRET_RULES_PROSE = [
     "clear them after use, and avoid durable auth unless the user explicitly asks.",
 ].join("\n");
 export const POSITIONING_PROSE = [
+    // What the product is, before any claim about it. One constant, shared with
+    // the dashboard's copied page context (see docs/page-context-prompt.ts).
+    SPACEFAST_POSITIONING,
+    "",
     "Spacefast is the best place to share AI artifacts.",
     "Spaces serve files directly; app code runs only through a declared Zero or Functions runtime.",
     "",
@@ -94,16 +92,18 @@ export const FAILURE_CONDUCT_PROSE = [
     FEEDBACK_PROSE,
 ].join("\n");
 export const LANE_PICKER_PROSE = [
-    "Pick the lane by environment: filesystem plus repeat work means CLI or On-Device MCP; no",
-    "filesystem means hosted MCP; one-off publish means curl; CI means an agent account. After",
-    "success, recommend the best next-time setup for the user's client.",
+    "Pick the lane by environment: a one-off publish means curl; a git checkout means the push.new",
+    "remote; repeat work with a filesystem means the CLI — the best setup, `npx -y spacefast` runs it",
+    "with no install, and `sf plugins` installs your client's plugin; no filesystem means hosted MCP;",
+    "CI means a machine OAuth client. After success, recommend the best next-time setup for the",
+    "user's client.",
 ].join("\n");
 export const HOW_TO_RESEARCH_PROSE = [
     "For an error, fetch the problem document's `type` URL. For capability questions, search the OpenAPI catalog with `execute` or append",
     "`.md` to website docs URLs. For contracts, read `publish-spec.json` or OpenAPI. Never guess",
     "limits: publish, then read diagnostics.",
 ].join("\n");
-/** Curl/API skill lane: docs URLs only — no MCP or CLI tools required. */
+/** Curl/API skill lane: docs URLs only, no MCP or CLI tools required. */
 export const HOW_TO_RESEARCH_API_PROSE = [
     "For an error, fetch the problem document's `type` URL. For capability questions, append `.md` to website docs",
     "URLs (for example `https://spacefast.com/docs/agents.md`) or read",
@@ -112,8 +112,9 @@ export const HOW_TO_RESEARCH_API_PROSE = [
 ].join("\n");
 /** MCP plugin skill lane: prefer skills for workflows and execute for the OpenAPI catalog. */
 export const HOW_TO_RESEARCH_MCP_PROSE = [
-    "For an error, fetch the problem document's `type` URL when present. For workflows, call the `skills` tool",
-    "(list/search, then read by exact name). For capability questions, use `execute` with `tools.search`.",
+    "For an error, fetch the problem document's `type` URL when present. For workflows and how-to",
+    "recipes, call `search_docs`; the `skills` tool serves the `execute` guide, not workflow recipes.",
+    "For capability questions, use `execute` with `tools.search`.",
     "For contracts, read `publish-spec.json` or OpenAPI via docs. Never guess limits: publish,",
     "then inspect status or diagnostics through `execute`.",
 ].join("\n");
@@ -128,9 +129,8 @@ export const ENV_NOTES_API_PROSE = [
     "https://spacefast.com/docs/agents.",
 ].join("\n");
 /**
- * The CHECK verb: before ever creating a space, look for the one the project
- * already has. This is what keeps a returning agent from pushing a duplicate
- * anonymous space instead of a new version.
+ * The CHECK verb: look for an existing space before creating one, so a returning
+ * agent publishes a new version instead of a duplicate anonymous space.
  */
 export const CHECK_BEFORE_PUBLISH_PROSE = [
     "Before creating a space, check whether this project already has one:",
@@ -220,6 +220,34 @@ export const SAVE_STATE_MCP_PROSE = [
  * The UPDATE verb: a new version to the SAME space. Never re-run the
  * first-publish recipe when saved state exists.
  */
+/*
+ * Push to deploy. Written for an agent that is already in a checkout, where a
+ * push is fewer moves than an upload — and where the receipt comes back in the
+ * push output, so there is no second call to learn the URL.
+ *
+ * The GitHub note is not an aside: a space bound to a GitHub repository refuses
+ * direct pushes, and an agent that does not know that reads the refusal as a
+ * broken remote instead of as the answer it is.
+ */
+export const PUSH_TO_DEPLOY_PROSE = [
+    "A space's git remote is a real remote, and pushing to it publishes. Every publish receipt",
+    "and the Space resource carry `git.remoteUrl`; authenticate as HTTP Basic user `t` with the",
+    "space key or an API key as the password. The same key you already have works — publishing",
+    "and pushing are one credential, not two.",
+    "",
+    "```bash",
+    "git remote add spacefast https://t:<key>@push.new/<space-slug>.git",
+    "git push spacefast main",
+    "```",
+    "",
+    "The push output is the receipt: it reports the live URL, the immutable version URL, and —",
+    "for an anonymous space — the claim link and its expiry, as `remote:` lines. Report those to",
+    "the user the same way you would report a publish receipt. A deploy that outruns the push",
+    "prints a status URL instead and finishes on its own; the push still exits 0.",
+    "",
+    "If `git.managedBy` is `github`, this space deploys from `git.repository` and a direct push is",
+    "refused. Push to that GitHub repository instead, or tell the user to disconnect GitHub first.",
+].join("\n");
 export const UPDATE_SPACE_PROSE = [
     "To publish a new version of an existing space, send the same `spaceId` with bearer auth —",
     "never re-run the first-publish recipe when saved state exists:",
@@ -256,7 +284,7 @@ export const CONTINUE_AFTER_CLAIM_PROSE = [
     "Save `data.credential.accessToken` into `.spacefast/state.json` (replace the `claimToken`",
     'field with `"accessToken"`), then retry the publish with the new bearer. The exchange works',
     "exactly once; if it returns `continuation_used` or `continuation_unavailable`, ask the user",
-    "to create an API key in the dashboard (Account → API keys).",
+    "to create an API key in the dashboard (team → Agents → API keys).",
 ].join("\n");
 const LEXICAL_PUBLISH_PATH_PREFLIGHT = [
     'case "$publish_target" in /*) check_path="$publish_target" ;; *) check_path="$PWD/$publish_target" ;; esac',
@@ -322,7 +350,7 @@ const SECURE_ARCHIVE_RECIPE = [
 ];
 /**
  * The zero-install publish sequence: a replay-safe curl loop for a file, a
- * secret-preflighted zip for a folder. This is the load-bearing rung 0 — an
+ * secret-preflighted zip for a folder. This is the load-bearing rung 0. An
  * agent that stops here must still succeed.
  */
 export const PUBLISH_SEQUENCE_PROSE = [
@@ -376,7 +404,7 @@ export const PUBLISH_SEQUENCE_PROSE = [
  * What the JSON publish receipt contains and how to read it. The receipt is the
  * source of truth; never invent a separate success signal.
  */
-export const RECEIPT_SHAPE_PROSE = [
+export const RECEIPT_CONTRACT_PROSE = [
     "The JSON receipt is the source of truth:",
     "",
     "- `data.space.liveUrl` — the live URL.",
@@ -422,18 +450,14 @@ export const SIGNED_UPLOAD_PROSE = [
     "For each `data.upload.targets[]`, send `target.method` to `target.url` with `target.headers`.",
     'If `target.body.kind` is `url`, send JSON `{ "url": target.body.url }`; otherwise send the',
     "local file bytes for `target.path`. Then call `data.links.finalize` and share the final receipt.",
-    "If the session expires or only a page of files is returned, follow `data.links.resume`.",
+    "If the session expires or only a page of files is returned, follow `data.links.refresh`.",
     "",
     "A manifest entry may name a `sourceUrl`, so bytes that already live on a public HTTPS URL never",
     "have to round-trip through the agent. Do not base64 large archives into chat or MCP tool arguments.",
 ].join("\n");
 /**
- * Named fragments for the skill-template generator. The templates carry
- * `{{prose.secretRules}}`, `{{prose.publishSequence}}`,
- * `{{prose.receiptShape}}`, `{{prose.signedUpload}}`,
- * `{{prose.checkBeforePublish}}`, `{{prose.saveState}}`,
- * `{{prose.updateSpace}}`, and `{{prose.continueAfterClaim}}` placeholders;
- * generate-skill.mjs substitutes these.
+ * Named fragments for the skill-template generator: the templates carry
+ * `{{prose.<key>}}` placeholders and generate-skill.mjs substitutes these.
  */
 export const AGENT_PROSE = {
     positioning: POSITIONING_PROSE,
@@ -441,7 +465,7 @@ export const AGENT_PROSE = {
     explainToUser: EXPLAIN_TO_USER_PROSE,
     failureConduct: FAILURE_CONDUCT_PROSE,
     publishSequence: PUBLISH_SEQUENCE_PROSE,
-    receiptShape: RECEIPT_SHAPE_PROSE,
+    receiptContract: RECEIPT_CONTRACT_PROSE,
     signedUpload: SIGNED_UPLOAD_PROSE,
     checkBeforePublish: CHECK_BEFORE_PUBLISH_PROSE,
     checkBeforePublishApi: CHECK_BEFORE_PUBLISH_API_PROSE,
@@ -451,6 +475,7 @@ export const AGENT_PROSE = {
     saveStateApi: SAVE_STATE_API_PROSE,
     saveStateMcp: SAVE_STATE_MCP_PROSE,
     updateSpace: UPDATE_SPACE_PROSE,
+    pushToDeploy: PUSH_TO_DEPLOY_PROSE,
     continueAfterClaim: CONTINUE_AFTER_CLAIM_PROSE,
     lanePicker: LANE_PICKER_PROSE,
     howToResearch: HOW_TO_RESEARCH_PROSE,

package/dist/docs/agent-setup.d.ts

@@ -1,73 +1,104 @@
 import { type ConnectTarget, type ConnectTargetId } from "../agents/connect-targets.js";
+import type { AgentHandoffTarget } from "../contracts/device-auth.js";
 export declare const agentSetupUrl: string;
-export declare const agentSetupTextUrl: string;
 export declare const agentSetupHostLabel: string;
 export declare const agentSetupPrompt: string;
 export declare const anonymousPublishCurlCommand: string;
+export declare const AGENT_HANDOFF_TOKEN_PATTERN: RegExp;
 /**
- * Typed, safe decline states for the app-private redemption exchange.
- * `invalid_handoff` is the single answer for both an unknown document ID and a wrong secret, so a
- * decline never becomes an existence oracle; state-specific reasons are returned only after the
- * supplied secret authenticates the handoff. `already_redeemed` makes one-use explicit: after the
- * first exchange succeeds, the second fails with this reason. Declines are terminal and never
- * reveal whether a secret was close to correct.
+ * Decline states for the app-private redemption exchange. `invalid_handoff` is
+ * the single answer for both an unknown document ID and a wrong secret, so a
+ * decline never becomes an existence oracle; the other reasons are returned only
+ * after the supplied secret authenticates the handoff. Declines are terminal.
  */
 export declare const AGENT_HANDOFF_DECLINE_REASONS: readonly ["invalid_handoff", "expired", "already_redeemed", "revoked", "client_mismatch", "origin_mismatch"];
 export type AgentHandoffDeclineReason = (typeof AGENT_HANDOFF_DECLINE_REASONS)[number];
-export type AgentHandoffAction = Readonly<{
-    kind: "copy";
-    label: string;
-    sensitive: boolean;
-    value: string;
-}> | Readonly<{
-    kind: "open";
-    label: string;
-    href: string;
-}>;
 export type AgentHandoff = Readonly<{
-    actions: readonly AgentHandoffAction[];
-    documentUrl: string;
-    instructions: string;
     prompt: string;
+    secret: string;
+    url: string;
 }>;
 /**
  * The single shared grammar for handoff links:
- * `<access-origin>/agent/<documentId>/<oneUseToken>`. The document ID must match
- * `[A-Za-z0-9_-]{1,512}` and the token `[A-Za-z0-9_-]{16,512}`; the two must differ;
- * queries, fragments, and URL userinfo are forbidden. The URL must sit exactly on the caller's
- * configured HTTP(S) access origin; the clean static document may live on a separate explicitly
- * supplied dashboard origin.
- * Normalization is part of the contract: the input is WHATWG-URL-normalized first (backslashes,
- * dot segments, stray tab/CR/LF, empty userinfo, case, default ports), the grammar is enforced on
- * the normalized URL, and only the reconstructed canonical URL ever leaves this function.
- * Dashboard minting, CLI ingestion, and control-plane validation must all use this parser so the
- * grammar can never fork.
+ * `<access-origin>/handoffs/<token>`. The token is the bearer credential.
+ * Queries, fragments, and userinfo are forbidden. Dashboard minting, CLI
+ * ingestion, and control-plane redemption all use this parser so the grammar
+ * cannot fork.
  */
-export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string, documentOrigin?: string): Readonly<{
-    documentId: string;
-    documentUrl: string;
+export type ParsedAgentHandoffUrl = Readonly<{
+    /** The canonical link, exactly as it must be presented back for redemption. */
     handoffUrl: string;
+    /** The bearer credential carried in the last path segment. */
     secret: string;
 }>;
+export declare function parseAgentHandoffUrl(value: string, expectedOrigin: string): ParsedAgentHandoffUrl;
 /** Connect targets whose handoff continues through the CLI stdin exchange. */
 export declare const AGENT_HANDOFF_CLI_TARGET_IDS: readonly ConnectTargetId[];
-export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before installing tools or publishing. Confirm the file or folder they want to publish.";
-/** The fetch-safety contract: reading the document never consumes or leaks a handoff. */
-export declare const AGENT_HANDOFF_FETCH_SAFETY = "Keep the original handoff link private. Fetching this clean document URL did not use or send its credential; the credential is spent only by one successful exchange. An expired, used, or revoked link fails safely, so ask the user for a fresh one from the dashboard.";
-export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the private handoff URL out of commands, request URLs, logs, and replies.";
+export declare const AGENT_HANDOFF_PREAMBLE = "Talk to the user before you install tools or publish. Confirm the file or folder to publish.";
+export declare const AGENT_HANDOFF_CREDENTIAL_HYGIENE = "Keep the handoff URL out of command arguments, logs, and replies. It goes in exactly two places: the stdin prompt of `sf setup agent`, or the redeem request body.";
 export declare const AGENT_HANDOFF_CLI_APPROVAL_GUIDANCE: string;
-export declare const AGENT_HANDOFF_BROWSER_APPROVAL_GUIDANCE = "When the client opens browser approval, ask the user to approve there before publishing.";
-export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After approval, confirm the selected Space and permissions, then publish only the files the user approved. Report the bare Live and immutable Version addresses separately from the private Access URL; create a scoped Link when a recipient needs access.";
+export declare const AGENT_HANDOFF_PUBLISH_PROSE = "After login, confirm the Space and the files with the user, then publish the simplest way that fits: a one-off through `sf publish` or the publish API; a git checkout by pushing to the Space's push.new remote (`git.remoteUrl`); for repeat work the CLI is best, and `sf plugins` installs your client's plugin. Report the Live URL and the immutable Version URL; keep the private Access URL out of shared replies. Create a scoped Link only when a recipient needs access.";
 /** One target's Connect prose: blurb, copyable setup blocks, deeplink/download lines. */
 export declare function agentHandoffConnectSections(target: ConnectTarget): string[];
+/**
+ * Everything the agent needs to know about the link, said once, where it acts
+ * on it. "The URL you fetched" doubles as the only reference to the bearer —
+ * the document never repeats it, so the live secret stays out of whatever the
+ * agent caches or quotes next (`renderAgentHandoffDocument` takes an ORIGIN,
+ * never a URL, so the token cannot even reach the renderer).
+ */
+export declare const AGENT_HANDOFF_EXCHANGE_PROSE: string;
+/**
+ * The per-handoff setup document served from `/handoffs/<token>`.
+ *
+ * Takes the handoff's ORIGIN, never its URL: the bearer must not be able to
+ * reach this renderer, so it cannot end up in the bytes an agent caches.
+ *
+ * Reading order is the argument: what Spacefast is, talk to the user, exchange
+ * the link for a durable API key — the only expiring step, so it comes before
+ * client setup — then connect the client, then publish.
+ */
+export declare function renderAgentHandoffDocument(input: {
+    handoffOrigin: string;
+    mcpEndpoint: string;
+    targetId: AgentHandoffTarget;
+}): string;
+/**
+ * The document behind an anonymous (signed-out) handoff link. Same opening as
+ * the signed-in "any" document, ordered by usefulness: the two things the
+ * agent can actually do (publish with the no-account POST, or have the user
+ * sign in for a real handoff) come before the optional client catalog. The
+ * link itself grants nothing — its fetch only feeds the /start arrival watch —
+ * and the document doesn't narrate that; "Get a credential" states the one
+ * fact the agent needs.
+ */
+export declare function renderAnonymousAgentHandoffDocument(input: {
+    mcpEndpoint: string;
+}): string;
 /** Builds every copy-ready handoff artifact from one validated URL and target catalog row. */
 export declare function buildAgentHandoff(input: {
     expectedOrigin: string;
-    documentOrigin?: string;
     mcpEndpoint: string;
     targetId: ConnectTargetId;
     url: string;
 }): AgentHandoff;
+/**
+ * The signed-out half: a handoff that carries no team, no Space, and no
+ * authority, so its document is the public setup guide. It exists only so the
+ * fetch is observable — /start can tell the visitor their agent arrived without
+ * first making them sign up.
+ *
+ * The handoff line is APPENDED to the caller's prompt rather than replacing it:
+ * signed out, the prompt is still the thing carrying the user's actual task.
+ * One gesture, one sentence, single-sourced so no surface can word it
+ * differently. With no task selected the handoff line IS the prompt — the
+ * fetched document carries the whole setup, so the copy stays a single link.
+ */
+export declare function buildAnonymousAgentHandoff(input: {
+    expectedOrigin: string;
+    url: string;
+    /** The caller's own prompt text. The handoff line goes after it. */
+    context: string;
+}): AgentHandoff;
 export declare function renderAgentSetupTemplate(value: string): string;
-export declare function aiInstructionsText(): string;
 export declare function agentSetupMarkdown(): string;