Add --exclude-template-repositories option

Adds a new CLI flag that filters out GitHub template repositories
from search results. Template repos are marked with is_template in
the GitHub API response.

- Add isTemplate: boolean to CodeMatch in types.ts
- Map is_template from GitHub API in api.ts
- Add excludeTemplates param to aggregate() with guard
- Thread excludeTemplates through output.ts (ReplayOptions,
  buildReplayCommand, buildOutput)
- Add excludeTemplates param to runInteractive() in tui.ts
- Register --exclude-template-repositories CLI flag and wire through
  searchAction in github-code-search.ts
- Add shell completion entry in completions.ts
- Add unit tests for the new filter in aggregate.test.ts
- Update docs: filtering.md, cli-options.md, README.md

Closes #116

Author: shouze

README.md

@@ -83,6 +83,14 @@ github-code-search query "useFeatureFlag" --org my-org --group-by-team-prefix pl
 
 Get a team-scoped view of every usage site before refactoring a shared hook or utility.
 
+**Skip template repositories**
+
+```bash
+github-code-search query "TODO" --org my-org --exclude-template-repositories
+```
+
+Exclude repositories that are marked as GitHub templates, so boilerplate repos don't clutter your results.
+
 **Regex search — pattern-based code audit**
 
 ```bash

docs/reference/cli-options.md

@@ -40,6 +40,7 @@ github-code-search completions [--shell <shell>]
 | `--format <format>`                 | `markdown` \| `json`              | ❌       | `markdown`         | Output format. See [Output formats](/usage/output-formats).                                                                                                                                                      |
 | `--output-type <type>`              | `repo-and-matches` \| `repo-only` | ❌       | `repo-and-matches` | Controls output detail level. `repo-only` lists repository names only, without individual extracts.                                                                                                              |
 | `--include-archived`                | boolean (flag)                    | ❌       | `false`            | Include archived repositories in results (excluded by default).                                                                                                                                                  |
+| `--exclude-template-repositories`   | boolean (flag)                    | ❌       | `false`            | Exclude template repositories from results (included by default). See [Filtering](/usage/filtering#--exclude-template-repositories).                                                                             |
 | `--group-by-team-prefix <prefixes>` | string                            | ❌       | `""`               | Comma-separated team-name prefixes for grouping result repos by GitHub team (e.g. `squad-,chapter-`). Requires `read:org` scope.                                                                                 |
 | `--no-cache`                        | boolean (flag)                    | ❌       | `true` (on)        | Bypass the 24 h team-list cache and re-fetch teams from GitHub. Cache is **on** by default; pass this flag to disable it. Only applies with `--group-by-team-prefix`.                                            |
 | `--regex-hint <term>`               | string                            | ❌       | —                  | Override the API search term used when the query is a regex (`/pattern/`). Useful when auto-extraction produces a term that is too broad or too narrow. See [Regex queries](/usage/search-syntax#regex-queries). |

docs/usage/filtering.md

@@ -64,13 +64,26 @@ github-code-search "useFeatureFlag" --org fulll --include-archived
 Archived repos are silently filtered out in the aggregation step before the TUI is shown. This flag overrides that behaviour.
 :::
 
+## `--exclude-template-repositories`
+
+By default, template repositories are included in results. Pass `--exclude-template-repositories` to filter them out:
+
+```bash
+github-code-search "useFeatureFlag" --org fulll --exclude-template-repositories
+```
+
+::: info
+Template repositories (marked as templates on GitHub) are filtered out in the aggregation step before the TUI is shown. Useful when your organisation uses template repos for boilerplate that should not appear in search results.
+:::
+
 ## Combining filters
 
-All three flags can be combined freely:
+All four flags can be combined freely:
 
 ```bash
 github-code-search "useFeatureFlag" --org fulll \
   --include-archived \
