@gmickel/gno 1.23.0 → 1.24.0

package/src/cli/commands/setup.ts

@@ -0,0 +1,410 @@
+/**
+ * Direct verified-folder setup CLI composition.
+ *
+ * @module src/cli/commands/setup
+ */
+
+// node:readline/promises is the platform line-input API; Bun has no equivalent
+// for one default-No terminal confirmation.
+import { createInterface } from "node:readline/promises";
+
+import type {
+  FolderSetupError,
+  FolderSetupOptions,
+  FolderSetupResult,
+} from "../../core/folder-setup";
+import type {
+  FolderSetupReceipt,
+  SetupStageName,
+} from "../../core/setup-receipt";
+import type { SqliteAdapter } from "../../store/sqlite/adapter";
+
+import { getIndexDbPath } from "../../app/constants";
+import {
+  getConfigPaths,
+  isInitialized,
+  loadConfig,
+  toAbsolutePath,
+} from "../../config";
+import { setupFolder } from "../../core/folder-setup";
+import { persistSetupReceipt } from "../../core/setup-receipt";
+import { SqliteAdapter as DefaultSqliteAdapter } from "../../store/sqlite/adapter";
+import { init } from "./init";
+import {
+  scheduleSetupSemantic,
+  type SetupSemanticReceipt,
+} from "./setup-semantic";
+
+export const SETUP_COMMAND_SCHEMA_VERSION = "1.0" as const;
+
+export interface SetupCommandError {
+  code: string;
+  message: string;
+  remediation: string;
+}
+
+export interface SetupCommandResult {
+  schemaVersion: typeof SETUP_COMMAND_SCHEMA_VERSION;
+  status: "completed" | "failed";
+  lexical: {
+    receipt: FolderSetupReceipt | null;
+    error: SetupCommandError | null;
+  };
+  semantic: SetupSemanticReceipt | null;
+}
+
+export interface SetupCommandOptions {
+  folder: string;
+  name?: string;
+  exclude?: string[];
+  authorizeSecretRisk?: boolean;
+  semantic?: boolean;
+  indexName?: string;
+  configPath?: string;
+  offline?: boolean;
+  yes?: boolean;
+  json?: boolean;
+  quiet?: boolean;
+  stdinIsTTY?: boolean;
+  stderrIsTTY?: boolean;
+  progress?: (stage: SetupStageName, receipt: FolderSetupReceipt) => void;
+  confirmSecretRisk?: (receipt: FolderSetupReceipt) => Promise<boolean>;
+  setupFolderFn?: (options: FolderSetupOptions) => Promise<FolderSetupResult>;
+  scheduleSemanticFn?: typeof scheduleSetupSemantic;
+  initFn?: typeof init;
+  isInitializedFn?: typeof isInitialized;
+  createStore?: () => SqliteAdapter;
+}
+
+export interface SetupCommandOutcome {
+  result: SetupCommandResult;
+  exitCode: 0 | 1 | 2;
+}
+
+const VALIDATION_ERROR_CODES = new Set([
+  "folder_not_found",
+  "folder_not_directory",
+  "folder_unreadable",
+  "dangerous_root",
+  "secret_risk",
+  "empty_folder",
+  "unsupported_only",
+  "no_indexable_lexical_corpus",
+  "invalid_collection_name",
+  "collection_name_conflict",
+  "collection_overlap",
+  "collection_filter_disagreement",
+  "store_index_mismatch",
+  "setup_path_overlap",
+]);
+
+function commandError(
+  code: string,
+  message: string,
+  remediation: string
+): SetupCommandError {
+  return { code, message, remediation };
+}
+
+function failureOutcome(
+  error: SetupCommandError,
+  receipt: FolderSetupReceipt | null,
+  exitCode: 1 | 2
+): SetupCommandOutcome {
+  return {
+    result: {
+      schemaVersion: SETUP_COMMAND_SCHEMA_VERSION,
+      status: "failed",
+      lexical: { receipt, error },
+      semantic: null,
+    },
+    exitCode,
+  };
+}
+
+function exitCodeForSetupError(error: FolderSetupError): 1 | 2 {
+  return VALIDATION_ERROR_CODES.has(error.code) ? 1 : 2;
+}
+
+function firstActiveStage(receipt: FolderSetupReceipt): SetupStageName {
+  const stages = Object.entries(receipt.stages);
+  const active = stages.find(([, stage]) => stage.status === "in_progress");
+  if (active) {
+    return active[0] as SetupStageName;
+  }
+  const failed = stages.find(([, stage]) => stage.status === "failed");
+  if (failed) {
+    return failed[0] as SetupStageName;
+  }
+  const lastPassed = stages
+    .reverse()
+    .find(([, stage]) => stage.status === "passed");
+  return (lastPassed?.[0] as SetupStageName | undefined) ?? "preflight";
+}
+
+export async function terminalSecretConfirmation(
+  receipt: FolderSetupReceipt,
+  ask?: (question: string) => Promise<string>
+): Promise<boolean> {
+  process.stderr.write(
+    `Potential secret files detected in ${receipt.input.folder}\n`
+  );
+  process.stderr.write(
+    `Effective exclusions: ${receipt.input.excludes.join(", ") || "(none)"}\n`
+  );
+  const prompt = ask
+    ? null
+    : createInterface({
+        input: process.stdin,
+        output: process.stderr,
+      });
+  try {
+    try {
+      const answer = await (ask ?? prompt!.question.bind(prompt))(
+        "Index this folder despite the secret-file risk? [y/N] "
+      );
+      return /^(?:y|yes)$/i.test(answer.trim());
+    } catch {
+      return false;
+    }
+  } finally {
+    prompt?.close();
+  }
+}
+
+export function lexicalSuccessIsProven(receipt: FolderSetupReceipt): boolean {
+  const resultUri = receipt.activation?.evidence.resultUri;
+  return (
+    receipt.status === "completed" &&
+    receipt.activation?.ready === true &&
+    typeof resultUri === "string" &&
+    resultUri.length > 0
+  );
+}
+
+function validateSetupArguments(
+  options: SetupCommandOptions
+): SetupCommandError | null {
+  if (!options.folder.trim()) {
+    return commandError(
+      "invalid_folder",
+      "Folder is required",
+      "Pass a readable local folder to `gno setup`."
+    );
+  }
+  if (options.exclude?.some((value) => value.length === 0)) {
+    return commandError(
+      "invalid_exclusion",
+      "--exclude requires a non-empty literal pattern",
+      "Remove the empty occurrence or pass a literal exclusion pattern."
+    );
+  }
+  return null;
+}
+
+/**
+ * Execute the standalone setup transaction. This function returns classified
+ * outcomes; the Commander surface owns stdout/stderr rendering.
+ */
+async function executeSetup(
+  options: SetupCommandOptions
+): Promise<SetupCommandOutcome> {
+  const argumentError = validateSetupArguments(options);
+  if (argumentError) {
+    return failureOutcome(argumentError, null, 1);
+  }
+
+  const paths = getConfigPaths();
+  const configPath = toAbsolutePath(options.configPath ?? paths.configFile);
+  const dataDir = paths.dataDir;
+  const indexName = options.indexName ?? "default";
+  const initialized = await (options.isInitializedFn ?? isInitialized)(
+    configPath
+  );
+  if (!initialized) {
+    const initializedResult = await (options.initFn ?? init)({
+      configPath,
+      yes: true,
+    });
+    if (!initializedResult.success) {
+      return failureOutcome(
+        commandError(
+          "bootstrap_failed",
+          initializedResult.error ?? "Failed to initialize GNO",
+          "Fix config/data-directory permissions and rerun setup."
+        ),
+        null,
+        2
+      );
+    }
+  }
+
+  const configResult = await loadConfig(configPath);
+  if (!configResult.ok) {
+    return failureOutcome(
+      commandError(
+        "config_load_failed",
+        configResult.error.message,
+        "Repair the selected config and rerun setup."
+      ),
+      null,
+      2
+    );
+  }
+
+  const store =
+    options.createStore?.() ?? (new DefaultSqliteAdapter() as SqliteAdapter);
+  store.setConfigPath(configPath);
+  const opened = await store.open(
+    getIndexDbPath(indexName),
+    configResult.value.ftsTokenizer
+  );
+  if (!opened.ok) {
+    await store.close();
+    return failureOutcome(
+      commandError(
+        "store_open_failed",
+        opened.error.message,
+        "Repair the selected index database and rerun setup."
+      ),
+      null,
+      2
+    );
+  }
+
+  const setupFolderFn = options.setupFolderFn ?? setupFolder;
+  let lastProgress: string | null = null;
+  const receiptWriter = async (receipt: FolderSetupReceipt): Promise<void> => {
+    await persistSetupReceipt(receipt);
+    if (options.quiet || options.json) {
+      return;
+    }
+    const stage = firstActiveStage(receipt);
+    const key = stage;
+    if (lastProgress !== key) {
+      lastProgress = key;
+      options.progress?.(stage, receipt);
+    }
+  };
+
+  const runCore = (authorized: boolean): Promise<FolderSetupResult> =>
+    setupFolderFn({
+      folder: options.folder,
+      store,
+      configPath,
+      dataDir,
+      indexName,
+      name: options.name,
+      exclude: options.exclude,
+      secretRiskAuthorized: authorized,
+      receiptWriter,
+    });
+
+  try {
+    let lexicalResult = await runCore(options.authorizeSecretRisk === true);
+    if (
+      !lexicalResult.ok &&
+      lexicalResult.error.code === "secret_risk" &&
+      lexicalResult.receipt &&
+      options.authorizeSecretRisk !== true
+    ) {
+      const mayPrompt =
+        options.json !== true &&
+        options.yes !== true &&
+        (options.stdinIsTTY ?? process.stdin.isTTY ?? false) &&
+        (options.stderrIsTTY ?? process.stderr.isTTY ?? false);
+      if (mayPrompt) {
+        const confirmed = await (
+          options.confirmSecretRisk ?? terminalSecretConfirmation
+        )(lexicalResult.receipt);
+        if (confirmed) {
+          lexicalResult = await runCore(true);
+        }
+      }
+    }
+
+    if (!lexicalResult.ok) {
+      return failureOutcome(
+        lexicalResult.error,
+        lexicalResult.receipt,
+        exitCodeForSetupError(lexicalResult.error)
+      );
+    }
+    if (!lexicalSuccessIsProven(lexicalResult.receipt)) {
+      return failureOutcome(
+        commandError(
+          "lexical_success_invariant_failed",
+          "Setup completed without an exact lexical retrieval result",
+          "Rerun setup after repairing the selected index."
+        ),
+        lexicalResult.receipt,
+        2
+      );
+    }
+
+    const semantic = await (
+      options.scheduleSemanticFn ?? scheduleSetupSemantic
+    )({
+      setupReceipt: lexicalResult.receipt,
+      dataDir,
+      configPath,
+      indexName,
+      offline: options.offline ?? false,
+      disabled: options.semantic === false,
+    });
+    return {
+      result: {
+        schemaVersion: SETUP_COMMAND_SCHEMA_VERSION,
+        status: "completed",
+        lexical: {
+          receipt: lexicalResult.receipt,
+          error: null,
+        },
+        semantic,
+      },
+      exitCode: 0,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export async function setup(
+  options: SetupCommandOptions
+): Promise<SetupCommandOutcome> {
+  try {
+    return await executeSetup(options);
+  } catch (error) {
+    return failureOutcome(
+      commandError(
+        "setup_runtime_failed",
+        error instanceof Error ? error.message : String(error),
+        "Fix the reported local setup error and rerun setup."
+      ),
+      null,
+      2
+    );
+  }
+}
+
+export function formatSetupResult(
+  result: SetupCommandResult,
+  options: { json: boolean }
+): string {
+  if (options.json) {
+    return JSON.stringify(result, null, 2);
+  }
+  const receipt = result.lexical.receipt;
+  if (result.status === "failed") {
+    const error = result.lexical.error;
+    return `${error?.code ?? "setup_failed"}: ${error?.message ?? "Setup failed"}. ${error?.remediation ?? ""}`.trim();
+  }
+  const semantic = result.semantic;
+  return [
+    `Setup ${receipt?.collection.disposition}: ${receipt?.collection.name}`,
+    `result=${receipt?.activation?.evidence.resultUri}`,
+    `receipt=${receipt?.paths.receipt}`,
+    `semantic=${semantic?.status ?? "pending"}`,
+    `resume=${semantic?.resumeCommand ?? "gno embed"}`,
+  ].join(" ");
+}

package/src/cli/program.ts

@@ -1346,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]")
@@ -2398,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);
+  }
+}