@spacefast/common 0.0.24 → 0.2.1

package/dist/utils/grants.js

@@ -27,8 +27,10 @@ function targetMatches(selector, target) {
             return target.kind === "version" && target.versionId === selector.versionId;
         case "branch":
             return target.kind === "branch" && target.branch === selector.branch;
+        // Immutable Version hosts only. The live host is its own target: sharing
+        // "every Version" does not thereby publish the live site.
         case "all_versions":
-            return target.kind === "live" || target.kind === "version";
+            return target.kind === "version";
     }
     throw new Error("Unsupported Grant target.");
 }
@@ -71,12 +73,10 @@ export function grantResourcePatternMatches(pattern, resource, resourceKind = "r
     return matches(0, 0);
 }
 /**
- * Exclude patterns read wider than include patterns, and that asymmetry is the
- * rule, not an accident: the route lane collapses a terminal `index.html`
- * (normalizeAccessScopePath) while the artifact lane keeps it, so an exclude
- * naming an index artifact must also close the route that artifact serves.
- * Include never gets the same courtesy — granting the stripped route would hand
- * out access nobody wrote down. The serving engine compiles the identical pair
+ * Exclude reads wider than include, deliberately: the route lane collapses a
+ * terminal `index.html`, so an exclude naming an index artifact must also close
+ * the route it serves. Include must not, or it would grant a route nobody wrote
+ * down. The serving engine compiles the same pair
  * (access-rules.php _stattic_grant_exclude_pattern_variants).
  */
 function grantExcludePatternMatches(pattern, resource, resourceKind) {
@@ -88,7 +88,6 @@ function grantExcludePatternMatches(pattern, resource, resourceKind) {
     const stripped = canonical.slice(0, -"/index.html".length);
     return grantResourcePatternMatches(stripped === "" ? "/" : stripped, resource, resourceKind);
 }
-/** Does a Grant's resource set reach this path? Include, minus exclude. */
 export function grantResourceSetMatches(resources, resource, resourceKind = "route") {
     return (resources.include.some((pattern) => grantResourcePatternMatches(pattern, resource, resourceKind)) &&
         !resources.exclude.some((pattern) => grantExcludePatternMatches(pattern, resource, resourceKind)));

package/dist/utils/gravatar.d.ts

@@ -1,9 +1,7 @@
-/** Gravatar's canonical address form: trimmed and lowercased. */
 export declare function normalizeGravatarEmail(email: string | null | undefined): string | null;
-/** The canonical avatar URL for an already-computed SHA-256 hash. */
 export declare function gravatarUrlFromHash(hashHex: string): string;
 /**
- * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
- * a browser can derive it locally and never send the raw address anywhere.
+ * Gravatar's identifier, the SHA-256 hex of a normalized email. WebCrypto lets
+ * a browser derive it locally and never send the raw address anywhere.
  */
 export declare function gravatarEmailHash(email: string | null | undefined): Promise<string | null>;

package/dist/utils/gravatar.js

@@ -1,26 +1,20 @@
 /**
- * The one Gravatar URL shape Spacefast emits. Every surface — control-plane
- * profiles, the Comments SDK, Slack notifications — derives the same address
- * for the same person, so an avatar is recognizable wherever it appears and
- * Cast can validate a guest avatar against a single pattern.
- *
- * `d=404` is deliberate: a person without a Gravatar gets no image at all, and
- * the consumer renders its own initials/palette fallback instead of a stock
- * silhouette. `s=160` covers the largest avatar we render, retina included.
+ * The one Gravatar URL shape Spacefast emits, so Cast can validate a guest
+ * avatar against a single pattern. `d=404` returns no image for a person
+ * without a Gravatar, leaving the consumer's own fallback to render; `s=160`
+ * covers the largest avatar we render, retina included.
  */
 const GRAVATAR_AVATAR_QUERY = "d=404&r=g&s=160";
-/** Gravatar's canonical address form: trimmed and lowercased. */
 export function normalizeGravatarEmail(email) {
     const normalized = email?.trim().toLowerCase();
     return normalized ? normalized : null;
 }
-/** The canonical avatar URL for an already-computed SHA-256 hash. */
 export function gravatarUrlFromHash(hashHex) {
     return `https://gravatar.com/avatar/${hashHex}?${GRAVATAR_AVATAR_QUERY}`;
 }
 /**
- * SHA-256 hex of a normalized email — Gravatar's identifier. Uses WebCrypto so
- * a browser can derive it locally and never send the raw address anywhere.
+ * Gravatar's identifier, the SHA-256 hex of a normalized email. WebCrypto lets
+ * a browser derive it locally and never send the raw address anywhere.
  */
 export async function gravatarEmailHash(email) {
     const normalized = normalizeGravatarEmail(email);

package/dist/utils/id-hints.js

@@ -1,17 +1,12 @@
-// Shared not-found self-correction (W1). One source for the closest-candidate
-// ranking used by every resource's 404 hint builder (spaces, versions, teams,
-// domains). Resources differ only in which caller-scoped rows they feed in and
-// which keys they expose for matching; keeping the levenshtein/closeness/ranking
-// here prevents per-resource drift. Callers are responsible for scoping the rows
-// to the caller principal — this module never touches the DB or auth.
-// How many caller-scoped rows a hint builder will scan to rank candidates. Above
-// this the collection is treated as too large to rank for free, so the builder
-// returns only the recovery hint (no candidate ids).
+// One closest-candidate ranking for every resource's 404 hint builder (spaces,
+// versions, teams, domains). Callers scope the rows to the caller principal;
+// this module never touches the DB or auth.
+// Above this many rows the collection is too large to rank for free, and the
+// builder returns the recovery hint without candidate ids.
 export const HINT_SCAN_CAP = 200;
 export const HINT_MAX_CANDIDATES = 5;
-// All supported hint keys (ids, slugs, hostnames, and numeric version refs) fit
-// within this ceiling. Rejecting larger values keeps best-effort 404 recovery
-// from turning attacker-controlled refs or stored labels into quadratic work.
+// Every hint key (ids, slugs, hostnames, version refs) fits here. Rejecting
+// larger values keeps attacker-controlled refs out of quadratic work.
 export const HINT_MAX_KEY_LENGTH = 256;
 function boundedLevenshtein(a, b, maxDistance) {
     if (Math.abs(a.length - b.length) > maxDistance)
@@ -48,9 +43,8 @@ export function levenshtein(a, b) {
     }
     return boundedLevenshtein(a, b, Math.max(a.length, b.length));
 }
-// Returns a small finite score the closer `candidate` is to `needle`, or
-// +Infinity when they are not genuinely close. Exact match = 0; substring
-// containment = 1; otherwise a typo within a length-bounded edit distance.
+// Lower is closer, +Infinity when not close at all: exact = 0, substring
+// containment = 1, otherwise 1 + a length-bounded edit distance.
 export function refCloseness(needle, candidate) {
     if (!candidate)
         return Number.POSITIVE_INFINITY;
@@ -61,22 +55,19 @@ export function refCloseness(needle, candidate) {
         return 0;
     if (candidate.includes(needle) || needle.includes(candidate))
         return 1;
-    // Only surface genuinely close typos: bound the allowed distance by the shorter
-    // string so short refs don't match everything.
+    // Bound the distance by the shorter string so short refs don't match everything.
     const tolerance = Math.max(2, Math.floor(Math.min(needle.length, candidate.length) / 3));
     const distance = boundedLevenshtein(needle, candidate, tolerance);
     return distance <= tolerance ? 1 + distance : Number.POSITIVE_INFINITY;
 }
-// Rank `rows` by how close any of their keys are to `ref`, returning at most
-// `max` closest rows. A row whose every key is far (or absent) is dropped, so
-// only genuine near-matches surface. Ties break by the optional comparator
-// (e.g. recency); keys are matched case-insensitively.
+// Rank `rows` by their closest key to `ref`, at most `max` rows. Rows with no
+// close key are dropped. Ties break by the optional comparator; keys match
+// case-insensitively.
 export function rankCandidates(ref, rows, keysOf, options) {
     if (rows.length > HINT_SCAN_CAP || ref.length > HINT_MAX_KEY_LENGTH)
         return [];
     const needle = ref.toLowerCase();
-    // Unicode case conversion can expand a string (for example, U+0130). Keep
-    // that normalized representation under the same work ceiling too.
+    // Lowercasing can expand a string (U+0130), so re-check the ceiling.
     if (needle.length > HINT_MAX_KEY_LENGTH)
         return [];
     const max = options?.max ?? HINT_MAX_CANDIDATES;

package/dist/utils/idempotency.d.ts

@@ -1,6 +1,6 @@
 /**
- * Stable, secret-safe key for one exact logical mutation attempt. Shared by
- * every client surface: the same publish issued through the CLI and through
- * MCP must land on one key or the API stops deduplicating the retry.
+ * Stable, secret-safe key for one logical mutation attempt. The same publish
+ * from the CLI and from MCP must land on one key, or the API stops
+ * deduplicating the retry.
  */
 export declare function stableIdempotencyKey(prefix: string, parts: unknown): string;

package/dist/utils/idempotency.js

@@ -1,9 +1,8 @@
 import { createHash } from "node:crypto";
 /**
- * Key-sorted JSON that treats an absent key and an `undefined` value as the
- * same thing. Deliberately *not* `canonicalJson`: a key the CLI omits and one
- * the MCP server sets to `undefined` describe the same mutation, so they have
- * to hash alike. Merging the two spellings would change every minted key.
+ * Key-sorted JSON that treats an absent key and an `undefined` value alike: a
+ * key the CLI omits and one MCP sets to `undefined` are the same mutation.
+ * Deliberately not `canonicalJson`; merging the two would change every key.
  */
 function keyJson(value) {
     if (Array.isArray(value)) {
@@ -19,9 +18,9 @@ function keyJson(value) {
     return JSON.stringify(value ?? null);
 }
 /**
- * Stable, secret-safe key for one exact logical mutation attempt. Shared by
- * every client surface: the same publish issued through the CLI and through
- * MCP must land on one key or the API stops deduplicating the retry.
+ * Stable, secret-safe key for one logical mutation attempt. The same publish
+ * from the CLI and from MCP must land on one key, or the API stops
+ * deduplicating the retry.
  */
 export function stableIdempotencyKey(prefix, parts) {
     return `${prefix}-${createHash("sha256").update(keyJson(parts)).digest("hex")}`;

package/dist/utils/local-space-state.d.ts

@@ -5,16 +5,13 @@ export declare const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
 /**
  * Local Spacefast checkout contract.
  *
- * `.spacefast/space.json` is the committable selection axis: it names which
- * space a checkout targets (`space`) and may carry non-secret provider/team
- * coordinates (`team`, `apiBaseUrl`). It must not carry credentials.
+ * `.spacefast/space.json` is the committable selection axis: which space a
+ * checkout targets, plus non-secret provider/team coordinates. Never credentials.
  *
- * `.spacefast/state.json` is the local credential/cache axis: it records the
- * resolved `spaceId`, provider `apiUrl`, anonymous `claimToken` before claim,
- * durable `accessToken` after continuation, and small publish caches such as
- * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written.
- * The strict versioned schema fails closed instead of letting an older tool
- * reinterpret fields written under a contract it does not understand.
+ * `.spacefast/state.json` is the secret axis: credentials and small publish
+ * caches, machine-written, gitignored, merge-written. Its strict versioned
+ * schema fails closed rather than let an older tool reinterpret fields written
+ * under a contract it does not understand.
  */
 export declare const localSpaceLinkSchema: z.ZodObject<{
     team: z.ZodOptional<z.ZodString>;
@@ -22,6 +19,12 @@ export declare const localSpaceLinkSchema: z.ZodObject<{
     apiBaseUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export declare const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
+export declare const creationAttemptSchema: z.ZodObject<{
+    key: z.ZodString;
+    principal: z.ZodString;
+    kind: z.ZodLiteral<"authenticated">;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
 export declare const localSpaceStateSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     spaceId: z.ZodOptional<z.ZodString>;
@@ -41,22 +44,14 @@ export declare const localSpaceStateSchema: z.ZodObject<{
     pendingPublish: z.ZodOptional<z.ZodObject<{
         key: z.ZodString;
         principal: z.ZodString;
-        kind: z.ZodEnum<{
-            anonymous: "anonymous";
-            authenticated: "authenticated";
-        }>;
-        intent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"authenticated">;
         createdAt: z.ZodString;
     }, z.core.$strict>>;
     /** Settled creation receipt identity retained for invocations that began before its commit. */
     creationReplay: z.ZodOptional<z.ZodObject<{
         key: z.ZodString;
         principal: z.ZodString;
-        kind: z.ZodEnum<{
-            anonymous: "anonymous";
-            authenticated: "authenticated";
-        }>;
-        intent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"authenticated">;
         createdAt: z.ZodString;
     }, z.core.$strict>>;
     /** Random replay capability reserved before consuming a claim credential. */
@@ -126,17 +121,15 @@ export declare function localSpaceStateDir(root: string): string;
 export declare function localSpaceStatePath(root: string): string;
 export declare function localSpaceLinkPath(root: string): string;
 export declare function readLocalSpaceLink(root: string): Promise<LocalSpaceLink | null>;
-/** Like readLocalSpaceLink, but reports the file path alongside the link. */
 export declare function readLocalSpaceLinkWithPath(root: string): Promise<{
     link: LocalSpaceLink;
     path: string;
 } | null>;
 export declare function readLocalSpaceStateAt(root: string): Promise<DiscoveredLocalSpaceState | null>;
 /**
- * Walk up from `startDir` to the filesystem root (or `boundary`, when given),
- * returning the first non-null result of `probe`. Shared by every "nearest
- * checkout marker" lookup (state+link discovery here, the CLI's link-only
- * discovery) so the traversal rules live in one place.
+ * Walk up from `startDir` to the filesystem root (or `boundary`), returning the
+ * first non-null `probe` result. Every "nearest checkout marker" lookup shares
+ * it so the traversal rules live in one place.
  */
 export declare function findUpward<T>(probe: (dir: string) => Promise<T | null>, startDir?: string, boundary?: string): Promise<T | null>;
 export declare function discoverLocalSpaceState(startDir?: string, boundary?: string): Promise<DiscoveredLocalSpaceState | null>;
@@ -146,9 +139,9 @@ export declare function mutateLocalSpaceState(root: string, mutate: (current: Lo
     afterBackup?: (() => void | Promise<void>) | undefined;
     /** Fault-injection observer used to synchronize concurrency tests. */
     onConflict?: (() => void | Promise<void>) | undefined;
+    /** Reports whether this mutation changed `.gitignore`. */
+    onGitignoreResult?: ((changed: boolean) => void) | undefined;
 }): Promise<LocalSpaceStateFile>;
-export declare function writeLocalSpaceState(root: string, state: LocalSpaceStateWrite): Promise<string>;
-/** Reserve random replay custody before a claim token can be consumed. */
 export declare function reserveLocalCredentialReplay(root: string, input: {
     operation: LocalCredentialReplayOperation;
     claimToken: string;
@@ -158,4 +151,8 @@ export declare function saveLocalSpaceState(root: string, input: SaveLocalSpaceS
     statePath: string;
     linkPath: string;
     wroteLink: boolean;
+    gitignore: {
+        path: string;
+        changed: boolean;
+    };
 }>;

package/dist/utils/local-space-state.js

@@ -10,16 +10,13 @@ export const LOCAL_SPACE_STATE_FILE_NAME = "state.json";
 /**
  * Local Spacefast checkout contract.
  *
- * `.spacefast/space.json` is the committable selection axis: it names which
- * space a checkout targets (`space`) and may carry non-secret provider/team
- * coordinates (`team`, `apiBaseUrl`). It must not carry credentials.
+ * `.spacefast/space.json` is the committable selection axis: which space a
+ * checkout targets, plus non-secret provider/team coordinates. Never credentials.
  *
- * `.spacefast/state.json` is the local credential/cache axis: it records the
- * resolved `spaceId`, provider `apiUrl`, anonymous `claimToken` before claim,
- * durable `accessToken` after continuation, and small publish caches such as
- * `lastVersionId`. It is secret, machine-written, gitignored, and merge-written.
- * The strict versioned schema fails closed instead of letting an older tool
- * reinterpret fields written under a contract it does not understand.
+ * `.spacefast/state.json` is the secret axis: credentials and small publish
+ * caches, machine-written, gitignored, merge-written. Its strict versioned
+ * schema fails closed rather than let an older tool reinterpret fields written
+ * under a contract it does not understand.
  */
 export const localSpaceLinkSchema = z
     .object({
@@ -29,6 +26,17 @@ export const localSpaceLinkSchema = z
 })
     .loose();
 export const LOCAL_SPACE_STATE_SCHEMA_VERSION = 1;
+// One reservation, two slots: it is written as `pendingPublish` and moved to
+// `creationReplay` once its receipt commits. Space creation is the only
+// mutation that reserves one. Credential-free publishes are not idempotent.
+export const creationAttemptSchema = z
+    .object({
+    key: z.string().min(1),
+    principal: z.string().regex(/^[0-9a-f]{64}$/),
+    kind: z.literal("authenticated"),
+    createdAt: z.string().datetime(),
+})
+    .strict();
 export const localSpaceStateSchema = z.strictObject({
     schemaVersion: z.literal(LOCAL_SPACE_STATE_SCHEMA_VERSION),
     spaceId: z.string().min(1).optional(),
@@ -45,27 +53,9 @@ export const localSpaceStateSchema = z.strictObject({
     /** Secret per-checkout entropy used only to namespace replay-safe first publishes. */
     anonymousPublishNonce: z.string().min(32).optional(),
     /** Unsettled first-publish mutation. Retries must reuse this exact key. */
-    pendingPublish: z
-        .object({
-        key: z.string().min(1),
-        principal: z.string().regex(/^[0-9a-f]{64}$/),
-        kind: z.enum(["anonymous", "authenticated"]),
-        intent: z.string().min(1).optional(),
-        createdAt: z.string().datetime(),
-    })
-        .strict()
-        .optional(),
+    pendingPublish: creationAttemptSchema.optional(),
     /** Settled creation receipt identity retained for invocations that began before its commit. */
-    creationReplay: z
-        .object({
-        key: z.string().min(1),
-        principal: z.string().regex(/^[0-9a-f]{64}$/),
-        kind: z.enum(["anonymous", "authenticated"]),
-        intent: z.string().min(1).optional(),
-        createdAt: z.string().datetime(),
-    })
-        .strict()
-        .optional(),
+    creationReplay: creationAttemptSchema.optional(),
     /** Random replay capability reserved before consuming a claim credential. */
     pendingCredentialReplay: z
         .object({
@@ -152,7 +142,6 @@ function linkSpaceId(link) {
 export async function readLocalSpaceLink(root) {
     return (await readLocalSpaceLinkWithPath(root))?.link ?? null;
 }
-/** Like readLocalSpaceLink, but reports the file path alongside the link. */
 export async function readLocalSpaceLinkWithPath(root) {
     const primary = parseLink(await readJsonFile(root, path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME)));
     return primary ? { link: primary, path: localSpaceLinkPath(root) } : null;
@@ -190,10 +179,9 @@ function isWithinBoundary(current, boundary) {
     return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 /**
- * Walk up from `startDir` to the filesystem root (or `boundary`, when given),
- * returning the first non-null result of `probe`. Shared by every "nearest
- * checkout marker" lookup (state+link discovery here, the CLI's link-only
- * discovery) so the traversal rules live in one place.
+ * Walk up from `startDir` to the filesystem root (or `boundary`), returning the
+ * first non-null `probe` result. Every "nearest checkout marker" lookup shares
+ * it so the traversal rules live in one place.
  */
 export async function findUpward(probe, startDir = process.cwd(), boundary) {
     let current = path.resolve(startDir);
@@ -258,7 +246,7 @@ async function ensureStateGitignored(root, onConflict) {
             const lines = raw.split(/\r?\n/);
             const missing = entries.filter((entry) => !lines.includes(entry));
             if (missing.length === 0)
-                return;
+                return false;
             const prefix = raw.length > 0 && !raw.endsWith("\n") ? "\n" : "";
             await secureWriteFile({
                 root,
@@ -268,7 +256,7 @@ async function ensureStateGitignored(root, onConflict) {
                 mode: 0o644,
                 expectedContent: existing,
             });
-            return;
+            return true;
         }
         catch (error) {
             if (error instanceof SecureLocalFileConflictError)
@@ -281,6 +269,7 @@ async function ensureStateGitignored(root, onConflict) {
         }
     }
     /* eslint-enable no-await-in-loop */
+    throw new LocalSpaceStateConflictError("Local .gitignore stayed busy for too long.");
 }
 function assignDefined(target, input) {
     for (const [key, value] of Object.entries(input)) {
@@ -315,7 +304,8 @@ export async function writeLocalSpaceLink(root, link) {
 }
 export async function mutateLocalSpaceState(root, mutate, options = {}) {
     const stateRelativePath = path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_STATE_FILE_NAME);
-    await ensureStateGitignored(root, options.onConflict);
+    const gitignoreChanged = await ensureStateGitignored(root, options.onConflict);
+    options.onGitignoreResult?.(gitignoreChanged);
     /* eslint-disable no-await-in-loop -- compare-and-swap retries are intentionally serialized against the latest committed state. */
     for (let attempt = 1; attempt <= LOCAL_STATE_MUTATION_ATTEMPTS; attempt += 1) {
         try {
@@ -327,8 +317,8 @@ export async function mutateLocalSpaceState(root, mutate, options = {}) {
             const current = parsed?.success
                 ? parsed.data
                 : { schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION };
-            // The callback may run again after a compare-and-swap collision. Keeping it
-            // synchronous makes remote effects and other one-shot work impossible here.
+            // The callback may run again after a compare-and-swap collision; keeping
+            // it synchronous rules out one-shot work inside it.
             const payload = localSpaceStateSchema.parse({
                 ...mutate(structuredClone(current)),
                 schemaVersion: LOCAL_SPACE_STATE_SCHEMA_VERSION,
@@ -360,10 +350,6 @@ export async function mutateLocalSpaceState(root, mutate, options = {}) {
     /* eslint-enable no-await-in-loop */
     throw new LocalSpaceStateConflictError("Local Spacefast state stayed busy for too long.");
 }
-export async function writeLocalSpaceState(root, state) {
-    await mutateLocalSpaceState(root, () => state);
-    return localSpaceStatePath(root);
-}
 function credentialFingerprint(credential) {
     return createHash("sha256").update(credential).digest("hex");
 }
@@ -373,7 +359,6 @@ function sameCredentialReplay(left, right) {
         left.key === right.key &&
         left.principal === right.principal);
 }
-/** Reserve random replay custody before a claim token can be consumed. */
 export async function reserveLocalCredentialReplay(root, input) {
     const identity = createOneShotReplayIdentity(`sf-${input.operation}`);
     const candidate = {
@@ -407,6 +392,7 @@ function credentialMatches(state, expected) {
     return state.claimToken === expected.claimToken && state.accessToken === expected.accessToken;
 }
 export async function saveLocalSpaceState(root, input) {
+    let gitignoreChanged = false;
     await mutateLocalSpaceState(root, (existing) => {
         if (existing.spaceId && existing.spaceId !== input.spaceId && !input.replaceSpace) {
             throw new LocalSpaceStateConflictError(`Local Spacefast state changed from ${input.spaceId} to ${existing.spaceId}.`);
@@ -484,6 +470,10 @@ export async function saveLocalSpaceState(root, input) {
             delete next.pendingCredentialReplay;
         }
         return localSpaceStateSchema.parse(next);
+    }, {
+        onGitignoreResult: (changed) => {
+            gitignoreChanged = changed;
+        },
     });
     const statePath = localSpaceStatePath(root);
     const linkRelativePath = path.join(LOCAL_SPACE_STATE_DIR_NAME, LOCAL_SPACE_LINK_FILE_NAME);
@@ -506,7 +496,12 @@ export async function saveLocalSpaceState(root, input) {
                 throw new LocalSpaceStateConflictError(`The committed checkout link selects ${inheritedLink.space}, not ${input.spaceId}.`);
             }
             if (inheritedLink) {
-                return { statePath, linkPath: localSpaceLinkPath(root), wroteLink };
+                return {
+                    statePath,
+                    linkPath: localSpaceLinkPath(root),
+                    wroteLink,
+                    gitignore: { path: path.join(root, ".gitignore"), changed: gitignoreChanged },
+                };
             }
         }
         try {
@@ -530,5 +525,10 @@ export async function saveLocalSpaceState(root, input) {
     else if (primaryLink.space !== input.spaceId) {
         throw new LocalSpaceStateConflictError(`The committed checkout link selects ${primaryLink.space}, not ${input.spaceId}.`);
     }
-    return { statePath, linkPath: localSpaceLinkPath(root), wroteLink };
+    return {
+        statePath,
+        linkPath: localSpaceLinkPath(root),
+        wroteLink,
+        gitignore: { path: path.join(root, ".gitignore"), changed: gitignoreChanged },
+    };
 }

package/dist/utils/oauth-signed-query.d.ts

@@ -1,8 +1,6 @@
 /**
- * The signed OAuth authorize continuation carried by a query string, or null
- * when there isn't one. Better Auth's signature covers every param it sent
- * (the set is self-declared in `ba_param`) — anything extra that later joined
- * the URL (a returnTo, a tracking param) must be dropped before the query is
- * sent back, or verification fails.
+ * The signed authorize continuation in `query`, or null when there isn't one.
+ * The signature covers only the params `ba_param` names, so anything that
+ * joined the URL later must be dropped or verification fails.
  */
 export declare function signedOAuthQuerySubset(query: string): string | null;

package/dist/utils/oauth-signed-query.js

@@ -1,13 +1,10 @@
-// Better Auth's OAuth authorize endpoint hands interaction prompts (login,
-// consent) to the dashboard by redirecting with the ENTIRE authorize query,
-// HMAC-signed by the auth server (`sig` + `exp` + `ba_*` bookkeeping params).
-// Verification hashes the query verbatim, so it must round-trip byte-exact.
+// Better Auth redirects interaction prompts to the dashboard with the entire
+// authorize query, HMAC-signed. Verification hashes it verbatim, so the query
+// must round-trip byte-exact.
 /**
- * The signed OAuth authorize continuation carried by a query string, or null
- * when there isn't one. Better Auth's signature covers every param it sent
- * (the set is self-declared in `ba_param`) — anything extra that later joined
- * the URL (a returnTo, a tracking param) must be dropped before the query is
- * sent back, or verification fails.
+ * The signed authorize continuation in `query`, or null when there isn't one.
+ * The signature covers only the params `ba_param` names, so anything that
+ * joined the URL later must be dropped or verification fails.
  */
 export function signedOAuthQuerySubset(query) {
     const params = new URLSearchParams(query);

package/dist/utils/one-shot-replay.d.ts

@@ -3,12 +3,13 @@ export type OneShotReplayIdentity = {
     principal: string;
 };
 /**
- * Creates an unguessable capability for replaying one shown-once response.
- *
- * Neither value is derived from the credential consumed by the mutation. A
- * caller holding only that old credential therefore cannot locate the stored
- * response after the credential is revoked.
+ * An unguessable capability for replaying one shown-once response. Neither
+ * value derives from the credential the mutation consumes, so a caller holding
+ * only that revoked credential cannot locate the stored response.
  */
 export declare function createOneShotReplayIdentity(prefix: string): OneShotReplayIdentity;
 /** Production headers for one one-shot attempt (or one device-poll sequence). */
-export declare function oneShotReplayHeaders(identity: OneShotReplayIdentity, sequence?: number): Record<"idempotency-key" | "x-spacefast-idempotency-principal", string>;
+export declare function oneShotReplayHeaders(identity: OneShotReplayIdentity, sequence?: number): {
+    "idempotency-key": string;
+    "x-spacefast-idempotency-principal": string;
+};

package/dist/utils/one-shot-replay.js

@@ -1,10 +1,8 @@
 import { randomBytes } from "node:crypto";
 /**
- * Creates an unguessable capability for replaying one shown-once response.
- *
- * Neither value is derived from the credential consumed by the mutation. A
- * caller holding only that old credential therefore cannot locate the stored
- * response after the credential is revoked.
+ * An unguessable capability for replaying one shown-once response. Neither
+ * value derives from the credential the mutation consumes, so a caller holding
+ * only that revoked credential cannot locate the stored response.
  */
 export function createOneShotReplayIdentity(prefix) {
     return {

package/dist/utils/page-colors.d.ts

@@ -1,17 +1,17 @@
 import type { SpacePageTheme } from "../contracts/space-config.js";
-/** Default page palette (mirrored into the shared template CSS). */
+/** Default page palette, mirrored into the shared template CSS. */
 export declare const PAGE_COLOR_DEFAULTS: {
-    readonly accent: "#ff4217";
-    readonly bg: "#f9f8f4";
-    readonly fg: "#1a1913";
-    readonly muted: "#6f6b62";
-    readonly card: "#f9f8f4";
-    readonly border: "#ddd9cf";
-    readonly darkBg: "#141313";
-    readonly darkFg: "#e9e7e2";
-    readonly darkMuted: "#8f8b84";
-    readonly darkCard: "#141313";
-    readonly darkBorder: "#2b2a27";
+    readonly accent: "#d8f24b";
+    readonly bg: "#f7f5ef";
+    readonly fg: "#0c0c0c";
+    readonly muted: "#6e6a5e";
+    readonly card: "#f7f5ef";
+    readonly border: "#e5e1d4";
+    readonly darkBg: "#0c0c0c";
+    readonly darkFg: "#f0eee6";
+    readonly darkMuted: "#a6a193";
+    readonly darkCard: "#0c0c0c";
+    readonly darkBorder: "#2b2823";
 };
 export type PageSchemeColors = {
     bg: string;
@@ -26,7 +26,6 @@ export type DerivedPageColors = {
     scheme: "adaptive" | "light" | "dark";
     /** The accent exactly as pushed (fills keep the brand color verbatim). */
     accent: string;
-    /** Label color on accent fills. */
     onAccent: string;
     /** Accent-derived link color, readable on the light (or pinned) surface. */
     link: string;
@@ -36,15 +35,12 @@ export type DerivedPageColors = {
     pinned?: PageSchemeColors;
 };
 /**
- * Return `color` unchanged when it already meets `target` on `surface`;
- * otherwise move its OKLCH lightness (hue/chroma preserved) just far enough
- * to meet it. Falls back to plain black/white when even full lightness range
- * cannot reach the target (e.g. a mid-gray surface).
+ * Moves `color`'s OKLCH lightness (hue and chroma preserved) just far enough
+ * to meet `target` on `surface`. Falls back to black or white when the full
+ * lightness range cannot reach it, as on a mid-gray surface.
  */
 export declare function readableOn(color: string, surface: string, target: number): string;
-/** Button-label color for an accent fill: white when it can carry, else ink. */
 export declare function onAccentColor(accent: string): string;
-/** The one entry point: raw theme in, everything the templates paint with out. */
 export declare function derivePageColors(theme: Pick<SpacePageTheme, "accent" | "background">): DerivedPageColors;
 /** Hex form of any schema-accepted color, for color-picker inputs. */
 export declare function pageColorToHex(value: string): string | null;