@gmickel/gno 1.22.0 → 1.24.0

package/src/core/setup-receipt.ts

@@ -0,0 +1,321 @@
+/**
+ * Canonical, privacy-bounded receipts for resumable folder setup.
+ *
+ * @module src/core/setup-receipt
+ */
+
+// node:fs/promises provides private file creation, directory permissions, and atomic rename APIs that Bun does not expose.
+import { chmod, mkdir, open, rename, unlink } from "node:fs/promises";
+// node:path has no Bun equivalent.
+import { dirname, join } from "node:path";
+
+import type { ActivationVerificationReceipt } from "../store/types";
+
+import { canonicalizeIndexName } from "../app/index-name";
+
+export const SETUP_RECEIPT_SCHEMA_VERSION = "1.0" as const;
+
+export const SETUP_STAGE_NAMES = [
+  "preflight",
+  "config_saved",
+  "store_synced",
+  "lexical_indexed",
+  "lexical_proved",
+  "completed",
+] as const;
+
+export type SetupStageName = (typeof SETUP_STAGE_NAMES)[number];
+export type SetupStageStatus = "pending" | "in_progress" | "passed" | "failed";
+
+export interface SetupStageReceipt {
+  status: SetupStageStatus;
+  token: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  code: string | null;
+  remediation: string | null;
+}
+
+export interface SetupFailure {
+  stage: SetupStageName;
+  code: string;
+  message: string;
+  remediation: string;
+}
+
+export interface FolderSetupReceipt {
+  schemaVersion: typeof SETUP_RECEIPT_SCHEMA_VERSION;
+  status: "in_progress" | "failed" | "completed";
+  generatedAt: string;
+  input: {
+    folder: string;
+    folderFingerprint: string;
+    indexName: string;
+    requestedName: string | null;
+    excludes: string[];
+    secretRiskAuthorized: boolean;
+  };
+  fingerprints: {
+    input: string;
+    config: string | null;
+    index: string | null;
+  };
+  collection: {
+    name: string | null;
+    path: string;
+    disposition: "pending" | "created" | "reused";
+  };
+  paths: {
+    config: string;
+    receipt: string;
+  };
+  stages: Record<SetupStageName, SetupStageReceipt>;
+  pending: string[];
+  failure: SetupFailure | null;
+  activation: ActivationVerificationReceipt | null;
+}
+
+type CanonicalJson =
+  | boolean
+  | null
+  | number
+  | string
+  | CanonicalJson[]
+  | { [key: string]: CanonicalJson };
+
+function canonicalize(value: unknown): CanonicalJson {
+  if (
+    value === null ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string"
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+  if (typeof value === "object") {
+    const output: Record<string, CanonicalJson> = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = (value as Record<string, unknown>)[key];
+      if (item !== undefined) {
+        output[key] = canonicalize(item);
+      }
+    }
+    return output;
+  }
+  throw new TypeError(`Unsupported canonical JSON value: ${typeof value}`);
+}
+
+export function serializeSetupReceipt(receipt: FolderSetupReceipt): string {
+  return `${JSON.stringify(canonicalize(receipt), null, 2)}\n`;
+}
+
+export function setupFingerprint(value: unknown): string {
+  return new Bun.CryptoHasher("sha256")
+    .update(JSON.stringify(canonicalize(value)))
+    .digest("hex");
+}
+
+export function setupRootFingerprint(folderRealpath: string): string {
+  return new Bun.CryptoHasher("sha256").update(folderRealpath).digest("hex");
+}
+
+export function getSetupReceiptPath(input: {
+  dataDir: string;
+  indexName: string;
+  folderRealpath: string;
+}): string {
+  const indexIdentity = canonicalizeIndexName(input.indexName);
+  const rootFingerprint = setupRootFingerprint(input.folderRealpath);
+  return join(
+    input.dataDir,
+    "setup-receipts",
+    indexIdentity,
+    `${rootFingerprint}.json`
+  );
+}
+
+export function createSetupReceipt(input: {
+  now: string;
+  folder: string;
+  indexName: string;
+  requestedName?: string;
+  excludes: string[];
+  secretRiskAuthorized: boolean;
+  configPath: string;
+  dataDir: string;
+}): FolderSetupReceipt {
+  const indexName = canonicalizeIndexName(input.indexName);
+  const folderFingerprint = setupRootFingerprint(input.folder);
+  const receiptPath = getSetupReceiptPath({
+    dataDir: input.dataDir,
+    indexName,
+    folderRealpath: input.folder,
+  });
+  const stages = Object.fromEntries(
+    SETUP_STAGE_NAMES.map((stage) => [
+      stage,
+      {
+        status: "pending",
+        token: null,
+        startedAt: null,
+        completedAt: null,
+        code: null,
+        remediation: null,
+      },
+    ])
+  ) as Record<SetupStageName, SetupStageReceipt>;
+  const requestedName = input.requestedName?.trim().toLowerCase() || null;
+
+  return {
+    schemaVersion: SETUP_RECEIPT_SCHEMA_VERSION,
+    status: "in_progress",
+    generatedAt: input.now,
+    input: {
+      folder: input.folder,
+      folderFingerprint,
+      indexName,
+      requestedName,
+      excludes: [...new Set(input.excludes)].sort(),
+      secretRiskAuthorized: input.secretRiskAuthorized,
+    },
+    fingerprints: {
+      input: setupFingerprint({
+        folder: input.folder,
+        indexName,
+        requestedName,
+        excludes: [...new Set(input.excludes)].sort(),
+        secretRiskAuthorized: input.secretRiskAuthorized,
+      }),
+      config: null,
+      index: null,
+    },
+    collection: {
+      name: null,
+      path: input.folder,
+      disposition: "pending",
+    },
+    paths: {
+      config: input.configPath,
+      receipt: receiptPath,
+    },
+    stages,
+    pending: [],
+    failure: null,
+    activation: null,
+  };
+}
+
+export function startSetupStage(
+  receipt: FolderSetupReceipt,
+  stage: SetupStageName,
+  now: string
+): void {
+  receipt.status = "in_progress";
+  receipt.generatedAt = now;
+  receipt.failure = null;
+  receipt.stages[stage] = {
+    status: "in_progress",
+    token: setupFingerprint({
+      receipt: receipt.input.folderFingerprint,
+      stage,
+      startedAt: now,
+    }),
+    startedAt: now,
+    completedAt: null,
+    code: null,
+    remediation: null,
+  };
+}
+
+export function passSetupStage(
+  receipt: FolderSetupReceipt,
+  stage: SetupStageName,
+  now: string
+): void {
+  receipt.generatedAt = now;
+  receipt.stages[stage] = {
+    ...receipt.stages[stage],
+    status: "passed",
+    completedAt: now,
+    code: null,
+    remediation: null,
+  };
+}
+
+export function failSetupStage(
+  receipt: FolderSetupReceipt,
+  failure: SetupFailure,
+  now: string
+): void {
+  const current = receipt.stages[failure.stage];
+  receipt.status = "failed";
+  receipt.generatedAt = now;
+  receipt.failure = failure;
+  if (current.status !== "passed") {
+    receipt.stages[failure.stage] = {
+      ...current,
+      status: "failed",
+      token:
+        current.token ??
+        setupFingerprint({
+          receipt: receipt.input.folderFingerprint,
+          stage: failure.stage,
+          startedAt: now,
+        }),
+      startedAt: current.startedAt ?? now,
+      completedAt: now,
+      code: failure.code,
+      remediation: failure.remediation,
+    };
+  }
+}
+
+export async function persistSetupReceipt(
+  receipt: FolderSetupReceipt
+): Promise<void> {
+  const receiptDir = dirname(receipt.paths.receipt);
+  await mkdir(receiptDir, { recursive: true, mode: 0o700 });
+  await chmod(receiptDir, 0o700);
+
+  const tempPath = `${receipt.paths.receipt}.tmp.${crypto.randomUUID()}`;
+  let tempFile: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    tempFile = await open(tempPath, "wx", 0o600);
+    await tempFile.writeFile(serializeSetupReceipt(receipt), "utf8");
+    await tempFile.sync();
+    await tempFile.close();
+    tempFile = null;
+    await rename(tempPath, receipt.paths.receipt);
+    await chmod(receipt.paths.receipt, 0o600);
+  } catch (error) {
+    await tempFile?.close().catch(() => {
+      /* best-effort temporary receipt handle cleanup */
+    });
+    await unlink(tempPath).catch(() => {
+      /* best-effort temporary receipt cleanup */
+    });
+    throw error;
+  }
+}
+
+export async function loadSetupReceipt(
+  path: string
+): Promise<FolderSetupReceipt | null> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return null;
+  }
+  const value: unknown = await file.json();
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("schemaVersion" in value) ||
+    value.schemaVersion !== SETUP_RECEIPT_SCHEMA_VERSION
+  ) {
+    return null;
+  }
+  return value as FolderSetupReceipt;
+}