+  --exclude-template-repositories \
   --exclude-repositories legacy-monolith \
   --exclude-extracts billing-api:src/flags.ts:0
 ```

github-code-search.ts

@@ -166,6 +166,11 @@ function addSearchOptions(cmd: Command): Command {
       "Include archived repositories in results (default: false)",
       false,
     )
+    .option(
+      "--exclude-template-repositories",
+      "Exclude template repositories from results (default: false)",
+      false,
+    )
     .option(
       "--group-by-team-prefix <prefixes>",
       [
@@ -203,6 +208,7 @@ async function searchAction(
     format: string;
     outputType: string;
     includeArchived: boolean;
+    excludeTemplateRepositories: boolean;
     groupByTeamPrefix: string;
     cache: boolean;
     regexHint?: string;
@@ -219,6 +225,7 @@ async function searchAction(
   const format: OutputFormat = opts.format === "json" ? "json" : "markdown";
   const outputType: OutputType = opts.outputType === "repo-only" ? "repo-only" : "repo-and-matches";
   const includeArchived = Boolean(opts.includeArchived);
+  const excludeTemplates = Boolean(opts.excludeTemplateRepositories);
 
   const excludedRepos = new Set(
     opts.excludeRepositories
@@ -305,6 +312,7 @@ async function searchAction(
     excludedExtractRefs,
     includeArchived,
     regexFilter,
+    excludeTemplates,
   );
 
   // ─── Team-prefix grouping ─────────────────────────────────────────────────
@@ -327,6 +335,7 @@ async function searchAction(
     console.log(
       buildOutput(groups, query, org, excludedRepos, excludedExtractRefs, format, outputType, {
         includeArchived,
+        excludeTemplates,
         groupByTeamPrefix: opts.groupByTeamPrefix,
         regexHint: opts.regexHint,
       }),
@@ -378,6 +387,7 @@ async function searchAction(
       format,
       outputType,
       includeArchived,
+      excludeTemplates,
       opts.groupByTeamPrefix,
       opts.regexHint ?? "",
     );

src/aggregate.test.ts

@@ -40,12 +40,13 @@ describe("extractRef", () => {
 
 // ─── aggregate ───────────────────────────────────────────────────────────────
 
-function makeMatch(repo: string, path: string, archived = false): CodeMatch {
+function makeMatch(repo: string, path: string, archived = false, isTemplate = false): CodeMatch {
   return {
     path,
     repoFullName: repo,
     htmlUrl: `https://github.com/${repo}/blob/main/${path}`,
     archived,
+    isTemplate,
     textMatches: [],
   };
 }
@@ -136,6 +137,26 @@ describe("aggregate", () => {
     const groups = aggregate(matches, new Set(), new Set());
     expect(groups).toHaveLength(0);
   });
+
+  it("excludes template repos when excludeTemplates = true", () => {
+    const matches: CodeMatch[] = [
+      makeMatch("myorg/repoA", "src/a.ts", false, false),
+      makeMatch("myorg/templateRepo", "src/b.ts", false, true),
+    ];
+    const groups = aggregate(matches, new Set(), new Set(), false, null, true);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].repoFullName).toBe("myorg/repoA");
+  });
+
+  it("includes template repos when excludeTemplates = false (default)", () => {
+    const matches: CodeMatch[] = [
+      makeMatch("myorg/repoA", "src/a.ts", false, false),
+      makeMatch("myorg/templateRepo", "src/b.ts", false, true),
+    ];
+    const groups = aggregate(matches, new Set(), new Set());
+    expect(groups).toHaveLength(2);
+    expect(groups.map((g) => g.repoFullName)).toContain("myorg/templateRepo");
+  });
 });
 
 // ─── aggregate with regexFilter ───────────────────────────────────────────────
@@ -146,6 +167,7 @@ function makeMatchWithFragments(repo: string, path: string, fragments: string[])
     repoFullName: repo,
     htmlUrl: `https://github.com/${repo}/blob/main/${path}`,
     archived: false,
+    isTemplate: false,
     textMatches: fragments.map((fragment) => ({ fragment, matches: [] })),
   };
 }

src/aggregate.ts

