github-star-lists 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# GitHub Star List Organizer
+
+Organize GitHub starred repositories into GitHub Star Lists. The CLI creates missing lists, classifies starred repositories with configurable rules, writes a dry-run plan first, and can sync list descriptions and visibility.
+
+## Install
+
+Run without installing:
+
+```bash
+npx github-star-lists
+```
+
+Or install globally:
+
+```bash
+npm install -g github-star-lists
+github-star-lists
+```
+
+## Authentication
+
+Use GitHub CLI:
+
+```bash
+gh auth login
+gh auth refresh -h github.com -s user -s repo
+```
+
+Or provide a token:
+
+```bash
+GITHUB_TOKEN=ghp_xxx npx github-star-lists
+```
+
+The token needs the classic `user` scope. Add `repo` if your starred repositories include private repositories.
+
+## Quick Start
+
+Create a local config:
+
+```bash
+npx github-star-lists init
+```
+
+Use the guided flow:
+
+```bash
+npx github-star-lists wizard
+```
+
+The wizard asks you to choose:
+
+- preview or apply
+- public, private, or config-based list visibility
+- whether to use existing lists only
+- whether to sync descriptions
+- whether to sync existing list visibility
+- whether to scan all stars or only the newest N
+
+Preview directly. This does not write to GitHub:
+
+```bash
+npx github-star-lists
+```
+
+Apply changes:
+
+```bash
+npx github-star-lists --apply
+```
+
+Most users should start with `wizard`. The flags below are useful for automation or repeatable workflows.
+
+## Visibility
+
+New lists are public by default. Before applying, the CLI prints lists as `[x] public` or `[x] private` and asks for confirmation.
+
+```bash
+npx github-star-lists --apply
+npx github-star-lists --all-private --apply
+npx github-star-lists --all-public --apply
+```
+
+Sync existing configured lists to the chosen visibility:
+
+```bash
+npx github-star-lists --all-public --sync-list-visibility --apply
+npx github-star-lists --all-private --sync-list-visibility --apply
+```
+
+Skip confirmation in automation:
+
+```bash
+npx github-star-lists --apply --yes
+```
+
+## Common Commands
+
+Scan only the newest 50 stars:
+
+```bash
+npx github-star-lists --limit=50
+```
+
+Use existing lists only:
+
+```bash
+npx github-star-lists --existing-only
+npx github-star-lists --existing-only --apply
+```
+
+Fill empty list descriptions from config:
+
+```bash
+npx github-star-lists --sync-list-descriptions
+npx github-star-lists --sync-list-descriptions --apply
+```
+
+Only sync list metadata without changing repository assignments:
+
+```bash
+npx github-star-lists --sync-list-descriptions --only-list-metadata --apply
+npx github-star-lists --sync-list-visibility --all-public --only-list-metadata --apply
+```
+
+Overwrite existing descriptions:
+
+```bash
+npx github-star-lists --sync-list-descriptions --overwrite-list-descriptions --apply
+```
+
+Hide progress output:
+
+```bash
+npx github-star-lists --quiet
+```
+
+## Configuration
+
+By default the CLI uses the first existing file from:
+
+1. `star-lists.config.json`
+2. `config/star-lists.json`
+3. the packaged default config
+
+Use a specific config:
+
+```bash
+npx github-star-lists --config ./my-star-lists.json
+```
+
+Each list can define:
+
+```json
+{
+  "name": "LLM",
+  "description": "Large language models, RAG, inference, evals, and LLM application tooling.",
+  "isPrivate": false,
+  "keywords": ["llm", "rag", "embedding", "inference"],
+  "topics": ["llm", "rag", "embeddings"]
+}
+```
+
+`--all-private` and `--all-public` override per-list `isPrivate` values.
+
+## How Classification Works
+
+The CLI first checks repository name, description, homepage, primary language, and topics. Repositories that do not meet the score threshold are checked again using their README. README matches are shown in the plan as `readme:<keyword>`.
+
+Existing list assignments are preserved by default. The CLI only adds newly matched lists unless you change `preserveExistingAssignments` in config.
+
+## Output
+
+Dry-run and apply commands write:
+
+```text
+out/plan.md
+out/plan.json
+```
+
+`--existing-only` writes `out/plan-existing-only.md` and `out/plan-existing-only.json`.
+
+`--only-list-metadata` writes `out/plan-list-metadata.md` and `out/plan-list-metadata.json`.
+
+## Local Development
+
+```bash
+npm run check
+npm run plan
+npm run apply
+```

package/config/star-lists.json