package/src/core/validation.ts

@@ -9,7 +9,7 @@ import { realpath } from "node:fs/promises";
 // node:os for homedir (no Bun os utils)
 import { homedir } from "node:os";
 // node:path for path utils (no Bun path utils)
-import { isAbsolute, join, posix as pathPosix } from "node:path";
+import { isAbsolute, join, posix as pathPosix, relative, sep } from "node:path";
 
 import { toAbsolutePath } from "../config/paths";
 
@@ -58,6 +58,25 @@ export function validateRelPath(relPath: string): string {
   return normalized;
 }
 
+/**
+ * Return whether candidate is equal to or nested beneath parent.
+ *
+ * Inputs must already be canonical absolute paths. `relative()` keeps this
+ * segment-safe, unlike string-prefix checks (`/project` vs `/project-old`).
+ */
+export function isCanonicalPathContained(
+  parent: string,
+  candidate: string
+): boolean {
+  const relativePath = relative(parent, candidate);
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath))
+  );
+}
+
 export async function validateCollectionRoot(
   inputPath: string
 ): Promise<string> {

package/src/mcp/tools/ask.ts

@@ -8,6 +8,7 @@ import type { ToolContext } from "../server";
 import type { ToolResult } from "./index";
 
 import { buildVerifiedAsk } from "../../app/verified-ask";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -30,6 +31,7 @@ const queryModeSchema = z
 export const askInputSchema = z
   .object({
     query: z.string().trim().min(1),
+    projectHints: z.array(z.string()).max(16).optional(),
     verify: z.literal(true),
     collection: z.string().optional(),
     limit: z.number().int().min(1).max(100).default(5),
@@ -153,8 +155,14 @@ export const handleAsk = (
       );
       if (!normalized.ok) throw new Error(normalized.error.message);
       const query = normalized.value.query;
+      const { projectHints, ...askInput } = args;
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        context.config,
+        projectHints
+      );
       const options = {
-        ...args,
+        ...askInput,
+        projectAffinity,
         queryModes:
           normalized.value.queryModes.length > 0
             ? normalized.value.queryModes
@@ -210,6 +218,7 @@ export const handleAsk = (
           embedPort: modelPorts.embedPort,
           rerankPort: modelPorts.rerankPort,
           genPort: modelPorts.genPort,
+          projectAffinity,
           traceSession,
         });
         const finished = await traceSession?.finish(

package/src/mcp/tools/context.ts

@@ -25,6 +25,11 @@ import {
   parseContextVerifySurfaceInput,
 } from "../../app/context-surface";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { ContextCapsuleContractError } from "../../core/context-capsule";
+import {
+  ProjectAffinityInputError,
+  resolveRemoteProjectAffinity,
+} from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   startRetrievalTraceRequest,
@@ -224,6 +229,18 @@ export const handleContext = (
       null;
     let traceSession: RetrievalTraceSession | undefined;
     try {
+      let projectAffinity;
+      try {
+        projectAffinity = await resolveRemoteProjectAffinity(
+          context.config,
+          parsed.projectHints
+        );
+      } catch (error) {
+        if (error instanceof ProjectAffinityInputError) {
+          throw new ContextCapsuleContractError("invalid_input", error.message);
+        }
+        throw error;
+      }
       const traceStart = await startRetrievalTraceRequest({
         store: context.store,
         config: context.config,
@@ -261,6 +278,7 @@ export const handleContext = (
         vectorIndex: modelPorts?.vectorIndex ?? null,
         embedPort: modelPorts?.embedPort ?? null,
         rerankPort: modelPorts?.rerankPort ?? null,
+        projectAffinity,
         traceSession,
       });
       const finalized = await traceSession?.finish("completed");

package/src/mcp/tools/index.ts

@@ -131,13 +131,22 @@ export const MCP_WRITE_TOOL_NAMES = new Set([
 // Shared Input Schemas
 // ─────────────────────────────────────────────────────────────────────────────
 
-const searchInputSchema = z.object({
+const projectHintsInputSchema = z
+  .array(z.string())
+  .max(16)
+  .optional()
+  .describe(
+    "Opaque caller project hints for cross-surface parity; remote hints never inspect server paths"
+  );
+
+export const searchInputSchema = z.object({
   query: z
     .string()
     .min(1, "Query cannot be empty")
     .describe(
       "Exact keyword, identifier, filename, error text, or phrase to match with BM25"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()
@@ -378,13 +387,14 @@ const duplicateNoteInputSchema = z.object({
   name: z.string().optional(),
 });
 
-const vsearchInputSchema = z.object({
+export const vsearchInputSchema = z.object({
   query: z
     .string()
     .min(1, "Query cannot be empty")
     .describe(
       "Natural-language concept to match semantically; use gno_search for exact error text or identifiers"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()
@@ -455,6 +465,7 @@ export const queryInputSchema = z.object({
     .describe(
       "Primary user query; combine with intent or queryModes for ambiguous requests"
     ),
+  projectHints: projectHintsInputSchema,
   collection: z
     .string()
     .optional()

package/src/mcp/tools/query.ts

@@ -26,6 +26,7 @@ import {
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -49,6 +50,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface QueryInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -227,6 +229,10 @@ export function handleQuery(
         hasStructuredModes,
       });
       const { noExpand, noRerank } = depthPolicy;
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const expandUri =
         !noExpand && !hasStructuredModes
           ? resolveModelUri(ctx.config, "expand", undefined, args.collection)
@@ -253,6 +259,7 @@ export function handleQuery(
         queryModes,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
 
       try {
@@ -440,6 +447,10 @@ export function handleQueryDiagnose(
           hasStructuredModes,
         });
         const { noExpand, noRerank } = depthPolicy;
+        const projectAffinity = await resolveRemoteProjectAffinity(
+          ctx.config,
+          args.projectHints
+        );
 
         if (!args.fast) {
           const embedResult = await llm.createEmbeddingPort(embedUri, {
@@ -524,6 +535,7 @@ export function handleQueryDiagnose(
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),
           tagsAny: normalizeTagFilters(args.tagsAny),
+          projectAffinity,
           contentTypeRules,
           contentTypeRulesFingerprint:
             fingerprintContentTypeRules(contentTypeRules),

package/src/mcp/tools/search.ts

@@ -11,6 +11,7 @@ import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -22,6 +23,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface SearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -113,6 +115,10 @@ export function handleSearch(
         }
       }
 
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -126,6 +132,7 @@ export function handleSearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       try {

package/src/mcp/tools/vsearch.ts

@@ -12,6 +12,7 @@ import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
+import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -34,6 +35,7 @@ import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
 interface VsearchInput {
   query: string;
+  projectHints?: string[];
   collection?: string;
   limit?: number;
   minScore?: number;
@@ -135,6 +137,10 @@ export function handleVsearch(
         undefined,
         args.collection
       );
+      const projectAffinity = await resolveRemoteProjectAffinity(
+        ctx.config,
+        args.projectHints
+      );
       const options = {
         limit: args.limit ?? 5,
         minScore: args.minScore,
@@ -147,6 +153,7 @@ export function handleVsearch(
         author: args.author,
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
+        projectAffinity,
       };
       let traceSession: RetrievalTraceSession | undefined;
       const traceStart = await startRetrievalTraceRequest({

package/src/pipeline/diagnose.ts

@@ -19,6 +19,12 @@ import { resolveDocRef } from "../core/ref-parser";
 import { err, ok } from "../store/types";
 import { evaluateQueryTargetFilters } from "./filters";
 import { searchHybrid } from "./hybrid";
+import {
+  getProjectAffinityMetadata,
+  type ProjectAffinityScoringInput,
+  type ProjectAffinityScoreMetadata,
+  scoreProjectAffinity,
+} from "./project-affinity";
 
 export type QueryDiagnoseTargetStatus =
   | "not_found"
@@ -46,7 +52,7 @@ export interface QueryDiagnoseStage {
 }
 
 export interface QueryDiagnoseResult {
-  schemaVersion: "1.0";
+  schemaVersion: "1.0" | "1.1";
   query: string;
   target: {
     ref: string;
@@ -65,6 +71,7 @@ export interface QueryDiagnoseResult {
     filterReasons: string[];
   };
   stages: QueryDiagnoseStage[];
+  affinity?: ProjectAffinityScoreMetadata;
   chunk: {
     seq: number | null;
     startLine: number | null;
@@ -155,6 +162,15 @@ function findTargetCandidate(
   );
 }
 
+const hasTrustedProjectAffinityInput = (
+  input: ProjectAffinityScoringInput | undefined
+): boolean =>
+  input?.enabled !== false &&
+  Boolean(
+    input?.resolution.matches.length ||
+    input?.resolution.roots.some((root) => root.source !== "remote_hint")
+  );
+
 export async function diagnoseQueryTarget(
   deps: HybridSearchDeps,
   query: string,
@@ -276,8 +292,28 @@ export async function diagnoseQueryTarget(
     chunks.find((chunk) => chunk.seq === firstMatched?.seq) ??
     chunks[0] ??
     null;
+  const targetResult = searchResult.value.results.find(
+    (result) => result.uri === doc.uri
+  );
+  const lastMatched = trace?.stages
+    .toReversed()
+    .flatMap((stage) => stage.candidates)
+    .find(
+      (candidate) =>
+        candidate.mirrorHash === doc.mirrorHash && targetSeqs.has(candidate.seq)
+    );
+  const affinity =
+    (targetResult ? getProjectAffinityMetadata(targetResult) : undefined) ??
+    (lastMatched && options.projectAffinity
+      ? scoreProjectAffinity(
+          lastMatched.score,
+          doc.collection,
+          options.projectAffinity,
+          { kind: "hybrid_blended", score: lastMatched.score }
+        )
+      : null);
 
-  return ok({
+  const baseResult: QueryDiagnoseResult = {
     ...buildBaseResult(query, options.target, "diagnosed", doc, {
       graphHints,
       chunkCount: chunks.length,
@@ -298,5 +334,14 @@ export async function diagnoseQueryTarget(
       totalResults: searchResult.value.meta.totalResults,
       queryModes: searchResult.value.meta.queryModes,
     },
-  });
+  };
+  return ok(
+    affinity && hasTrustedProjectAffinityInput(options.projectAffinity)
+      ? {
+          ...baseResult,
+          schemaVersion: "1.1",
+          affinity,
+        }
+      : baseResult
+  );
 }