@@ -85,6 +85,7 @@ export function aggregate(
   excludedExtractRefs: Set<string>,
   includeArchived = false,
   regexFilter?: RegExp | null,
+  excludeTemplates = false,
 ): RepoGroup[] {
   // Compile the global regex once per aggregate() call rather than once per
   // fragment inside recomputeSegments — avoids repeated RegExp construction
@@ -97,6 +98,7 @@ export function aggregate(
   for (const m of matches) {
     if (excludedRepos.has(m.repoFullName)) continue;
     if (!includeArchived && m.archived) continue;
+    if (excludeTemplates && m.isTemplate) continue;
     // Fix: when a regex filter is active, replace each TextMatch's API-provided
     // segments (which point at the literal search term) with segments derived
     // from the actual regex match positions — see issue #111 / fix highlight bug

src/api.ts

@@ -18,7 +18,7 @@ interface RawTextMatch {
 interface RawCodeItem {
   path: string;
   html_url: string;
-  repository: { full_name: string; archived?: boolean };
+  repository: { full_name: string; archived?: boolean; is_template?: boolean };
   text_matches?: RawTextMatch[];
 }
 
@@ -277,6 +277,7 @@ export async function fetchAllResults(
       repoFullName: item.repository.full_name,
       htmlUrl: item.html_url,
       archived: item.repository.archived === true,
+      isTemplate: item.repository.is_template === true,
       textMatches: (item.text_matches ?? []).map((m) => {
         const fragment: string = m.fragment ?? "";
         const fragmentStartLine = fileContent ? computeFragmentStartLine(fileContent, fragment) : 1;

src/completions.ts

@@ -57,6 +57,12 @@ const OPTIONS = [
     takesArg: false,
     values: [],
   },
+  {
+    flag: "exclude-template-repositories",
+    description: "Exclude template repositories",
+    takesArg: false,
+    values: [],
+  },
   {
     flag: "no-cache",
     description: "Bypass the 24 h team-list cache",

src/output.ts

@@ -32,6 +32,7 @@ export interface ReplayOptions {
   format?: OutputFormat;
   outputType?: OutputType;
   includeArchived?: boolean;
+  excludeTemplates?: boolean;
   groupByTeamPrefix?: string;
   /** When set, appends `--regex-hint <term>` to the replay command so the
    *  result set from a regex query can be reproduced exactly. */
@@ -49,7 +50,8 @@ export function buildReplayCommand(
   // Fix: forward all input options so the replay command is fully reproducible — see issue #11
   options: ReplayOptions = {},
 ): string {
-  const { format, outputType, includeArchived, groupByTeamPrefix, regexHint } = options;
+  const { format, outputType, includeArchived, excludeTemplates, groupByTeamPrefix, regexHint } =
+    options;
   const parts: string[] = [`github-code-search ${shellQuote(query)} --org ${org} --no-interactive`];
 
   const excludedReposList: string[] = [...excludedRepos].map((r) => shortRepo(r, org));
@@ -90,6 +92,9 @@ export function buildReplayCommand(
   if (includeArchived) {
     parts.push("--include-archived");
   }
+  if (excludeTemplates) {
+    parts.push("--exclude-template-repositories");
+  }
   if (groupByTeamPrefix) {
     parts.push(`--group-by-team-prefix ${groupByTeamPrefix}`);
   }
@@ -264,7 +269,10 @@ export function buildOutput(
   excludedExtractRefs: Set<string>,
   format: OutputFormat,
   outputType: OutputType = "repo-and-matches",
-  extraOptions: Pick<ReplayOptions, "includeArchived" | "groupByTeamPrefix" | "regexHint"> = {},
+  extraOptions: Pick<
+    ReplayOptions,
+    "includeArchived" | "excludeTemplates" | "groupByTeamPrefix" | "regexHint"
+  > = {},
 ): string {
   const options: ReplayOptions = { format, outputType, ...extraOptions };
   if (format === "json") {

src/tui.ts

@@ -108,6 +108,7 @@ export async function runInteractive(
   format: OutputFormat,
   outputType: OutputType = "repo-and-matches",
   includeArchived = false,
+  excludeTemplates = false,
   groupByTeamPrefix = "",
   regexHint = "",
 ): Promise<void> {
@@ -371,6 +372,7 @@ export async function runInteractive(
       console.log(
         buildOutput(groups, query, org, excludedRepos, excludedExtractRefs, format, outputType, {
           includeArchived,
+          excludeTemplates,
           groupByTeamPrefix,
           regexHint: regexHint || undefined,
         }),