fix: improve error handling, UX, and i18n across CLI and collectors

- Throw on 401/403 in Events API instead of silently returning empty results
- Add retry with backoff for 429 rate limits in Events API
- Fix model validation false-positive (match 'not found' instead of 'model')
- Fix DST cron offset bug by using standard time (Jan 1) for calculation
- Add spinner for token and model validation during setup
- Add permission hint on 403 errors in addFileToRepo
- Throw on 401/403 in Search API, warn on other errors
- Add YAML parse failure advice in LLM error messages
- Warn when Events API 300-event limit is reached
- Add PR fetch failure summary (N of M failed)
- Add urlEncode Handlebars helper for share links
- Fix render --language help text to list all 10 languages
- Display site title without raw \n in CLI summary and README
- Document both fine-grained and classic PAT options in README
- Fix i18n diacritics for French, German, Portuguese, and Spanish
- Add temperature to Anthropic, add maxOutputTokens/temperature to Gemini

Author: unhappychoice

README.md

@@ -16,9 +16,13 @@ Every week, this tool looks at everything you did on GitHub (commits, pull reque
 
 Have these two things ready before running setup:
 
-1. **GitHub fine-grained PAT** with `All repositories` access and these permissions (all Read & Write):
-   `Actions`, `Administration`, `Contents`,  `Pages`, `Secrets`, `Workflows`
-   ([Create one](https://github.com/settings/personal-access-tokens/new))
+1. **GitHub personal access token (PAT)**, either type works:
+
+   - **Fine-grained PAT** (recommended): `All repositories` access with permissions: `Actions`, `Administration`, `Contents`, `Pages`, `Secrets`, `Workflows` (all Read & Write).
+     ([Create one](https://github.com/settings/personal-access-tokens/new))
+   - **Classic PAT**: scopes `repo` and `workflow`.
+     ([Create one](https://github.com/settings/tokens/new?scopes=repo,workflow))
+     Use this if you hit 403 errors with fine-grained tokens (e.g. org policy restrictions).
 
 2. **LLM API key** from any supported provider:
 

src/cli/commands/fetch.ts

@@ -161,7 +161,15 @@ const searchWeeklyPRs = async (
           "User-Agent": "github-weekly-reporter",
         },
       });
-      if (!res.ok) break;
+      if (!res.ok) {
+        if (res.status === 401 || res.status === 403) {
+          throw new Error(
+            `GitHub Search API returned ${res.status}. Check that your token (GH_PAT) is valid.`,
+          );
+        }
+        console.warn(`  Search API error (${res.status}), some PRs may be missing.`);
+        break;
+      }
       const data = (await res.json()) as {
         items: { number: number; pull_request?: { url: string }; repository_url: string }[];
         total_count: number;

src/cli/commands/render.ts

@@ -228,7 +228,7 @@ export const registerRender = (program: Command): void => {
     .option("-o, --output-dir <dir>", "Output directory for HTML (env: OUTPUT_DIR, default: ./output)")
     .option("--base-url <url>", "Base URL for absolute links in OG tags, sitemap, canonical (env: BASE_URL)")
     .option("--site-title <title>", "Site title for nav header (env: SITE_TITLE, default: {username}'s Weekly Reports)")
-    .option("--language <lang>", "Report language: en, ja (env: LANGUAGE, default: en)")
+    .option("--language <lang>", "Report language: en, ja, zh-CN, zh-TW, ko, es, fr, de, pt, ru (env: LANGUAGE, default: en)")
     .option("--timezone <tz>", "IANA timezone (env: TIMEZONE, default: UTC)")
     .option("--date <date>", "Date within the target week (YYYY-MM-DD, default: today)")
     .action(async (opts) => {

src/cli/commands/setup.ts

@@ -8,6 +8,7 @@ import { midnightCronUTC, buildDailyWorkflow, buildWeeklyWorkflow, buildReadme,
 import type { WorkflowOpts } from "./setup/workflows.js";
 import { TIMEZONE_CHOICES, LANGUAGE_CHOICES, MODEL_LIST_URLS } from "./setup/constants.js";
 import { validateModel } from "./setup/validate-model.js";
+import { withSpinner } from "../spinner.js";
 
 // Re-export for tests and external consumers
 export { midnightCronUTC, buildDailyWorkflow, buildWeeklyWorkflow } from "./setup/workflows.js";
@@ -46,8 +47,7 @@ const collectInputs = async (cliRepo?: string): Promise<SetupConfig> => {
     validate: (v) => (v.length > 0 ? true : "Token is required"),
   });
 
-  console.log("\n  Validating token...");
-  const { login } = await validateToken(token);
+  const { login } = await withSpinner("Validating token...", () => validateToken(token));
   console.log(`  Authenticated as ${login}\n`);
 
   // 2. Username
@@ -149,10 +149,9 @@ const collectInputs = async (cliRepo?: string): Promise<SetupConfig> => {
         validate: (v) => (v.length > 0 ? true : "Model name is required"),
       });
 
-      console.log("  Validating model...");
-      const result = await validateModel(llmProvider, llmApiKey, llmModel);
+      const result = await withSpinner("Validating model...", () => validateModel(llmProvider, llmApiKey!, llmModel!));
       if (result.valid) {
-        console.log("  Model OK.\n");
+        console.log("");
         modelValidated = true;
       } else {
         console.log(`  ${result.error}`);
@@ -195,7 +194,7 @@ const run = async (cliRepo?: string): Promise<void> => {
   console.log("\n  ── Setup Summary ─────────────────────────────");
   console.log(`  Repository:    ${fullRepo}`);
   console.log(`  Username:      ${config.username}`);
-  console.log(`  Site title:    ${config.siteTitle}`);
+  console.log(`  Site title:    ${config.siteTitle.replace(/\\n/g, " ")}`);
   console.log(`  Language:      ${config.language}`);
   console.log(`  Timezone:      ${config.timezone}`);
   console.log(`  Schedule:      Daily at midnight (cron: ${cron})`);

src/cli/commands/setup/github-api.ts

@@ -192,7 +192,12 @@ export const addFileToRepo = async (
     ...(sha ? { sha } : {}),
   });
   if (!res.ok) {
-    throw new Error(`Failed to add ${path}: ${res.status}`);
+    const hint = res.status === 403
+      ? "\n\n  Possible causes:" +
+        "\n    - Fine-grained PAT: ensure 'Contents: Read and write' and 'Workflows: Read and write' permissions" +
+        "\n    - Classic PAT: ensure 'repo' and 'workflow' scopes are granted"
+      : "";
+    throw new Error(`Failed to add ${path}: ${res.status}${hint}`);
   }
 };
 

src/cli/commands/setup/validate-model.test.ts

@@ -109,4 +109,14 @@ describe("validateModel", () => {
     expect(result.valid).toBe(false);
     expect(result.error).toContain("API error: 500");
   });
+
+  it("does not false-positive on error body that mentions 'model' without 'not found'", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response('{"error": "The model is currently overloaded"}', { status: 503 }),
+    );
+    const result = await validateModel("openai", "key", "gpt-4");
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain("API error: 503");
+    expect(result.error).not.toContain("not found");
+  });
 });

src/cli/commands/setup/validate-model.ts

@@ -71,8 +71,9 @@ export const validateModel = async (
     if (res.ok) return { valid: true };
 
     const body = await res.text();
-    // 404 or "model not found" means wrong model name
-    if (res.status === 404 || body.toLowerCase().includes("model")) {
+    const lower = body.toLowerCase();
+    // 404 or explicit "not found" in body means wrong model name
+    if (res.status === 404 || lower.includes("not_found") || lower.includes("not found")) {
       return { valid: false, error: `Model "${model}" not found (${res.status})` };
     }
     // Rate limit or other non-model errors are fine (model exists)

src/cli/commands/setup/workflows.ts

@@ -27,12 +27,17 @@ const LLM_API_KEY_INPUT_NAMES: Record<string, string> = {
 // GitHub Actions cron is always UTC, so we calculate the offset.
 
 export const midnightCronUTC = (timezone: string): string => {
-  const now = new Date();
+  // Use Jan 1 (standard time) to avoid DST-dependent offset.
+  // During DST the cron fires ~1h late (e.g. 01:00 local), which is safe
+  // because daily-fetch resolves "yesterday" from the local date.
+  // The opposite (firing 1h early = 23:00 the previous day) would shift
+  // the local date backward and collect the wrong day.
+  const jan1 = new Date(new Date().getFullYear(), 0, 1, 0, 0, 0);
   const utcMidnight = new Date(
-    now.toLocaleString("en-US", { timeZone: "UTC" }),
+    jan1.toLocaleString("en-US", { timeZone: "UTC" }),
   );
   const localMidnight = new Date(
-    now.toLocaleString("en-US", { timeZone: timezone }),
+    jan1.toLocaleString("en-US", { timeZone: timezone }),
   );
   const offsetMinutes = Math.round(
     (utcMidnight.getTime() - localMidnight.getTime()) / 60000,
@@ -151,7 +156,9 @@ export const buildReadme = (opts: {
   timezone: string;
   llmProvider?: LLMProvider;
   llmModel?: string;
-}): string => `# ${opts.siteTitle}
+}): string => {
+  const displayTitle = opts.siteTitle.replace(/\\n/g, " ");
+  return `# ${displayTitle}
 
 Weekly GitHub activity reports for [@${opts.username}](https://github.com/${opts.username}), powered by [github-weekly-reporter](https://github.com/deariary/github-weekly-reporter).
 
@@ -174,7 +181,7 @@ Edit \`.github/workflows/weekly-report.yml\` to change:
 | \`username\` | \`${opts.username}\` | GitHub user to report on |
 | \`language\` | \`${opts.language}\` | Report language (en, ja, zh-CN, zh-TW, ko, es, fr, de, pt, ru) |
 | \`timezone\` | \`${opts.timezone}\` | IANA timezone for date calculations |
-| \`SITE_TITLE\` | \`${opts.siteTitle}\` | Site title in the header and hero |
+| \`SITE_TITLE\` | \`${displayTitle}\` | Site title in the header and hero |
 ${opts.llmProvider ? `| \`llm-provider\` | \`${opts.llmProvider}\` | LLM provider for AI narrative |\n| \`llm-model\` | \`${opts.llmModel}\` | Model name |\n` : ""}
 ## Base URL
 
@@ -208,3 +215,4 @@ Go to [Actions](https://github.com/${opts.repo}/actions), click **Weekly Report*
 
 Supported by [deariary](https://deariary.com)
 `;
+};

src/cli/spinner.ts

@@ -0,0 +1,29 @@
+// Minimal CLI spinner (no external dependencies)
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL = 80;
+
+export const withSpinner = async <T>(message: string, task: () => Promise<T>): Promise<T> => {
+  // Skip animation in non-TTY environments (CI, piped output, tests)
+  if (!process.stderr.isTTY) {
+    process.stderr.write(`  ${message}\n`);
+    return task();
+  }
+
+  let i = 0;
+  const timer = setInterval(() => {
+    const frame = FRAMES[i++ % FRAMES.length];
+    process.stderr.write(`\r  ${frame} ${message}`);
+  }, INTERVAL);
+
+  try {
+    const result = await task();
+    clearInterval(timer);
+    process.stderr.write(`\r  ✔ ${message}\n`);
+    return result;
+  } catch (error) {
+    clearInterval(timer);
+    process.stderr.write(`\r  ✖ ${message}\n`);
+    throw error;
+  }
+};

src/collector/fetch-events.test.ts

@@ -247,11 +247,31 @@ describe("fetchEvents", () => {
     expect(fetchSpy).toHaveBeenCalledTimes(1);
   });
 
-  it("handles API error gracefully", async () => {
+  it("throws on 401 authentication error", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response("", { status: 401, statusText: "Unauthorized" }),
+    );
+
+    await expect(fetchEvents("token", "testuser", range)).rejects.toThrow(
+      /GitHub API returned 401/,
+    );
+  });
+
+  it("throws on 403 forbidden error", async () => {
     vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
       new Response("", { status: 403, statusText: "Forbidden" }),
     );
 
+    await expect(fetchEvents("token", "testuser", range)).rejects.toThrow(
+      /GitHub API returned 403/,
+    );
+  });
+
+  it("handles other API errors gracefully", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response("", { status: 500, statusText: "Internal Server Error" }),
+    );
+
     const result = await fetchEvents("token", "testuser", range);
     expect(result).toEqual([]);
   });