@@ -0,0 +1,118 @@
+{
+  "settings": {
+    "defaultPrivate": false,
+    "minScore": 2,
+    "maxListsPerRepo": 3,
+    "preserveExistingAssignments": true
+  },
+  "lists": [
+    {
+      "name": "Agentic Coding",
+      "description": "AI coding agents, code generation, MCP, and developer automation.",
+      "keywords": [
+        "agent", "agentic", "ai coding", "autonomous", "codegen", "coding assistant",
+        "copilot", "cursor", "claude", "codex", "mcp", "multi-agent", "swe", "devin",
+        "software engineering agent", "llm app"
+      ],
+      "topics": ["agents", "ai-agent", "mcp", "code-generation", "coding-agent", "developer-tools"]
+    },
+    {
+      "name": "LLM",
+      "description": "Large language models, RAG, inference, evals, and LLM application tooling.",
+      "keywords": [
+        "llm", "large language model", "language model", "rag", "retrieval",
+        "transformer", "prompt", "embedding", "inference", "ollama", "llama",
+        "vllm", "langchain", "llamaindex", "eval", "chatbot"
+      ],
+      "topics": ["llm", "rag", "transformers", "langchain", "llama", "openai", "chatbot", "embeddings"]
+    },
+    {
+      "name": "Vision",
+      "description": "Computer vision, image generation, video, OCR, and multimodal vision.",
+      "keywords": [
+        "vision", "computer vision", "image", "video", "ocr", "segmentation",
+        "detection", "object detection", "diffusion", "stable diffusion", "multimodal",
+        "vae", "gan", "opencv", "yolo"
+      ],
+      "topics": ["computer-vision", "opencv", "image-processing", "diffusion", "ocr", "yolo", "multimodal"]
+    },
+    {
+      "name": "Quantization",
+      "description": "Model compression, quantization, GGUF, and efficient inference.",
+      "keywords": [
+        "quantization", "quantize", "quantized", "int4", "int8", "fp8", "gguf",
+        "ggml", "awq", "gptq", "bitsandbytes", "compression", "efficient inference"
+      ],
+      "topics": ["quantization", "gguf", "ggml", "model-compression", "inference"]
+    },
+    {
+      "name": "ROS",
+      "description": "ROS, robotics middleware, robot tooling, and autonomy systems.",
+      "keywords": ["ros", "ros2", "robot", "robotics", "navigation2", "nav2", "gazebo", "rviz", "urdf"],
+      "topics": ["ros", "ros2", "robotics", "gazebo", "rviz", "autonomous-robots"]
+    },
+    {
+      "name": "SLAM",
+      "description": "SLAM, localization, mapping, LiDAR, and visual odometry.",
+      "keywords": [
+        "slam", "localization", "mapping", "lidar", "visual odometry", "odometry",
+        "bundle adjustment", "point cloud", "pointcloud", "3d reconstruction"
+      ],
+      "topics": ["slam", "lidar", "mapping", "localization", "point-cloud", "visual-odometry"]
+    },
+    {
+      "name": "Utilities",
+      "description": "Practical CLI, desktop, productivity, and small workflow tools.",
+      "keywords": [
+        "cli", "terminal", "tui", "utility", "tool", "productivity", "workflow",
+        "automation", "desktop", "app", "editor", "viewer", "formatter", "converter"
+      ],
+      "topics": ["cli", "terminal", "tui", "productivity", "developer-tools", "automation"]
+    },
+    {
+      "name": "Frontend",
+      "description": "Frontend frameworks, UI components, design systems, and web apps.",
+      "keywords": [
+        "react", "next.js", "nextjs", "vue", "svelte", "frontend", "ui", "component",
+        "design system", "tailwind", "css", "web app", "vite"
+      ],
+      "topics": ["react", "nextjs", "vue", "svelte", "tailwindcss", "frontend", "ui"]
+    },
+    {
+      "name": "Backend",
+      "description": "APIs, servers, databases, infrastructure services, and backend frameworks.",
+      "keywords": [
+        "api", "backend", "server", "database", "postgres", "sqlite", "redis",
+        "queue", "microservice", "fastapi", "django", "rails", "spring", "nestjs"
+      ],
+      "topics": ["api", "backend", "database", "postgresql", "sqlite", "redis", "server"]
+    },
+    {
+      "name": "DevOps",
+      "description": "Deployment, containers, Kubernetes, CI, observability, and operations.",
+      "keywords": [
+        "docker", "kubernetes", "k8s", "terraform", "ansible", "ci", "cd",
+        "deployment", "observability", "monitoring", "prometheus", "grafana"
+      ],
+      "topics": ["docker", "kubernetes", "terraform", "devops", "ci-cd", "monitoring"]
+    },
+    {
+      "name": "Data",
+      "description": "Data engineering, analytics, notebooks, ETL, and visualization.",
+      "keywords": [
+        "data", "analytics", "etl", "pipeline", "notebook", "pandas", "duckdb",
+        "spark", "visualization", "dashboard", "chart"
+      ],
+      "topics": ["data-engineering", "analytics", "etl", "pandas", "duckdb", "visualization"]
+    },
+    {
+      "name": "Security",
+      "description": "Security tooling, secrets, auth, vulnerability research, and privacy.",
+      "keywords": [
+        "security", "auth", "oauth", "passkey", "secret", "vulnerability",
+        "scanner", "privacy", "encryption", "cryptography", "sso"
+      ],
+      "topics": ["security", "privacy", "oauth", "cryptography", "vulnerability-scanner"]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "github-star-lists",
+  "version": "0.1.0",
+  "description": "Organize GitHub starred repositories into Star Lists with dry-run plans, README fallback classification, and list description sync.",
+  "type": "module",
+  "bin": {
+    "github-star-lists": "scripts/organize-stars.mjs",
+    "gh-star-lists": "scripts/organize-stars.mjs"
+  },
+  "files": [
+    "scripts/",
+    "config/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check scripts/organize-stars.mjs",
+    "plan": "node scripts/organize-stars.mjs",
+    "apply": "node scripts/organize-stars.mjs --apply"
+  },
+  "keywords": [
+    "github",
+    "stars",
+    "starred",
+    "lists",
+    "cli",
+    "graphql"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/organize-stars.mjs

@@ -0,0 +1,940 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_CONFIG_PATH = resolve(PACKAGE_ROOT, "config/star-lists.json");
+
+const command = process.argv[2]?.startsWith("-") ? null : process.argv[2];
+const args = new Set(process.argv.slice(2));
+const configPath = resolveOption("--config") ?? findDefaultConfigPath();
+const outDir = resolve(process.cwd(), resolveOption("--out-dir") ?? "out");
+const apply = args.has("--apply");
+const verbose = args.has("--verbose");
+const quiet = args.has("--quiet");
+const existingOnly = args.has("--existing-only");
+const syncListDescriptions = args.has("--sync-list-descriptions");
+const syncListVisibility = args.has("--sync-list-visibility");
+const overwriteListDescriptions = args.has("--overwrite-list-descriptions");
+const onlyListDescriptions = args.has("--only-list-descriptions");
+const onlyListMetadata = args.has("--only-list-metadata") || onlyListDescriptions;
+const allPrivate = args.has("--all-private");
+const allPublic = args.has("--all-public");
+const yes = args.has("--yes") || args.has("-y");
+const limitArg = process.argv.find((arg) => arg.startsWith("--limit="));
+const limit = limitArg ? Number(limitArg.slice("--limit=".length)) : Infinity;
+
+if (args.has("--help") || args.has("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === "init") {
+  initConfig();
+  process.exit(0);
+}
+
+if (command === "wizard") {
+  const status = await runWizard();
+  process.exit(status);
+}
+
+if (command && !["run", "wizard"].includes(command)) {
+  fail(`Unknown command: ${command}\nRun with --help for usage.`);
+}
+
+if (Number.isNaN(limit) || limit <= 0) {
+  fail("--limit must be a positive number");
+}
+
+if (allPrivate && allPublic) {
+  fail("Choose only one of --all-private or --all-public.");
+}
+
+const config = JSON.parse(readFileSync(configPath, "utf8"));
+const settings = {
+  defaultPrivate: false,
+  minScore: 2,
+  maxListsPerRepo: 3,
+  preserveExistingAssignments: true,
+  readmeFallback: true,
+  readmeMaxChars: 20000,
+  readmeIgnoredKeywords: [
+    "api", "app", "cd", "ci", "css", "data", "image", "prompt", "server",
+    "tool", "ui", "video", "workflow"
+  ],
+  ...config.settings
+};
+
+const token = getToken();
+
+function resolveOption(name) {
+  const equalsArg = process.argv.find((arg) => arg.startsWith(`${name}=`));
+  if (equalsArg) return equalsArg.slice(name.length + 1);
+
+  const index = process.argv.indexOf(name);
+  if (index !== -1) return process.argv[index + 1];
+  return null;
+}
+
+function findDefaultConfigPath() {
+  const candidates = [
+    resolve(process.cwd(), "star-lists.config.json"),
+    resolve(process.cwd(), "config/star-lists.json"),
+    DEFAULT_CONFIG_PATH
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? DEFAULT_CONFIG_PATH;
+}
+
+function initConfig() {
+  const target = resolve(process.cwd(), resolveOption("--config") ?? "star-lists.config.json");
+  if (existsSync(target) && !args.has("--force")) {
+    fail(`${target} already exists. Re-run init with --force to overwrite it.`);
+  }
+  writeFileSync(target, readFileSync(DEFAULT_CONFIG_PATH, "utf8"));
+  console.log(`Wrote ${target}`);
+}
+
+async function runWizard() {
+  if (!process.stdin.isTTY) {
+    fail("Wizard requires an interactive terminal. Use flags directly in non-interactive environments.");
+  }
+
+  const rl = createInterface({ input, output });
+  try {
+    console.log("GitHub Star Lists setup");
+    console.log("");
+
+    const mode = await promptChoice(rl, "What do you want to do?", [
+      ["preview", "Preview a plan only"],
+      ["apply", "Apply star list changes"],
+      ["metadata", "Only sync list descriptions/visibility"]
+    ], "preview");
+
+    const visibility = await promptChoice(rl, "New list visibility?", [
+      ["public", "Public"],
+      ["private", "Private"],
+      ["config", "Use config per list"]
+    ], "public");
+
+    const generatedArgs = [];
+    appendPassthroughOption(generatedArgs, "--config");
+    appendPassthroughOption(generatedArgs, "--out-dir");
+
+    if (mode === "apply" || mode === "metadata") generatedArgs.push("--apply");
+    if (mode === "metadata") generatedArgs.push("--only-list-metadata");
+
+    if (visibility === "public") generatedArgs.push("--all-public");
+    if (visibility === "private") generatedArgs.push("--all-private");
+
+    const useExistingOnly = mode !== "metadata" &&
+      await promptYesNo(rl, "Use existing lists only?", false);
+    if (useExistingOnly) generatedArgs.push("--existing-only");
+
+    const syncDescriptions = await promptYesNo(rl, "Fill empty list descriptions from config?", true);
+    if (syncDescriptions) generatedArgs.push("--sync-list-descriptions");
+
+    const syncVisibility = await promptYesNo(rl, "Also sync existing list visibility?", false);
+    if (syncVisibility) generatedArgs.push("--sync-list-visibility");
+
+    if (mode !== "metadata") {
+      const limitValue = await promptText(rl, "Limit to newest N stars? Leave blank for all", "");
+      if (limitValue.trim()) generatedArgs.push(`--limit=${limitValue.trim()}`);
+    }
+
+    if (args.has("--verbose")) generatedArgs.push("--verbose");
+    if (args.has("--quiet")) generatedArgs.push("--quiet");
+
+    console.log("");
+    console.log("Checklist:");
+    console.log(`  [x] Mode: ${mode === "preview" ? "preview only" : mode === "apply" ? "apply changes" : "metadata only"}`);
+    console.log(`  [x] New list visibility: ${visibility}`);
+    console.log(`  [${useExistingOnly ? "x" : " "}] Existing lists only`);
+    console.log(`  [${syncDescriptions ? "x" : " "}] Sync descriptions`);
+    console.log(`  [${syncVisibility ? "x" : " "}] Sync existing visibility`);
+    console.log("");
+    console.log(`Command: github-star-lists ${generatedArgs.join(" ") || "(preview)"}`);
+    console.log("");
+
+    const shouldRun = await promptYesNo(rl, "Run this now?", true);
+    if (!shouldRun) return 0;
+
+    const scriptPath = fileURLToPath(import.meta.url);
+    const child = spawnSync(process.execPath, [scriptPath, ...generatedArgs], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: "inherit"
+    });
+    return child.status ?? 1;
+  } finally {
+    rl.close();
+  }
+}
+
+function appendPassthroughOption(targetArgs, name) {
+  const value = resolveOption(name);
+  if (!value) return;
+  targetArgs.push(name, value);
+}
+
+async function promptChoice(rl, question, choices, defaultValue) {
+  const defaultIndex = choices.findIndex(([value]) => value === defaultValue);
+  const fallbackIndex = defaultIndex === -1 ? 0 : defaultIndex;
+
+  console.log(question);
+  choices.forEach(([, label], index) => {
+    const checked = index === fallbackIndex ? "x" : " ";
+    console.log(`  ${index + 1}. [${checked}] ${label}`);
+  });
+
+  const answer = await rl.question(`Choose 1-${choices.length} [${fallbackIndex + 1}]: `);
+  const selected = Number(answer.trim() || String(fallbackIndex + 1));
+  if (!Number.isInteger(selected) || selected < 1 || selected > choices.length) {
+    console.log("");
+    console.log(`Using default: ${choices[fallbackIndex][1]}`);
+    console.log("");
+    return choices[fallbackIndex][0];
+  }
+  console.log("");
+  return choices[selected - 1][0];
+}
+
+async function promptYesNo(rl, question, defaultYes) {
+  const answer = await rl.question(`${question} [${defaultYes ? "Y/n" : "y/N"}]: `);
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) return defaultYes;
+  return ["y", "yes"].includes(normalized);
+}
+
+async function promptText(rl, question, defaultValue) {
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  const answer = await rl.question(`${question}${suffix}: `);
+  return answer || defaultValue;
+}
+
+function getToken() {
+  const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (envToken) return envToken;
+
+  try {
+    return execFileSync("gh", ["auth", "token"], { encoding: "utf8" }).trim();
+  } catch {
+    fail("No GitHub token found. Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`.");
+  }
+}
+
+function resolveListPrivacy(listConfig) {
+  if (allPrivate) return true;
+  if (allPublic) return false;
+  return listConfig.isPrivate ?? settings.defaultPrivate;
+}
+
+async function confirmListVisibility({ listsToCreate, listVisibilityUpdates }) {
+  if (yes) return;
+  console.log("");
+  if (listsToCreate.length) {
+    console.log("Lists to create:");
+    for (const list of listsToCreate) {
+      const mark = list.isPrivate ? "[x] private" : "[x] public";
+      console.log(`  ${mark} ${list.name}`);
+    }
+  }
+  if (listVisibilityUpdates.length) {
+    if (listsToCreate.length) console.log("");
+    console.log("Existing list visibility changes:");
+    for (const update of listVisibilityUpdates) {
+      const mark = update.isPrivate ? "[x] private" : "[x] public";
+      console.log(`  ${mark} ${update.name} (${update.from} -> ${update.to})`);
+    }
+  }
+  console.log("");
+  console.log("Default visibility is public. Re-run with --all-private for private, or --all-public for public.");
+
+  if (!process.stdin.isTTY) {
+    fail("Confirmation required before changing list visibility. Re-run with --yes to skip this prompt.");
+  }
+
+  const rl = createInterface({ input, output });
+  const answer = await rl.question("Continue with the visibility shown above? Type yes to continue: ");
+  rl.close();
+
+  if (answer.trim().toLowerCase() !== "yes") {
+    fail("Aborted.");
+  }
+}
+
+function printHelp() {
+  console.log(`GitHub Star List Organizer
+
+Usage:
+  github-star-lists init [--config star-lists.config.json] [--force]
+  github-star-lists wizard
+  github-star-lists [run] [options]
+
+Options:
+  --apply                         Apply changes to GitHub. Without this, only writes a plan.
+  --config <path>                 Classification config path.
+  --out-dir <path>                Plan output directory. Default: out
+  --limit <number>                Scan only the newest N starred repositories.
+  --existing-only                 Do not create missing lists; only use existing lists.
+  --all-public                    Create missing lists as public. This is the default.
+  --all-private                   Create missing lists as private.
+  --sync-list-descriptions        Fill empty list descriptions from config.
+  --sync-list-visibility          Update existing configured lists to the chosen visibility.
+  --only-list-metadata            Only update list descriptions/visibility; do not classify stars.
+  --only-list-descriptions        Alias for --only-list-metadata.
+  --overwrite-list-descriptions   Replace existing descriptions when syncing.
+  --yes, -y                       Skip apply confirmation prompts.
+  --verbose                       Print each updated repository/list.
+  --quiet                         Hide progress output.
+  --help                          Show this help.
+
+Authentication:
+  Use gh auth login, or set GITHUB_TOKEN/GH_TOKEN. The token needs the classic "user" scope.
+`);
+}
+
+async function main() {
+  const progress = createProgress({ quiet });
+  progress.start("Loading viewer lists");
+  const viewer = await graphql(`
+    query {
+      viewer {
+        login
+        id
+        lists(first: 100) {
+          nodes {
+            id
+            name
+            description
+            isPrivate
+            items(first: 100) {
+              nodes {
+                __typename
+                ... on Repository { id nameWithOwner }
+              }
+              pageInfo { hasNextPage endCursor }
+            }
+          }
+        }
+      }
+    }
+  `);
+  progress.done("Loaded viewer lists");
+
+  const listByName = new Map(viewer.viewer.lists.nodes.map((list) => [list.name, list]));
+  const listsToCreate = [];
+  const listDescriptionUpdates = [];
+  const listVisibilityUpdates = [];
+
+  for (const listConfig of config.lists) {
+    const isPrivate = resolveListPrivacy(listConfig);
+    const existingList = listByName.get(listConfig.name);
+    if (existingList) {
+      const wantedDescription = listConfig.description ?? "";
+      const currentDescription = existingList.description ?? "";
+      const shouldUpdateDescription = syncListDescriptions &&
+        wantedDescription &&
+        currentDescription !== wantedDescription &&
+        (overwriteListDescriptions || currentDescription.trim() === "");
+
+      if (shouldUpdateDescription) {
+        listDescriptionUpdates.push({
+          id: existingList.id,
+          name: existingList.name,
+          from: currentDescription,
+          to: wantedDescription
+        });
+      }
+      if (syncListVisibility && existingList.isPrivate !== isPrivate) {
+        listVisibilityUpdates.push({
+          id: existingList.id,
+          name: existingList.name,
+          from: existingList.isPrivate ? "private" : "public",
+          to: isPrivate ? "private" : "public",
+          isPrivate
+        });
+      }
+      continue;
+    }
+    if (onlyListMetadata) continue;
+    if (existingOnly) continue;
+    listsToCreate.push({
+      name: listConfig.name,
+      description: listConfig.description ?? "",
+      isPrivate
+    });
+    if (!apply) {
+      listByName.set(listConfig.name, {
+        id: `DRY_RUN:${listConfig.name}`,
+        name: listConfig.name,
+        description: listConfig.description ?? "",
+        isPrivate
+      });
+      continue;
+    }
+  }
+
+  if (apply && listsToCreate.length) {
+    await confirmListVisibility({ listsToCreate, listVisibilityUpdates: [] });
+    for (const list of listsToCreate) {
+      const created = await graphql(
+        `
+        mutation($input: CreateUserListInput!) {
+          createUserList(input: $input) {
+            list { id name description isPrivate }
+          }
+        }
+        `,
+        {
+          input: {
+            name: list.name,
+            description: list.description,
+            isPrivate: list.isPrivate
+          }
+        }
+      );
+      listByName.set(list.name, created.createUserList.list);
+    }
+  }
+
+  if (onlyListMetadata) {
+    mkdirSync(outDir, { recursive: true });
+    const jsonPath = resolve(outDir, "plan-list-metadata.json");
+    const mdPath = resolve(outDir, "plan-list-metadata.md");
+    writeFileSync(jsonPath, JSON.stringify({
+      apply,
+      onlyListMetadata,
+      listDescriptionUpdates,
+      listVisibilityUpdates,
+      totalStars: 0,
+      changes: [],
+      skipped: [],
+      unchanged: []
+    }, null, 2));
+    writeFileSync(mdPath, renderMarkdown({
+      apply,
+      existingOnly,
+      listsToCreate: [],
+      listDescriptionUpdates,
+      listVisibilityUpdates,
+      stars: [],
+      changes: [],
+      skipped: [],
+      unchanged: []
+    }));
+
+    if (apply) {
+      if (listVisibilityUpdates.length) {
+        await confirmListVisibility({ listsToCreate: [], listVisibilityUpdates });
+      }
+      await applyListDescriptionUpdates(listDescriptionUpdates, progress);
+      await applyListVisibilityUpdates(listVisibilityUpdates, progress);
+    }
+
+    console.log(`${apply ? "Applied" : "Planned"} ${listDescriptionUpdates.length} list description updates and ${listVisibilityUpdates.length} visibility updates.`);
+    console.log(`Wrote ${mdPath}`);
+    console.log(`Wrote ${jsonPath}`);
+    if (!apply) console.log("Run with --apply to update GitHub Star List descriptions.");
+    return;
+  }
+
+  const existingAssignments = await fetchExistingAssignments(viewer.viewer.lists.nodes, progress);
+  const stars = await fetchStars(limit, progress);
+  const changes = [];
+  const skipped = [];
+  const unchanged = [];
+  let readmeChecks = 0;
+  let readmeHits = 0;
+  let processed = 0;
+
+  progress.start(`Classifying stars 0/${stars.length}`);
+  for (const repo of stars) {
+    processed += 1;
+    const allMatches = classify(repo);
+    let matches = thresholdMatches(allMatches);
+    let readme = "";
+    let finalMatches = allMatches;
+
+    if (matches.length === 0 && settings.readmeFallback) {
+      readmeChecks += 1;
+      progress.tick(`Classifying stars ${processed}/${stars.length} | README checks ${readmeChecks}`);
+      readme = await fetchReadme(repo.nameWithOwner);
+      if (readme) readmeHits += 1;
+      if (readme) {
+        finalMatches = classify(repo, readme);
+        matches = thresholdMatches(finalMatches);
+      }
+    }
+
+    if (matches.length === 0) {
+      skipped.push({
+        repo: repo.nameWithOwner,
+        description: repo.description ?? "",
+        language: repo.primaryLanguage?.name ?? "",
+        topics: topicNames(repo),
+        readmeChecked: settings.readmeFallback,
+        readmeFound: Boolean(readme),
+        bestMatches: finalMatches.slice(0, 3)
+      });
+      if (processed % 25 === 0 || processed === stars.length) {
+        progress.tick(`Classifying stars ${processed}/${stars.length} | README checks ${readmeChecks}, found ${readmeHits}`);
+      }
+      continue;
+    }
+
+    const oldIds = existingAssignments.get(repo.id) ?? [];
+    const oldSet = new Set(oldIds);
+    const targetIds = new Set(settings.preserveExistingAssignments ? oldIds : []);
+    const targetNames = [];
+
+    for (const match of matches) {
+      const list = listByName.get(match.name);
+      if (!list) continue;
+      targetIds.add(list.id);
+      targetNames.push({ name: match.name, score: match.score, reasons: match.reasons });
+    }
+
+    const hasNewList = [...targetIds].some((id) => !oldSet.has(id));
+    if (!hasNewList) {
+      unchanged.push({
+        repo: repo.nameWithOwner,
+        matchedLists: targetNames
+      });
+      if (processed % 25 === 0 || processed === stars.length) {
+        progress.tick(`Classifying stars ${processed}/${stars.length} | README checks ${readmeChecks}, found ${readmeHits}`);
+      }
+      continue;
+    }
+
+    changes.push({
+      repo: repo.nameWithOwner,
+      id: repo.id,
+      oldListIds: [...oldSet],
+      targetListIds: [...targetIds],
+      targetLists: targetNames
+    });
+
+    if (processed % 25 === 0 || processed === stars.length) {
+      progress.tick(`Classifying stars ${processed}/${stars.length} | README checks ${readmeChecks}, found ${readmeHits}`);
+    }
+  }
+  progress.done(`Classified ${stars.length} stars | README checks ${readmeChecks}, found ${readmeHits}`);
+
+  mkdirSync(outDir, { recursive: true });
+  const basename = existingOnly ? "plan-existing-only" : "plan";
+  const jsonPath = resolve(outDir, `${basename}.json`);
+  const mdPath = resolve(outDir, `${basename}.md`);
+  writeFileSync(jsonPath, JSON.stringify({ apply, existingOnly, listsToCreate, listDescriptionUpdates, listVisibilityUpdates, totalStars: stars.length, changes, skipped, unchanged }, null, 2));
+  writeFileSync(mdPath, renderMarkdown({ apply, existingOnly, listsToCreate, listDescriptionUpdates, listVisibilityUpdates, stars, changes, skipped, unchanged }));
+
+  if (apply) {
+    if (listVisibilityUpdates.length) {
+      await confirmListVisibility({ listsToCreate: [], listVisibilityUpdates });
+    }
+    if (listDescriptionUpdates.length) {
+      await applyListDescriptionUpdates(listDescriptionUpdates, progress);
+    }
+    if (listVisibilityUpdates.length) {
+      await applyListVisibilityUpdates(listVisibilityUpdates, progress);
+    }
+
+    progress.start(`Applying updates 0/${changes.length}`);
+    for (let index = 0; index < changes.length; index += 1) {
+      const change = changes[index];
+      await graphql(
+        `
+        mutation($input: UpdateUserListsForItemInput!) {
+          updateUserListsForItem(input: $input) {
+            item { __typename ... on Repository { nameWithOwner } }
+          }
+        }
+        `,
+        { input: { itemId: change.id, listIds: change.targetListIds } }
+      );
+      if (verbose) console.log(`updated ${change.repo}`);
+      progress.tick(`Applying updates ${index + 1}/${changes.length}`);
+    }
+    progress.done(`Applied updates ${changes.length}/${changes.length}`);
+  }
+
+  console.log(`${apply ? "Applied" : "Planned"} ${changes.length} repository list updates.`);
+  console.log(`Wrote ${mdPath}`);
+  console.log(`Wrote ${jsonPath}`);
+  if (!apply) console.log("Run with --apply to update GitHub Star Lists.");
+}
+
+async function applyListDescriptionUpdates(updates, progress) {
+  if (!updates.length) return;
+  progress.start(`Updating list descriptions 0/${updates.length}`);
+  for (let index = 0; index < updates.length; index += 1) {
+    const update = updates[index];
+    await graphql(
+      `
+      mutation($input: UpdateUserListInput!) {
+        updateUserList(input: $input) {
+          list { id name description }
+        }
+      }
+      `,
+      { input: { listId: update.id, description: update.to } }
+    );
+    if (verbose) console.log(`updated list description ${update.name}`);
+    progress.tick(`Updating list descriptions ${index + 1}/${updates.length}`);
+  }
+  progress.done(`Updated list descriptions ${updates.length}/${updates.length}`);
+}
+
+async function applyListVisibilityUpdates(updates, progress) {
+  if (!updates.length) return;
+  progress.start(`Updating list visibility 0/${updates.length}`);
+  for (let index = 0; index < updates.length; index += 1) {
+    const update = updates[index];
+    await graphql(
+      `
+      mutation($input: UpdateUserListInput!) {
+        updateUserList(input: $input) {
+          list { id name isPrivate }
+        }
+      }
+      `,
+      { input: { listId: update.id, isPrivate: update.isPrivate } }
+    );
+    if (verbose) console.log(`updated list visibility ${update.name}: ${update.to}`);
+    progress.tick(`Updating list visibility ${index + 1}/${updates.length}`);
+  }
+  progress.done(`Updated list visibility ${updates.length}/${updates.length}`);
+}
+
+async function fetchExistingAssignments(lists, progress) {
+  const assignments = new Map();
+  progress.start(`Scanning existing list assignments 0/${lists.length}`);
+
+  for (let index = 0; index < lists.length; index += 1) {
+    const list = lists[index];
+    let page = list.items;
+    addItems(list.id, page.nodes, assignments);
+
+    while (page.pageInfo.hasNextPage) {
+      const data = await graphql(
+        `
+        query($listId: ID!, $cursor: String) {
+          node(id: $listId) {
+            ... on UserList {
+              items(first: 100, after: $cursor) {
+                nodes {
+                  __typename
+                  ... on Repository { id nameWithOwner }
+                }
+                pageInfo { hasNextPage endCursor }
+              }
+            }
+          }
+        }
+        `,
+        { listId: list.id, cursor: page.pageInfo.endCursor }
+      );
+      page = data.node.items;
+      addItems(list.id, page.nodes, assignments);
+    }
+    progress.tick(`Scanning existing list assignments ${index + 1}/${lists.length}`);
+  }
+  progress.done(`Scanned existing list assignments ${lists.length}/${lists.length}`);
+
+  return assignments;
+}
+
+function addItems(listId, nodes, assignments) {
+  for (const item of nodes ?? []) {
+    if (item.__typename !== "Repository") continue;
+    const ids = assignments.get(item.id) ?? [];
+    ids.push(listId);
+    assignments.set(item.id, ids);
+  }
+}
+
+async function fetchStars(max, progress) {
+  const stars = [];
+  let cursor = null;
+  progress.start("Fetching starred repositories");
+
+  do {
+    const first = Math.min(100, max - stars.length);
+    if (first <= 0) break;
+    const data = await graphql(
+      `
+      query($first: Int!, $cursor: String) {
+        viewer {
+          starredRepositories(first: $first, after: $cursor, orderBy: {field: STARRED_AT, direction: DESC}) {
+            nodes {
+              id
+              name
+              nameWithOwner
+              description
+              homepageUrl
+              primaryLanguage { name }
+              repositoryTopics(first: 30) {
+                nodes { topic { name } }
+              }
+            }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }
+      `,
+      { first, cursor }
+    );
+    stars.push(...data.viewer.starredRepositories.nodes);
+    const total = Number.isFinite(max) ? max : "all";
+    progress.tick(`Fetching starred repositories ${stars.length}/${total}`);
+    cursor = data.viewer.starredRepositories.pageInfo.endCursor;
+    if (!data.viewer.starredRepositories.pageInfo.hasNextPage) break;
+  } while (stars.length < max);
+
+  progress.done(`Fetched ${stars.length} starred repositories`);
+  return stars;
+}
+
+async function fetchReadme(nameWithOwner) {
+  const response = await fetch(`https://api.github.com/repos/${nameWithOwner}/readme`, {
+    headers: {
+      authorization: `bearer ${token}`,
+      accept: "application/vnd.github.raw",
+      "user-agent": "git-star-organizer"
+    }
+  });
+
+  if (response.status === 404) return "";
+  if (!response.ok) return "";
+
+  const text = await response.text();
+  return text.slice(0, settings.readmeMaxChars);
+}
+
+function thresholdMatches(matches) {
+  return matches
+    .filter((match) => match.score >= settings.minScore)
+    .slice(0, settings.maxListsPerRepo);
+}
+
+function classify(repo, extraText = "") {
+  const metadataHaystack = [
+    repo.nameWithOwner,
+    repo.description ?? "",
+    repo.homepageUrl ?? "",
+    repo.primaryLanguage?.name ?? "",
+    ...topicNames(repo)
+  ].join(" ").toLowerCase();
+  const readmeHaystack = extraText.toLowerCase();
+  const topics = new Set(topicNames(repo));
+
+  return config.lists
+    .map((list) => {
+      let score = 0;
+      const reasons = [];
+      const seenReasons = new Set();
+
+      for (const topic of list.topics ?? []) {
+        if (topics.has(topic.toLowerCase())) {
+          score += 3;
+          addReason(reasons, seenReasons, `topic:${topic}`);
+        }
+      }
+
+      for (const keyword of list.keywords ?? []) {
+        const needle = keyword.toLowerCase();
+        if (matchesKeyword(metadataHaystack, needle)) {
+          score += needle.includes(" ") ? 2 : 1;
+          addReason(reasons, seenReasons, `keyword:${keyword}`);
+        }
+
+        if (
+          readmeHaystack &&
+          !settings.readmeIgnoredKeywords.includes(needle) &&
+          matchesKeyword(readmeHaystack, needle)
+        ) {
+          score += needle.includes(" ") ? 2 : 1;
+          addReason(reasons, seenReasons, `readme:${keyword}`);
+        }
+      }
+
+      return { name: list.name, score, reasons };
+    })
+    .filter((match) => match.score > 0)
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+
+function topicNames(repo) {
+  return (repo.repositoryTopics?.nodes ?? []).map((node) => node.topic.name.toLowerCase());
+}
+
+function addReason(reasons, seenReasons, reason) {
+  if (seenReasons.has(reason)) return;
+  seenReasons.add(reason);
+  reasons.push(reason);
+}
+
+function matchesKeyword(haystack, keyword) {
+  const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const startsWithWord = /^[a-z0-9]/i.test(keyword);
+  const endsWithWord = /[a-z0-9]$/i.test(keyword);
+  const prefix = startsWithWord ? "(^|[^a-z0-9])" : "";
+  const suffix = endsWithWord ? "($|[^a-z0-9])" : "";
+  return new RegExp(`${prefix}${escaped}${suffix}`, "i").test(haystack);
+}
+
+function renderMarkdown({ apply, existingOnly, listsToCreate, listDescriptionUpdates, listVisibilityUpdates = [], stars, changes, skipped, unchanged }) {
+  const lines = [
+    `# GitHub Star List ${apply ? "Apply" : "Plan"}`,
+    "",
+    `- Stars scanned: ${stars.length}`,
+    `- Repositories to update: ${changes.length}`,
+    `- Unmatched repositories: ${skipped.length}`,
+    `- Already covered repositories: ${unchanged.length}`,
+    `- Existing lists only: ${existingOnly ? "yes" : "no"}`,
+    `- Lists to create: ${listsToCreate.length ? listsToCreate.map(formatListCreate).join(", ") : "none"}`,
+    `- List descriptions to update: ${listDescriptionUpdates.length}`,
+    `- List visibility changes: ${listVisibilityUpdates.length}`,
+    ""
+  ];
+
+  if (listDescriptionUpdates.length) {
+    lines.push("## List Description Updates");
+    lines.push("");
+    for (const update of listDescriptionUpdates) {
+      lines.push(`### ${update.name}`);
+      if (update.from) lines.push(`- from: ${update.from}`);
+      lines.push(`- to: ${update.to}`);
+      lines.push("");
+    }
+  }
+
+  if (listVisibilityUpdates.length) {
+    lines.push("## List Visibility Changes");
+    lines.push("");
+    for (const update of listVisibilityUpdates) {
+      lines.push(`### ${update.name}`);
+      lines.push(`- from: ${update.from}`);
+      lines.push(`- to: ${update.to}`);
+      lines.push("");
+    }
+  }
+
+  if (changes.length) {
+    lines.push("## Updates");
+    lines.push("");
+
+    for (const change of changes) {
+      lines.push(`### ${change.repo}`);
+      for (const target of change.targetLists) {
+        lines.push(`- ${target.name} (score ${target.score}): ${target.reasons.join(", ")}`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (skipped.length) {
+    lines.push("## Unmatched");
+    lines.push("");
+    for (const item of skipped) {
+      const metadata = [
+        item.language ? `language: ${item.language}` : null,
+        item.topics.length ? `topics: ${item.topics.join(", ")}` : null,
+        item.description ? `description: ${item.description}` : null
+      ].filter(Boolean);
+      lines.push(`### ${item.repo}`);
+      if (metadata.length) lines.push(`- ${metadata.join(" | ")}`);
+      if (item.bestMatches.length) {
+        for (const match of item.bestMatches) {
+          lines.push(`- below threshold: ${match.name} (score ${match.score}): ${match.reasons.join(", ")}`);
+        }
+      } else {
+        lines.push("- no configured keyword/topic matched");
+      }
+      lines.push("");
+    }
+  }
+
+  if (unchanged.length) {
+    lines.push("## Already Covered");
+    lines.push("");
+    for (const item of unchanged) {
+      lines.push(`### ${item.repo}`);
+      for (const match of item.matchedLists) {
+        lines.push(`- ${match.name} (score ${match.score}): ${match.reasons.join(", ")}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatListCreate(list) {
+  if (typeof list === "string") return list;
+  return `${list.name} (${list.isPrivate ? "private" : "public"})`;
+}
+
+async function graphql(query, variables = {}) {
+  const response = await fetch("https://api.github.com/graphql", {
+    method: "POST",
+    headers: {
+      authorization: `bearer ${token}`,
+      "content-type": "application/json",
+      "user-agent": "git-star-organizer"
+    },
+    body: JSON.stringify({ query, variables })
+  });
+
+  const body = await response.json();
+  if (!response.ok || body.errors) {
+    fail(JSON.stringify(body, null, 2));
+  }
+  return body.data;
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function createProgress({ quiet }) {
+  const enabled = !quiet && process.stderr.isTTY;
+  let lastLength = 0;
+
+  function write(message, final = false) {
+    if (!enabled) return;
+    const text = final ? `✓ ${message}` : renderSpinner(message);
+    const padding = " ".repeat(Math.max(0, lastLength - text.length));
+    process.stderr.write(`\r${text}${padding}`);
+    lastLength = text.length;
+    if (final) {
+      process.stderr.write("\n");
+      lastLength = 0;
+    }
+  }
+
+  return {
+    start(message) {
+      write(message);
+    },
+    tick(message) {
+      write(message);
+    },
+    done(message) {
+      write(message, true);
+    }
+  };
+}
+
+function renderSpinner(message) {
+  const frames = ["-", "\\", "|", "/"];
+  const frame = frames[Math.floor(Date.now() / 120) % frames.length];
+  return `${frame} ${message}`;
+}
+
+main().catch((error) => fail(error.stack || error.message));