@gmickel/gno 1.22.0 → 1.24.0

package/src/cli/program.ts

@@ -32,7 +32,9 @@ import { CliError } from "./errors";
 import {
   assertFormatSupported,
   CMD,
+  collectRepeatableValue,
   getDefaultLimit,
+  parseCliProjectAffinityOptions,
   parseOptionalFloat,
   parsePositiveInt,
 } from "./options";
@@ -594,6 +596,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--json", "JSON output")
@@ -641,6 +650,7 @@ function wireSearchCommands(program: Command): void {
           : getDefaultLimit(format);
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const { search, formatSearch } = await import("./commands/search");
       const result = await search(queryText, {
@@ -658,6 +668,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         json: format === "json",
@@ -714,6 +725,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--json", "JSON output")
@@ -759,6 +777,7 @@ function wireSearchCommands(program: Command): void {
         : getDefaultLimit(format);
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const { vsearch, formatVsearch } = await import("./commands/vsearch");
       const result = await vsearch(queryText, {
@@ -776,6 +795,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         json: format === "json",
@@ -827,6 +847,13 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
     .option("--fast", "skip expansion and reranking (fastest, ~0.7s)")
@@ -931,6 +958,7 @@ function wireSearchCommands(program: Command): void {
         : undefined;
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       const depthPolicy = resolveDepthPolicy({
         presetId: activePresetId,
@@ -960,6 +988,7 @@ function wireSearchCommands(program: Command): void {
           exclude,
           tagsAll,
           tagsAny,
+          ...projectAffinity,
           noExpand: depthPolicy.noExpand,
           noRerank: depthPolicy.noRerank,
           graph: Boolean(cmdOpts.graph),
@@ -995,6 +1024,7 @@ function wireSearchCommands(program: Command): void {
         exclude,
         tagsAll,
         tagsAny,
+        ...projectAffinity,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         noExpand: depthPolicy.noExpand,
@@ -1121,6 +1151,13 @@ function wireSearchCommands(program: Command): void {
     .option("--context-budget-bytes <num>", "verified Context byte budget")
     .option("--min-score <score>", "minimum retrieval score (0-1)")
     .option("--graph", "include bounded graph expansion")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--show-sources", "show all retrieved sources (not just cited)")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -1169,6 +1206,7 @@ function wireSearchCommands(program: Command): void {
       }
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
 
       let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
       if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
@@ -1229,6 +1267,7 @@ function wireSearchCommands(program: Command): void {
         maxAnswerTokens,
         contextBudgetTokens,
         contextBudgetBytes,
+        ...projectAffinity,
         showSources,
         json: format === "json",
         md: format === "md",
@@ -1307,6 +1346,69 @@ function wireOnboardingCommands(program: Command): void {
       }
     );
 
+  // setup - Verify a folder is lexically retrievable, then hand off semantics
+  program
+    .command("setup <folder>")
+    .description("Add and verify a folder with a real lexical retrieval")
+    .option("-n, --name <name>", "collection name")
+    .option(
+      "--exclude <pattern>",
+      "literal exclusion pattern (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option(
+      "--authorize-secret-risk",
+      "explicitly authorize indexing likely secret files"
+    )
+    .option(
+      "--connector <id>",
+      "install and verify one connector (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-semantic", "skip background semantic indexing")
+    .option("--json", "JSON output")
+    .action(async (folder: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const json = Boolean(cmdOpts.json) || globals.json;
+      const { formatSetupOutputResult, setupWithActivation } =
+        await import("./commands/setup-activation");
+      const exclusions = cmdOpts.exclude as string[];
+      const outcome = await setupWithActivation({
+        folder,
+        name: cmdOpts.name as string | undefined,
+        exclude: exclusions.length > 0 ? exclusions : undefined,
+        authorizeSecretRisk: Boolean(cmdOpts.authorizeSecretRisk),
+        connectorIds: cmdOpts.connector as string[],
+        semantic: cmdOpts.semantic !== false,
+        indexName: globals.index,
+        configPath: globals.config,
+        offline: globals.offline,
+        yes: globals.yes,
+        json,
+        quiet: globals.quiet,
+        progress: (stage) => {
+          process.stderr.write(`setup: ${stage}\n`);
+        },
+      });
+      const output = formatSetupOutputResult(outcome.result, { json });
+      if (json || outcome.exitCode === 0) {
+        process.stdout.write(`${output}\n`);
+      } else {
+        process.stderr.write(`${output}\n`);
+      }
+      if (outcome.exitCode !== 0) {
+        const setupResult =
+          "setup" in outcome.result ? outcome.result.setup : outcome.result;
+        throw new CliError(
+          outcome.exitCode === 1 ? "VALIDATION" : "RUNTIME",
+          setupResult.lexical.error?.message ?? "Setup failed",
+          { silent: true }
+        );
+      }
+    });
+
   // index - Index collections
   program
     .command("index [collection]")
@@ -1974,6 +2076,13 @@ function wireManagementCommands(program: Command): void {
     .option("--since <date>", "modified-at lower bound")
     .option("--until <date>", "modified-at upper bound")
     .option("--graph", "enable graph neighbor expansion")
+    .option(
+      "--project-root <path>",
+      "trusted project root (repeatable; replaces cwd affinity)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--no-project-affinity", "disable project-aware ranking")
     .option("--fast", "use lexical-first fast retrieval")
     .option("--thorough", "use a wider retrieval pool")
     .option("-n, --limit <num>", "maximum retrieved results")
@@ -1991,6 +2100,7 @@ function wireManagementCommands(program: Command): void {
         throw new CliError("VALIDATION", "Choose either --fast or --thorough");
       }
       const globals = getGlobals();
+      const projectAffinity = parseCliProjectAffinityOptions(cmdOpts);
       const { contextBuild } = await import("./commands/context-build");
       let queryModes: import("../pipeline/types").QueryModeInput[] | undefined;
       if (Array.isArray(cmdOpts.queryMode) && cmdOpts.queryMode.length > 0) {
@@ -2022,6 +2132,7 @@ function wireManagementCommands(program: Command): void {
           true
         ),
         query: cmdOpts.query as string | undefined,
+        ...projectAffinity,
         queryModes,
         collections: cmdOpts.collection as string[],
         uriPrefix: cmdOpts.uriPrefix as string | undefined,
@@ -2350,6 +2461,7 @@ function wireManagementCommands(program: Command): void {
           yes: globals.yes,
           json: format === "json",
           verbose: globals.verbose,
+          offline: globals.offline,
         };
         const result = await embed(opts);
 

package/src/cli/setup-semantic-worker.ts

@@ -0,0 +1,177 @@
+/**
+ * One-shot semantic worker started by `gno setup`.
+ *
+ * It owns its store/model lifecycle through the existing collection-scoped
+ * embed command, updates one durable receipt, and exits.
+ *
+ * @module src/cli/setup-semantic-worker
+ */
+
+import { loadSetupReceipt } from "../core/setup-receipt";
+import { embed, type EmbedOptions, type EmbedResult } from "./commands/embed";
+import {
+  loadSetupSemanticReceipt,
+  type SetupSemanticReceipt,
+  setupSemanticSourceFingerprint,
+  updateSetupSemanticReceipt,
+} from "./commands/setup-semantic";
+
+const PARENT_REGISTRATION_TIMEOUT_MS = 2000;
+const PARENT_REGISTRATION_POLL_MS = 20;
+const MAX_ERROR_LENGTH = 500;
+
+export interface SetupSemanticWorkerDependencies {
+  embedFn?: (options: EmbedOptions) => Promise<EmbedResult>;
+  now?: () => Date;
+}
+
+function boundedError(error: unknown): string {
+  return (
+    (error instanceof Error ? error.message : String(error)).slice(
+      0,
+      MAX_ERROR_LENGTH
+    ) || "Unknown semantic setup error"
+  );
+}
+
+async function waitForParentRegistration(
+  receiptPath: string,
+  jobId: string
+): Promise<SetupSemanticReceipt> {
+  const deadline = Date.now() + PARENT_REGISTRATION_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const receipt = await loadSetupSemanticReceipt(receiptPath);
+    if (
+      receipt?.jobId === jobId &&
+      (receipt.pid === process.pid ||
+        receipt.status === "pending" ||
+        receipt.status === "skipped")
+    ) {
+      return receipt;
+    }
+    await Bun.sleep(PARENT_REGISTRATION_POLL_MS);
+  }
+  throw new Error("Setup parent did not register the semantic worker");
+}
+
+export async function runSetupSemanticWorker(
+  receiptPath: string,
+  jobId: string,
+  dependencies: SetupSemanticWorkerDependencies = {}
+): Promise<number> {
+  try {
+    const registered = await waitForParentRegistration(receiptPath, jobId);
+    if (registered.status === "pending") {
+      return 2;
+    }
+    if (registered.status === "skipped") {
+      return 0;
+    }
+
+    const setupReceipt = await loadSetupReceipt(registered.setupReceiptPath);
+    if (
+      !setupReceipt ||
+      setupReceipt.status !== "completed" ||
+      setupReceipt.collection.name !== registered.collection ||
+      setupReceipt.input.indexName !== registered.indexName ||
+      setupReceipt.paths.receipt !== registered.setupReceiptPath ||
+      setupSemanticSourceFingerprint(setupReceipt) !==
+        registered.setupReceiptFingerprint
+    ) {
+      throw new Error("Lexical setup receipt no longer matches semantic job");
+    }
+
+    const startedAt = (dependencies.now ?? (() => new Date()))().toISOString();
+    await updateSetupSemanticReceipt(receiptPath, jobId, (current) => ({
+      ...current,
+      status: "running",
+      generatedAt: startedAt,
+      startedAt: current.startedAt ?? startedAt,
+      completedAt: null,
+      pid: process.pid,
+      counts: null,
+      error: null,
+    }));
+
+    const result = await (dependencies.embedFn ?? embed)({
+      configPath: setupReceipt.paths.config,
+      indexName: registered.indexName,
+      collection: registered.collection,
+      yes: true,
+      json: true,
+      offline: registered.offline,
+    });
+    if (!result.success) {
+      throw new Error(result.error);
+    }
+    if (result.errors > 0 || result.syncError) {
+      const completedAt = (
+        dependencies.now ?? (() => new Date())
+      )().toISOString();
+      const message = result.syncError
+        ? `Vector index sync failed: ${result.syncError}`
+        : `Embedding completed with ${result.errors} failed chunk${result.errors === 1 ? "" : "s"}`;
+      await updateSetupSemanticReceipt(receiptPath, jobId, (current) => ({
+        ...current,
+        status: "failed",
+        generatedAt: completedAt,
+        completedAt,
+        pid: null,
+        counts: {
+          embedded: result.embedded,
+          errors: result.errors,
+        },
+        error: {
+          message: boundedError(message),
+          remediation: `Run: ${current.resumeCommand}`,
+        },
+      }));
+      return 2;
+    }
+
+    const completedAt = (
+      dependencies.now ?? (() => new Date())
+    )().toISOString();
+    await updateSetupSemanticReceipt(receiptPath, jobId, (current) => ({
+      ...current,
+      status: "completed",
+      generatedAt: completedAt,
+      completedAt,
+      pid: null,
+      counts: {
+        embedded: result.embedded,
+        errors: result.errors,
+      },
+      error: null,
+    }));
+    return 0;
+  } catch (error) {
+    const completedAt = (
+      dependencies.now ?? (() => new Date())
+    )().toISOString();
+    await updateSetupSemanticReceipt(receiptPath, jobId, (current) => ({
+      ...current,
+      status: "failed",
+      generatedAt: completedAt,
+      startedAt: current.startedAt ?? completedAt,
+      completedAt,
+      pid: null,
+      counts: null,
+      error: {
+        message: boundedError(error),
+        remediation: `Run: ${current.resumeCommand}`,
+      },
+    })).catch(() => undefined);
+    return 2;
+  }
+}
+
+if (import.meta.main) {
+  const receiptPath = process.argv[2];
+  const jobId = process.argv[3];
+  if (!(receiptPath && jobId)) {
+    process.exitCode = 1;
+  } else {
+    process.exitCode = await runSetupSemanticWorker(receiptPath, jobId);
+  }
+}

package/src/config/defaults.ts

@@ -4,7 +4,12 @@
  * @module src/config/defaults
  */
 
-import { CONFIG_VERSION, type Config, DEFAULT_FTS_TOKENIZER } from "./types";
+import {
+  CONFIG_VERSION,
+  type Config,
+  DEFAULT_FTS_TOKENIZER,
+  PROJECT_AFFINITY_MAX_CONTRIBUTION,
+} from "./types";
 
 /**
  * Create a default config object.
@@ -17,5 +22,9 @@ export function createDefaultConfig(): Config {
     collections: [],
     contexts: [],
     contentTypes: [],
+    projectAffinity: {
+      enabled: true,
+      contribution: PROJECT_AFFINITY_MAX_CONTRIBUTION,
+    },
   };
 }

package/src/config/types.ts

@@ -115,6 +115,74 @@ export const CollectionSchema = z.object({
 export type Collection = z.infer<typeof CollectionSchema>;
 export type CollectionModelOverrides = NonNullable<Collection["models"]>;
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Project Affinity Input
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const TrustedProjectRootSourceSchema = z.enum([
+  "cli_cwd",
+  "cli_explicit",
+  "cli_worktree",
+]);
+export type TrustedProjectRootSource = z.infer<
+  typeof TrustedProjectRootSourceSchema
+>;
+
+export const LocalProjectAffinityRootSchema = z.object({
+  source: TrustedProjectRootSourceSchema,
+  path: z.string().min(1),
+});
+export type LocalProjectAffinityRoot = z.infer<
+  typeof LocalProjectAffinityRootSchema
+>;
+
+export const RemoteProjectAffinityRootSchema = z.object({
+  source: z.literal("remote_hint"),
+  hint: z.string().min(1),
+});
+export type RemoteProjectAffinityRoot = z.infer<
+  typeof RemoteProjectAffinityRootSchema
+>;
+
+export const ProjectAffinityRootSchema = z.discriminatedUnion("source", [
+  LocalProjectAffinityRootSchema,
+  RemoteProjectAffinityRootSchema,
+]);
+export type ProjectAffinityRoot = z.infer<typeof ProjectAffinityRootSchema>;
+
+export const LocalProjectAffinityInputSchema = z.object({
+  roots: z.array(LocalProjectAffinityRootSchema).max(16).default([]),
+});
+export type LocalProjectAffinityInput = z.infer<
+  typeof LocalProjectAffinityInputSchema
+>;
+
+export const RemoteProjectAffinityInputSchema = z.object({
+  roots: z.array(RemoteProjectAffinityRootSchema).max(16).default([]),
+});
+export type RemoteProjectAffinityInput = z.infer<
+  typeof RemoteProjectAffinityInputSchema
+>;
+
+export const ProjectAffinityInputSchema = z.object({
+  roots: z.array(ProjectAffinityRootSchema).max(16).default([]),
+});
+export type ProjectAffinityInput = z.infer<typeof ProjectAffinityInputSchema>;
+
+export const PROJECT_AFFINITY_MAX_CONTRIBUTION = 0.03;
+export const AUXILIARY_RANKING_MAX_CONTRIBUTION = 0.08;
+
+export const ProjectAffinityConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  contribution: z
+    .number()
+    .finite()
+    .min(0)
+    .max(PROJECT_AFFINITY_MAX_CONTRIBUTION)
+    .default(PROJECT_AFFINITY_MAX_CONTRIBUTION),
+});
+export type ProjectAffinityConfig = z.infer<typeof ProjectAffinityConfigSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Context Schema
 // ─────────────────────────────────────────────────────────────────────────────
@@ -342,6 +410,9 @@ export const ConfigSchema = z.object({
 
   /** Private local retrieval trace recording. Absent means recording off. */
   retrievalTraces: RetrievalTraceConfigSchema.optional(),
+
+  /** Bounded project-aware retrieval affinity. */
+  projectAffinity: ProjectAffinityConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {