@gmickel/gno 1.22.0 → 1.24.0

package/src/core/project-affinity.ts

@@ -0,0 +1,330 @@
+/**
+ * Trusted project-root resolution for project-aware retrieval affinity.
+ *
+ * This module resolves local roots only. Remote hints remain opaque and never
+ * trigger filesystem probes. Returned metadata is path-redacted; ranking is a
+ * separate concern.
+ *
+ * @module src/core/project-affinity
+ */
+
+// node:fs/promises for directory stat/realpath (no Bun directory equivalent)
+import { realpath, stat } from "node:fs/promises";
+// node:path for path utilities (no Bun path utils)
+import { dirname, join, relative, sep } from "node:path";
+
+import type {
+  Collection,
+  ProjectAffinityInput,
+  ProjectAffinityRoot,
+  TrustedProjectRootSource,
+} from "../config/types";
+
+import { isCanonicalPathContained } from "./validation";
+
+export type ProjectAffinityZeroReason =
+  | "no_collection_match"
+  | "root_unavailable"
+  | "untrusted_remote_hint";
+
+export type ProjectAffinityRelation =
+  | "collection_contains_root"
+  | "exact"
+  | "root_contains_collection";
+
+export interface ProjectAffinityMatch {
+  collection: string;
+  collectionAlias: string;
+  distance: number;
+  relation: ProjectAffinityRelation;
+  rootAlias: string;
+  source: TrustedProjectRootSource;
+}
+
+export interface ProjectAffinityRootMetadata {
+  collectionAliases: string[];
+  reason: ProjectAffinityZeroReason | null;
+  repositoryRootDiscovered: boolean;
+  rootAlias: string;
+  source: ProjectAffinityRoot["source"];
+  status: "matched" | "zero";
+}
+
+export interface ProjectAffinityResolution {
+  matches: ProjectAffinityMatch[];
+  roots: ProjectAffinityRootMetadata[];
+}
+
+export interface ProjectAffinityResolverDependencies {
+  canonicalizePath: (path: string) => Promise<string>;
+  discoverRepositoryRoot: (path: string) => Promise<string | null>;
+}
+
+/**
+ * Trust is supplied by the invoking surface, never inferred from payload data.
+ */
+export interface ProjectAffinityResolverContext {
+  channel: "local" | "remote";
+}
+
+interface CanonicalCollection {
+  alias: string;
+  name: string;
+  path: string;
+}
+
+interface CanonicalTrustedRoot {
+  path: string;
+  repositoryRootDiscovered: boolean;
+  rootAlias: string;
+  source: TrustedProjectRootSource;
+}
+
+const alias = (namespace: "collection" | "root", value: string): string => {
+  const hash = new Bun.CryptoHasher("sha256")
+    .update(`${namespace}\0${value}`)
+    .digest("hex")
+    .slice(0, 12);
+  return `${namespace}_${hash}`;
+};
+
+const defaultCanonicalizePath = (path: string): Promise<string> =>
+  realpath(path);
+
+const isDirectoryOrFile = async (path: string): Promise<boolean> => {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const defaultDiscoverRepositoryRoot = async (
+  startingPath: string
+): Promise<string | null> => {
+  let current = startingPath;
+  while (true) {
+    if (await isDirectoryOrFile(join(current, ".git"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+};
+
+const pathDistance = (parent: string, child: string): number => {
+  const nestedPath = relative(parent, child);
+  if (nestedPath === "") {
+    return 0;
+  }
+  return nestedPath.split(sep).filter(Boolean).length;
+};
+
+const describeRelationship = (
+  collectionPath: string,
+  rootPath: string
+): Pick<ProjectAffinityMatch, "distance" | "relation"> | null => {
+  if (collectionPath === rootPath) {
+    return { distance: 0, relation: "exact" };
+  }
+  if (isCanonicalPathContained(collectionPath, rootPath)) {
+    return {
+      distance: pathDistance(collectionPath, rootPath),
+      relation: "collection_contains_root",
+    };
+  }
+  if (isCanonicalPathContained(rootPath, collectionPath)) {
+    return {
+      distance: pathDistance(rootPath, collectionPath),
+      relation: "root_contains_collection",
+    };
+  }
+  return null;
+};
+
+const canonicalizeCollections = async (
+  collections: readonly Collection[],
+  canonicalizePath: ProjectAffinityResolverDependencies["canonicalizePath"]
+): Promise<CanonicalCollection[]> => {
+  const resolved = await Promise.all(
+    collections.map(async (collection): Promise<CanonicalCollection | null> => {
+      try {
+        const path = await canonicalizePath(collection.path);
+        return {
+          alias: alias("collection", collection.name),
+          name: collection.name,
+          path,
+        };
+      } catch {
+        return null;
+      }
+    })
+  );
+  return resolved
+    .filter((collection): collection is CanonicalCollection =>
+      Boolean(collection)
+    )
+    .sort((left, right) => left.name.localeCompare(right.name));
+};
+
+const canonicalizeTrustedRoot = async (
+  root: Extract<ProjectAffinityRoot, { path: string }>,
+  dependencies: ProjectAffinityResolverDependencies
+): Promise<CanonicalTrustedRoot | null> => {
+  let canonicalPath: string;
+  try {
+    canonicalPath = await dependencies.canonicalizePath(root.path);
+  } catch {
+    return null;
+  }
+
+  let repositoryRootDiscovered = false;
+  if (root.source === "cli_cwd" || root.source === "cli_worktree") {
+    let discovered: string | null = null;
+    try {
+      discovered = await dependencies.discoverRepositoryRoot(canonicalPath);
+    } catch {
+      // Repository discovery is opportunistic; the trusted canonical cwd
+      // remains a valid affinity root when discovery is unavailable.
+    }
+    if (discovered) {
+      try {
+        canonicalPath = await dependencies.canonicalizePath(discovered);
+        repositoryRootDiscovered = true;
+      } catch {
+        return null;
+      }
+    }
+  }
+
+  return {
+    path: canonicalPath,
+    repositoryRootDiscovered,
+    rootAlias: alias("root", canonicalPath),
+    source: root.source,
+  };
+};
+
+const zeroMetadata = (
+  root: ProjectAffinityRoot,
+  reason: ProjectAffinityZeroReason,
+  source: ProjectAffinityRoot["source"] = root.source
+): ProjectAffinityRootMetadata => ({
+  collectionAliases: [],
+  reason,
+  repositoryRootDiscovered: false,
+  rootAlias: alias(
+    "root",
+    root.source === "remote_hint" ? root.hint : root.path
+  ),
+  source,
+  status: "zero",
+});
+
+const relationOrder: Record<ProjectAffinityRelation, number> = {
+  exact: 0,
+  collection_contains_root: 1,
+  root_contains_collection: 2,
+};
+
+const compareMatches = (
+  left: ProjectAffinityMatch,
+  right: ProjectAffinityMatch
+): number =>
+  relationOrder[left.relation] - relationOrder[right.relation] ||
+  left.distance - right.distance ||
+  left.collection.localeCompare(right.collection) ||
+  left.rootAlias.localeCompare(right.rootAlias);
+
+export async function resolveProjectAffinity(
+  input: ProjectAffinityInput,
+  collections: readonly Collection[],
+  context: ProjectAffinityResolverContext,
+  overrides: Partial<ProjectAffinityResolverDependencies> = {}
+): Promise<ProjectAffinityResolution> {
+  if (context.channel === "remote") {
+    return {
+      matches: [],
+      roots: input.roots.map((root) =>
+        zeroMetadata(root, "untrusted_remote_hint", "remote_hint")
+      ),
+    };
+  }
+
+  const dependencies: ProjectAffinityResolverDependencies = {
+    canonicalizePath: overrides.canonicalizePath ?? defaultCanonicalizePath,
+    discoverRepositoryRoot:
+      overrides.discoverRepositoryRoot ?? defaultDiscoverRepositoryRoot,
+  };
+  const trustedRoots = input.roots.filter(
+    (root): root is Extract<ProjectAffinityRoot, { path: string }> =>
+      root.source !== "remote_hint"
+  );
+  const canonicalCollections =
+    trustedRoots.length === 0
+      ? []
+      : await canonicalizeCollections(
+          collections,
+          dependencies.canonicalizePath
+        );
+  const matches: ProjectAffinityMatch[] = [];
+  const roots: ProjectAffinityRootMetadata[] = [];
+
+  for (const root of input.roots) {
+    if (root.source === "remote_hint") {
+      roots.push(zeroMetadata(root, "untrusted_remote_hint"));
+      continue;
+    }
+
+    const canonicalRoot = await canonicalizeTrustedRoot(root, dependencies);
+    if (!canonicalRoot) {
+      roots.push(zeroMetadata(root, "root_unavailable"));
+      continue;
+    }
+
+    const rootMatches = canonicalCollections
+      .map((collection): ProjectAffinityMatch | null => {
+        const relationship = describeRelationship(
+          collection.path,
+          canonicalRoot.path
+        );
+        return relationship
+          ? {
+              collection: collection.name,
+              collectionAlias: collection.alias,
+              rootAlias: canonicalRoot.rootAlias,
+              source: canonicalRoot.source,
+              ...relationship,
+            }
+          : null;
+      })
+      .filter((match): match is ProjectAffinityMatch => Boolean(match))
+      .sort(compareMatches);
+
+    if (rootMatches.length === 0) {
+      roots.push({
+        ...zeroMetadata(root, "no_collection_match"),
+        repositoryRootDiscovered: canonicalRoot.repositoryRootDiscovered,
+        rootAlias: canonicalRoot.rootAlias,
+      });
+      continue;
+    }
+
+    matches.push(...rootMatches);
+    roots.push({
+      collectionAliases: rootMatches.map((match) => match.collectionAlias),
+      reason: null,
+      repositoryRootDiscovered: canonicalRoot.repositoryRootDiscovered,
+      rootAlias: canonicalRoot.rootAlias,
+      source: root.source,
+      status: "matched",
+    });
+  }
+
+  matches.sort(compareMatches);
+  return { matches, roots };
+}

package/src/core/setup-activation.ts

@@ -0,0 +1,309 @@
+import type {
+  ActivationVerificationCode,
+  ActivationVerificationReceipt,
+  StorePort,
+  StoreResult,
+} from "../store/types";
+import type { ConnectorVerificationCode } from "./connector-policy";
+
+import { getConnectorVerificationRemediation } from "./connector-policy";
+
+export const SETUP_ACTIVATION_SCHEMA_VERSION = "1.0" as const;
+
+export type SetupConnectorInstallation = "installed" | "reused" | "failed";
+export type SetupConnectorVerification =
+  | "passed"
+  | "failed"
+  | "skipped"
+  | "not_run";
+export type SetupConnectorCode =
+  | "connector_verified"
+  | "connector_configuration_unavailable"
+  | "connector_install_failed"
+  | "connector_verification_failed"
+  | ConnectorVerificationCode;
+
+export interface SetupConnectorDefinition {
+  id: string;
+  kind: "skill" | "mcp";
+  target: string;
+  scope: "user" | "project";
+}
+
+export interface SetupConnectorState extends SetupConnectorDefinition {
+  installed: boolean;
+  configurationError: boolean;
+}
+
+export interface SetupConnectorResult {
+  connectorId: string;
+  kind: "skill" | "mcp";
+  target: string;
+  scope: "user" | "project";
+  installation: SetupConnectorInstallation;
+  verification: SetupConnectorVerification;
+  code: SetupConnectorCode;
+  remediation: string;
+  receipt: ActivationVerificationReceipt | null;
+}
+
+export interface SetupConnectorComposition {
+  status: "completed" | "completed_with_actions";
+  connectors: SetupConnectorResult[];
+}
+
+export interface SetupConnectorInstallContext {
+  indexName: string;
+  configPath: string;
+}
+
+export interface SetupConnectorCompositionDeps {
+  getStates: () => Promise<SetupConnectorState[]>;
+  install: (
+    connectorId: string,
+    context: SetupConnectorInstallContext
+  ) => Promise<SetupConnectorState>;
+  verify: (
+    connectorId: string,
+    store: StorePort,
+    collection: string
+  ) => Promise<StoreResult<ActivationVerificationReceipt>>;
+}
+
+export interface ComposeSetupConnectorsOptions {
+  connectorIds: string[];
+  definitions: SetupConnectorDefinition[];
+  collection: string;
+  store: StorePort;
+  installContext: SetupConnectorInstallContext;
+  deps: SetupConnectorCompositionDeps;
+}
+
+const completedRemediation = "No action required.";
+const installFailureRemediation =
+  "Repair the selected connector configuration or permissions, then rerun the same setup command.";
+const configurationFailureRemediation =
+  "Repair the selected connector configuration without overwriting it, then rerun the same setup command.";
+const verificationFailureRemediation =
+  "Retry the same setup command; if verification still fails, run gno doctor.";
+
+function isConnectorVerificationCode(
+  code: ActivationVerificationCode | undefined
+): code is ConnectorVerificationCode {
+  return (
+    code === "connector_not_configured" ||
+    code === "connector_probe_unavailable" ||
+    code === "connector_unsupported_config" ||
+    code === "connector_start_failed" ||
+    code === "connector_timeout" ||
+    code === "connector_missing_tools" ||
+    code === "connector_status_failed" ||
+    code === "connector_search_failed" ||
+    code === "connector_result_mismatch" ||
+    code === "target_runtime_unverifiable"
+  );
+}
+
+function dedupeConnectorIds(connectorIds: string[]): string[] {
+  const seen = new Set<string>();
+  return connectorIds.filter((connectorId) => {
+    if (seen.has(connectorId)) {
+      return false;
+    }
+    seen.add(connectorId);
+    return true;
+  });
+}
+
+function failedResult(
+  definition: SetupConnectorDefinition,
+  input: {
+    installation: SetupConnectorInstallation;
+    code:
+      | "connector_configuration_unavailable"
+      | "connector_install_failed"
+      | "connector_verification_failed";
+    remediation: string;
+  }
+): SetupConnectorResult {
+  return {
+    connectorId: definition.id,
+    kind: definition.kind,
+    target: definition.target,
+    scope: definition.scope,
+    installation: input.installation,
+    verification:
+      input.code === "connector_verification_failed" ? "failed" : "not_run",
+    code: input.code,
+    remediation: input.remediation,
+    receipt: null,
+  };
+}
+
+function receiptResult(
+  definition: SetupConnectorDefinition,
+  installation: SetupConnectorInstallation,
+  receipt: ActivationVerificationReceipt
+): SetupConnectorResult {
+  const connectorStage = receipt.stages.connector;
+  const verification =
+    connectorStage.status === "passed" ||
+    connectorStage.status === "failed" ||
+    connectorStage.status === "skipped"
+      ? connectorStage.status
+      : "failed";
+  const code =
+    connectorStage.status === "passed"
+      ? "connector_verified"
+      : isConnectorVerificationCode(connectorStage.code)
+        ? connectorStage.code
+        : "connector_verification_failed";
+  const remediation =
+    code === "connector_verified"
+      ? completedRemediation
+      : code === "connector_verification_failed"
+        ? verificationFailureRemediation
+        : getConnectorVerificationRemediation(code, definition.target);
+  return {
+    connectorId: definition.id,
+    kind: definition.kind,
+    target: definition.target,
+    scope: definition.scope,
+    installation,
+    verification,
+    code,
+    remediation,
+    receipt,
+  };
+}
+
+export function unavailableSetupConnectorComposition(
+  definitions: SetupConnectorDefinition[]
+): SetupConnectorComposition {
+  return {
+    status: "completed_with_actions",
+    connectors: definitions.map((definition) => ({
+      connectorId: definition.id,
+      kind: definition.kind,
+      target: definition.target,
+      scope: definition.scope,
+      installation: "failed",
+      verification: "not_run",
+      code: "connector_verification_failed",
+      remediation: verificationFailureRemediation,
+      receipt: null,
+    })),
+  };
+}
+
+async function currentStateAfterInstallFailure(
+  connectorId: string,
+  deps: SetupConnectorCompositionDeps
+): Promise<SetupConnectorState | null> {
+  try {
+    const states = await deps.getStates();
+    return states.find(({ id }) => id === connectorId) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function composeOneConnector(
+  definition: SetupConnectorDefinition,
+  initialState: SetupConnectorState | null,
+  options: ComposeSetupConnectorsOptions
+): Promise<SetupConnectorResult> {
+  if (!initialState || initialState.configurationError) {
+    return failedResult(definition, {
+      installation: "failed",
+      code: "connector_configuration_unavailable",
+      remediation: configurationFailureRemediation,
+    });
+  }
+
+  let installation: SetupConnectorInstallation = "reused";
+  if (!initialState.installed) {
+    try {
+      const installed = await options.deps.install(
+        definition.id,
+        options.installContext
+      );
+      if (!installed.installed || installed.configurationError) {
+        return failedResult(definition, {
+          installation: "failed",
+          code: "connector_install_failed",
+          remediation: installFailureRemediation,
+        });
+      }
+      installation = "installed";
+    } catch {
+      const racedState = await currentStateAfterInstallFailure(
+        definition.id,
+        options.deps
+      );
+      if (!racedState?.installed || racedState.configurationError) {
+        return failedResult(definition, {
+          installation: "failed",
+          code: "connector_install_failed",
+          remediation: installFailureRemediation,
+        });
+      }
+      installation = "reused";
+    }
+  }
+
+  try {
+    const verification = await options.deps.verify(
+      definition.id,
+      options.store,
+      options.collection
+    );
+    if (!verification.ok) {
+      return failedResult(definition, {
+        installation,
+        code: "connector_verification_failed",
+        remediation: verificationFailureRemediation,
+      });
+    }
+    return receiptResult(definition, installation, verification.value);
+  } catch {
+    return failedResult(definition, {
+      installation,
+      code: "connector_verification_failed",
+      remediation: verificationFailureRemediation,
+    });
+  }
+}
+
+/**
+ * Compose requested connector install/verification after lexical setup.
+ * Callers own store lifecycle and validation of connector IDs.
+ */
+export async function composeSetupConnectors(
+  options: ComposeSetupConnectorsOptions
+): Promise<SetupConnectorComposition> {
+  const requestedIds = dedupeConnectorIds(options.connectorIds);
+  let states: SetupConnectorState[] = [];
+  try {
+    states = await options.deps.getStates();
+  } catch {
+    // Per-target bounded results below deliberately hide the unbounded error.
+  }
+
+  const results: SetupConnectorResult[] = [];
+  for (const connectorId of requestedIds) {
+    const definition = options.definitions.find(({ id }) => id === connectorId);
+    if (!definition) {
+      continue;
+    }
+    const state = states.find(({ id }) => id === connectorId) ?? null;
+    results.push(await composeOneConnector(definition, state, options));
+  }
+
+  return {
+    status: results.every(({ verification }) => verification === "passed")
+      ? "completed"
+      : "completed_with_actions",
+    connectors: results,
+  };
+}