sweet-search 2.5.2 → 2.5.3

package/scripts/write-claude-rules.js

@@ -0,0 +1,110 @@
+/**
+ * Claude-specific rules file under `.claude/rules/sweet-search.md`, plus the
+ * `@.claude/rules/sweet-search.md` import line in `CLAUDE.md`.
+ *
+ * Plan reference: §4B. The Claude Code memory system loads `.claude/rules/*.md`
+ * only via documented `CLAUDE.md` imports — we never assume auto-loading. The
+ * import is wired by `inject-agent-instructions.js` (which writes the
+ * sweet-search marker block in `CLAUDE.md` containing `@AGENTS.md` plus
+ * `@.claude/rules/sweet-search.md`).
+ *
+ * Lifecycle:
+ *   - init   → writes (or rewrites) `.claude/rules/sweet-search.md`
+ *   - re-init → overwrites idempotently (no diff if content unchanged)
+ *   - uninstall → removes the rules file (the import line in CLAUDE.md is
+ *     stripped by `removeAgentInstructions` in inject-agent-instructions.js)
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const CLAUDE_RULES_REL = '.claude/rules/sweet-search.md';
+
+// Sentinel header so we can recognise "this file is sweet-search-managed"
+// without keeping a separate manifest.
+const SENTINEL = '<!-- generated by `sweet-search init`; edit `AGENTS.md` for the canonical policy -->';
+
+const BODY = `${SENTINEL}
+
+# Sweet Search — Claude-specific rules
+
+These supplement the canonical \`AGENTS.md\` policy with Claude Code surface
+nudges. The canonical decision tree is in \`AGENTS.md\`; this file only
+captures Claude-specific behaviour.
+
+## Tool selection (Claude harness specifics)
+
+- Prefer \`ss-grep\`, \`ss-find\`, \`ss-read\`, \`ss-semantic\` (the sweet-search
+  agent wrappers) over native \`Grep\` / \`Read\` for code-discovery and
+  code-reading tasks. The sweet-search wrappers ship semantic ranking,
+  graph-neighbour expansion, and tight chunk packaging that native tools
+  do not provide.
+- Use native \`Read\` only when the file path AND exact line range are already
+  known from a prior sweet-search call. Bare \`Read\` of a whole file for
+  code-understanding loses the ranked-pack trailer signals.
+- Use native \`Grep\` only for trivial single-token literal lookups in tiny
+  scopes where index startup cost dominates (one file, one pattern). For
+  anything larger, \`ss-grep\` returns ranked + scored hits in the same
+  latency band.
+
+## Honour the response trailer
+
+When sweet-search returns \`sufficient=YES\` plus a \`presentation=full\` top-1
+result, answer immediately. Calling a second sweet-search tool merely to
+"verify" the first answer wastes turns and tokens — see the STOP rules block
+in \`AGENTS.md\` for the full discipline.
+
+## Avoid running sweet-search via Bash when a wrapper exists
+
+The agent wrappers (\`ss-grep\`, etc.) have stable argument shapes and are
+safer than constructing \`bash -lc 'sweet-search grep ...'\` invocations on the
+fly. Bash construction also bypasses any \`PreToolUse\` hint hooks the user has
+installed.
+`;
+
+/**
+ * Write `.claude/rules/sweet-search.md`. Idempotent: re-running with
+ * unchanged content is a no-op (no mtime bump).
+ *
+ * @returns 'created' | 'updated' | 'unchanged'
+ */
+export function writeClaudeRules({ projectRoot } = {}) {
+  if (!projectRoot) throw new TypeError('write-claude-rules: projectRoot is required');
+  const filePath = join(projectRoot, CLAUDE_RULES_REL);
+  if (!existsSync(filePath)) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, BODY);
+    return 'created';
+  }
+  const current = readFileSync(filePath, 'utf8');
+  if (current === BODY) return 'unchanged';
+  // If the existing file is sweet-search-managed (sentinel present), rewrite
+  // it. If a user wrote their own file at this path, leave it alone — they
+  // can opt out by removing the sentinel-tagged version manually.
+  if (!current.startsWith(SENTINEL) && !current.includes(SENTINEL)) {
+    return 'preserved-user-file';
+  }
+  writeFileSync(filePath, BODY);
+  return 'updated';
+}
+
+/**
+ * Remove `.claude/rules/sweet-search.md` if it carries the sweet-search
+ * sentinel. The CLAUDE.md import line is stripped by
+ * `removeAgentInstructions` in `inject-agent-instructions.js`.
+ *
+ * @returns 'removed' | 'not-found' | 'preserved-user-file' | 'dry-run'
+ */
+export function removeClaudeRules({ projectRoot, dryRun = false } = {}) {
+  if (!projectRoot) throw new TypeError('remove-claude-rules: projectRoot is required');
+  const filePath = join(projectRoot, CLAUDE_RULES_REL);
+  if (!existsSync(filePath)) return 'not-found';
+  const text = readFileSync(filePath, 'utf8');
+  if (!text.includes(SENTINEL)) return 'preserved-user-file';
+  if (dryRun) return 'dry-run';
+  unlinkSync(filePath);
+  return 'removed';
+}
+
+// Exposed for tests.
+export const _internal = { BODY, SENTINEL };