@gmickel/gno 1.38.0 → 1.39.0

package/src/cli/commands/agents/harnesses.ts

@@ -0,0 +1,298 @@
+/**
+ * Harness matrix for `gno agents`: which global (user-scope) instruction
+ * file each supported harness reads, how the harness is detected, and which
+ * import chains make a separate install redundant.
+ *
+ * Discovery is standard documented locations only — nonstandard/multi-
+ * instance layouts are served by the explicit `--extra-dir` flag, never by
+ * guessed discovery.
+ *
+ * @module src/cli/commands/agents/harnesses
+ */
+
+// node:fs: detection needs synchronous stat/realpath (symlink-aware identity)
+// with no Bun equivalent.
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  resolve,
+} from "node:path";
+
+import { CliError } from "../../errors.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Environment Variables
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Override home dir for testing / sandboxed live verification. */
+export const ENV_AGENTS_HOME_OVERRIDE = "GNO_AGENTS_HOME_OVERRIDE";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type HarnessId =
+  | "claude"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "grok"
+  | "hermes"
+  | "openclaw";
+
+export const HARNESS_IDS: HarnessId[] = [
+  "claude",
+  "codex",
+  "cursor",
+  "opencode",
+  "grok",
+  "hermes",
+  "openclaw",
+];
+
+interface HarnessDef {
+  id: HarnessId;
+  label: string;
+  /** Harness config dir (detection root), relative to home. */
+  configDir: string;
+  /** Instruction file: inside the config dir, or directly under home. */
+  instructionFile: { dir: "config" | "home"; name: string };
+  /**
+   * Env var naming the harness's documented config-dir override
+   * (honored only when no explicit homeDir override is active).
+   */
+  configDirEnvVar?: string;
+  /**
+   * Import chain: this harness reads another harness's instruction file, so
+   * a separate install would double the block. Data-driven so future chains
+   * are matrix entries, not code changes.
+   */
+  coveredBy?: HarnessId;
+}
+
+const HARNESS_DEFS: Record<HarnessId, HarnessDef> = {
+  claude: {
+    id: "claude",
+    label: "Claude Code",
+    configDir: ".claude",
+    instructionFile: { dir: "config", name: "CLAUDE.md" },
+    configDirEnvVar: "CLAUDE_CONFIG_DIR",
+  },
+  codex: {
+    id: "codex",
+    label: "Codex",
+    configDir: ".codex",
+    instructionFile: { dir: "config", name: "AGENTS.md" },
+    configDirEnvVar: "CODEX_HOME",
+  },
+  cursor: {
+    id: "cursor",
+    label: "Cursor Agent",
+    configDir: ".cursor",
+    // Cursor Agent discovers AGENTS.md walking from the working directory
+    // towards the home directory; ~/AGENTS.md is its user-global surface.
+    instructionFile: { dir: "home", name: "AGENTS.md" },
+  },
+  opencode: {
+    id: "opencode",
+    label: "OpenCode",
+    configDir: ".config/opencode",
+    instructionFile: { dir: "config", name: "AGENTS.md" },
+  },
+  grok: {
+    id: "grok",
+    label: "Grok Build",
+    configDir: ".grok",
+    // Grok imports the Claude global instruction file — no file of its own;
+    // `coveredBy` makes resolution report Claude's file for it.
+    instructionFile: { dir: "config", name: "AGENTS.md" },
+    coveredBy: "claude",
+  },
+  hermes: {
+    id: "hermes",
+    label: "Hermes",
+    configDir: ".hermes",
+    instructionFile: { dir: "config", name: "SOUL.md" },
+  },
+  openclaw: {
+    id: "openclaw",
+    label: "OpenClaw",
+    configDir: ".openclaw/workspace",
+    instructionFile: { dir: "config", name: "AGENTS.md" },
+  },
+};
+
+export interface ResolvedTarget {
+  /** Harness id, or "extra-dir" for explicit --extra-dir paths. */
+  id: HarnessId | "extra-dir";
+  label: string;
+  /** Detection root (harness config dir, or the extra dir itself). */
+  configDir: string;
+  /** Absolute path to the instruction file the harness reads. */
+  file: string;
+  /** Real (symlink-resolved) identity of the file, for dedupe + writes. */
+  realFile: string;
+  /** Whether the harness is detected on this machine. */
+  detected: boolean;
+  /** Import chain target this harness is covered by, when applicable. */
+  coveredBy?: HarnessId;
+}
+
+export interface ResolveOptions {
+  /** Explicit home override (testing / sandboxed verification). When set,
+   *  harness config-dir env overrides are ignored for determinism. */
+  homeDir?: string;
+  /** Explicit extra instruction dirs (nonstandard/multi-instance layouts). */
+  extraDirs?: string[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resolution
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Symlink-resolved identity of an instruction file. An existing file resolves
+ * fully (so a canonical file linked into several harnesses is written once,
+ * through the link); a file that does not exist yet resolves its parent dir,
+ * so two harnesses whose config dirs are links to one place still share an
+ * identity. Anything unresolvable falls back to the normalized path.
+ */
+export function realIdentity(file: string): string {
+  try {
+    return realpathSync(file);
+  } catch {
+    const normalized = normalize(file);
+    try {
+      return join(realpathSync(dirname(normalized)), basename(normalized));
+    } catch {
+      return normalized;
+    }
+  }
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveHarness(
+  def: HarnessDef,
+  home: string,
+  explicitHome: boolean
+): ResolvedTarget {
+  let configDir = join(home, def.configDir);
+
+  if (!explicitHome && def.configDirEnvVar) {
+    const envOverride = process.env[def.configDirEnvVar];
+    if (envOverride) {
+      if (!isAbsolute(envOverride)) {
+        throw new CliError(
+          "VALIDATION",
+          `${def.configDirEnvVar} must be an absolute path`
+        );
+      }
+      configDir = normalize(envOverride);
+    }
+  }
+
+  // A covered harness (grok → claude) reads its covering harness's file and
+  // has none of its own, so that is the file its rows report.
+  const file = def.coveredBy
+    ? resolveHarness(HARNESS_DEFS[def.coveredBy], home, explicitHome).file
+    : def.instructionFile.dir === "home"
+      ? join(home, def.instructionFile.name)
+      : join(configDir, def.instructionFile.name);
+
+  return {
+    id: def.id,
+    label: def.label,
+    configDir,
+    file,
+    realFile: realIdentity(file),
+    detected: isDirectory(configDir),
+    coveredBy: def.coveredBy,
+  };
+}
+
+/** Instruction file candidates for --extra-dir, in priority order. */
+const EXTRA_DIR_FILE_CANDIDATES = ["CLAUDE.md", "AGENTS.md", "SOUL.md"];
+const DEFAULT_EXTRA_DIR_FILE = "AGENTS.md";
+
+function resolveExtraDir(dir: string): ResolvedTarget {
+  const abs = resolve(dir);
+  if (!isDirectory(abs)) {
+    throw new CliError(
+      "VALIDATION",
+      `--extra-dir ${dir} does not exist or is not a directory. The installer never fabricates harness directories.`
+    );
+  }
+  const existing = EXTRA_DIR_FILE_CANDIDATES.find((name) =>
+    existsSync(join(abs, name))
+  );
+  const file = join(abs, existing ?? DEFAULT_EXTRA_DIR_FILE);
+  return {
+    id: "extra-dir",
+    label: `extra dir ${abs}`,
+    configDir: abs,
+    file,
+    realFile: realIdentity(file),
+    detected: true,
+  };
+}
+
+/** Covering chain for an explicit target (e.g. grok → claude), covering first. */
+function coveringChain(id: HarnessId): HarnessId[] {
+  const chain: HarnessId[] = [];
+  let cursor = HARNESS_DEFS[id].coveredBy;
+  while (cursor && !chain.includes(cursor) && cursor !== id) {
+    chain.unshift(cursor);
+    cursor = HARNESS_DEFS[cursor].coveredBy;
+  }
+  return chain;
+}
+
+/**
+ * Resolve all requested targets to concrete instruction files.
+ * `target: "all"` = every supported harness (detection filters at plan time).
+ * An explicit covered target (e.g. `grok`) also resolves its covering
+ * target(s) so the file it actually reads is planned/verified — but only when
+ * the requested target itself is detected; an absent one is reported
+ * `not-detected` without touching the covering harness's file.
+ */
+export function resolveTargets(
+  target: HarnessId | "all",
+  opts: ResolveOptions = {}
+): ResolvedTarget[] {
+  // Any home override (option or env) suppresses harness config-dir env
+  // overrides too — an overridden home is an isolation request.
+  const explicitHome =
+    opts.homeDir !== undefined ||
+    process.env[ENV_AGENTS_HOME_OVERRIDE] !== undefined;
+  const home =
+    opts.homeDir ?? process.env[ENV_AGENTS_HOME_OVERRIDE] ?? homedir();
+  const one = (id: HarnessId): ResolvedTarget =>
+    resolveHarness(HARNESS_DEFS[id], home, explicitHome);
+
+  let results: ResolvedTarget[];
+  if (target === "all") {
+    results = HARNESS_IDS.map(one);
+  } else {
+    const leaf = one(target);
+    results = leaf.detected
+      ? [...coveringChain(target).map(one), leaf]
+      : [leaf];
+  }
+
+  for (const dir of opts.extraDirs ?? []) {
+    results.push(resolveExtraDir(dir));
+  }
+  return results;
+}

package/src/cli/commands/agents/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Agents command exports.
+ *
+ * @module src/cli/commands/agents
+ */
+
+export {
+  BEGIN_MARKER,
+  BLOCK_VERSION,
+  END_MARKER,
+  extractBlock,
+  hashBlockBody,
+  renderBlock,
+  renderBlockBody,
+} from "./block.js";
+export {
+  type AgentsOptions,
+  installAgents,
+  parseTargetOption,
+  uninstallAgents,
+  verifyAgents,
+} from "./commands.js";
+export {
+  applyPlan,
+  planTargets,
+  type TargetPlan,
+  unifiedDiff,
+} from "./engine.js";
+export {
+  ENV_AGENTS_HOME_OVERRIDE,
+  type HarnessId,
+  HARNESS_IDS,
+  type ResolvedTarget,
+  resolveTargets,
+} from "./harnesses.js";

package/src/cli/commands/completion/scripts.ts

@@ -57,6 +57,11 @@ const COMMANDS = [
   "skill uninstall",
   "skill show",
   "skill paths",
+  "agents",
+  "agents install",
+  "agents update",
+  "agents verify",
+  "agents uninstall",
   "completion",
   "completion output",
   "completion install",

package/src/cli/program.ts

@@ -364,6 +364,7 @@ export function createProgram(): Command {
   wireKnowledgeDeltaCommands(program);
   wireMcpCommand(program);
   wireSkillCommands(program);
+  wireAgentsCommands(program);
   wireDaemonCommand(program);
   wireServeCommand(program);
   wireCompletionCommand(program);
@@ -3320,6 +3321,109 @@ function wireSkillCommands(program: Command): void {
     });
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Agents Commands (install, update, verify, uninstall)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function wireAgentsCommands(program: Command): void {
+  const agentsCmd = program
+    .command("agents")
+    .description(
+      "Manage the GNO protocol block in global harness instruction files"
+    );
+
+  const targetDescription =
+    "target harness (claude, codex, cursor, opencode, grok, hermes, openclaw, all)";
+
+  const collectExtraDir = (value: string, previous: string[]): string[] => [
+    ...previous,
+    value,
+  ];
+
+  const parseCommonOpts = async (cmdOpts: Record<string, unknown>) => {
+    const { parseTargetOption } = await import("./commands/agents/commands.js");
+    return {
+      target: parseTargetOption((cmdOpts.target as string) ?? "all"),
+      extraDirs: (cmdOpts.extraDir as string[] | undefined) ?? [],
+      dryRun: Boolean(cmdOpts.dryRun),
+      // The root program also defines a global --json and may consume the
+      // flag; leave undefined here so the runner falls back to globals.
+      json: cmdOpts.json ? true : undefined,
+    };
+  };
+
+  agentsCmd
+    .command("install")
+    .description(
+      "Install the GNO protocol block into detected harnesses' global instruction files"
+    )
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { installAgents } = await import("./commands/agents/commands.js");
+      await installAgents(await parseCommonOpts(cmdOpts), "install");
+    });
+
+  agentsCmd
+    .command("update")
+    .description("Refresh an installed GNO protocol block in place")
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { installAgents } = await import("./commands/agents/commands.js");
+      await installAgents(await parseCommonOpts(cmdOpts), "update");
+    });
+
+  agentsCmd
+    .command("verify")
+    .description(
+      "Verify installed GNO protocol blocks (one block, version + hash)"
+    )
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { verifyAgents } = await import("./commands/agents/commands.js");
+      await verifyAgents(await parseCommonOpts(cmdOpts));
+    });
+
+  agentsCmd
+    .command("uninstall")
+    .description("Remove the GNO protocol block and markers from harness files")
+    .option("-t, --target <target>", targetDescription, "all")
+    .option(
+      "--extra-dir <path>",
+      "additional instruction dir (repeatable, for nonstandard layouts)",
+      collectExtraDir,
+      [] as string[]
+    )
+    .option("--dry-run", "print the unified diff and write nothing")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const { uninstallAgents } = await import("./commands/agents/commands.js");
+      await uninstallAgents(await parseCommonOpts(cmdOpts));
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tags Commands (list, add, rm)
 // ─────────────────────────────────────────────────────────────────────────────

package/browser-extension/artifacts/gno-browser-clipper-v1.38.0.zip.sha256

@@ -1 +0,0 @@
-59f8dc960d1910f7b9dec3c4fea286c46bfe63487a43212fbb8ba61a207753ae  gno-browser-clipper-v1.38.0.zip