flagrm 0.4.1 → 1.0.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
 import path from "node:path";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import pc from "picocolors";
 import { realProbes } from "./adapters/dotnet/setup.js";
 import { acceptBaseline, addNames, assertNoEditsSinceBaseline, baselinePath, baselineSummary, discoverFlag, mergeNames, parseAccept, validateAgentNames, writeBaseline, } from "./core/baseline.js";
@@ -13,14 +13,17 @@ import { blobIds, gitState } from "./core/git.js";
 import { hookRoot, parseHookInput, stopDecision } from "./core/hook.js";
 import { initProject, installRoot, updateProject } from "./core/install.js";
 import { buildInventory } from "./core/inventory.js";
-import { verifyMarkdown } from "./core/markdown.js";
+import { staleMarkdown, verifyMarkdown } from "./core/markdown.js";
 import { assertOwnNames } from "./core/name-owner.js";
 import { packageVersion } from "./core/package.js";
 import { resolveProjects } from "./core/registry.js";
-import { printBaseline, printDoctor, printInventory, printScope, printSteps, printVerifyReport, } from "./core/report.js";
+import { printBaseline, printDoctor, printInventory, printScope, printStale, printSteps, printVerifyReport, } from "./core/report.js";
 import { baselineRuns } from "./core/run-cache.js";
 import { setupReport, writeScope } from "./core/scope.js";
 import { withScopeFiles } from "./core/scope-files.js";
+import { LaunchDarklySource } from "./core/sources/launchdarkly.js";
+import { SourceError } from "./core/sources/types.js";
+import { evaluateStale, needsHistory } from "./core/stale.js";
 import { askTools, detectTools, savedTools, TOOL_LABELS } from "./core/tools.js";
 import { CHECK_IDS } from "./core/types.js";
 import { onPath, relativePath } from "./core/util.js";
@@ -29,8 +32,11 @@ const program = new Command();
 program
     .name("flagrm")
     .description("Guardrails for removing feature flags with an AI coding agent: set up the skills and hook (init, update, " +
-    "doctor), find flags (list), record the state before a removal (baseline) and gate the result (verify).")
-    .version(packageVersion());
+    "doctor), find flags (list) and those LaunchDarkly says are ready to remove (stale), record the state before a " +
+    "removal (baseline) and gate the result (verify).")
+    .version(packageVersion())
+    // Throw instead of exiting, so a usage error commander finds (unknown option, missing argument) exits 2 too.
+    .exitOverride();
 /** Accumulate repeatable options (`--exclude a --exclude b`) into an array. */
 function collect(value, previous) {
     return previous.concat([value]);
@@ -42,8 +48,6 @@ function addGlobOptions(cmd) {
 }
 function addCommonOptions(cmd) {
     return addGlobOptions(cmd
-        .option("--frontend <path>", "path to an Angular project (adds or replaces the project named 'frontend')")
-        .option("--backend <path>", "path to a .NET project (adds or replaces the project named 'backend')")
         .option("--config <path>", "path to a config file (default: the nearest flagrm.config.yaml up to the git repository root)")
         .option("--json", "machine-readable JSON output"));
 }
@@ -206,6 +210,57 @@ addCommonOptions(program
         printInventory(report);
     }
 });
+// --- stale -------------------------------------------------------------------
+addCommonOptions(program
+    .command("stale [flags...]")
+    .description("ask LaunchDarkly (the config's launchdarkly: section, read-only) which flags are ready to remove from code: " +
+    "remove (meets the conditions, in this repository's code), unreferenced (not in this repository) or keep " +
+    "(with reasons); flags are LaunchDarkly keys or code names, default all; " +
+    "exit 0 evaluated, 2 usage error, 3 LaunchDarkly unreachable or refused the request (token, access, project key)"))
+    .option("--md", "print a markdown summary (for a pull request or pipeline summary) instead of text")
+    .action(async (flags, opts) => {
+    if (opts.md && opts.json)
+        fail(new Error("--md and --json can't be combined."));
+    let config;
+    let projects;
+    try {
+        config = loadConfig(opts);
+        projects = resolveProjects(config);
+    }
+    catch (err) {
+        fail(err);
+    }
+    const ld = config.launchdarkly;
+    if (!ld) {
+        fail(new Error(`No launchdarkly: section in ${config.file ?? "the config"}. Add one with your LaunchDarkly project key:\n` +
+            "  launchdarkly:\n    project: <project key>\n" +
+            "and set LD_API_TOKEN to an API token (reader role is enough). See the README's LaunchDarkly section."));
+    }
+    // Checked before any request: nothing goes out without a token.
+    const token = process.env[ld.tokenEnv]?.trim();
+    if (!token)
+        fail(new Error(`${ld.tokenEnv} is not set: set it to a LaunchDarkly API token (reader role is enough).`));
+    const codeNames = (await buildInventory(projects)).flags.map((f) => f.flag);
+    let report;
+    try {
+        const read = await new LaunchDarklySource(ld, { token }).read((f) => needsHistory(f, ld, codeNames));
+        report = evaluateStale({ project: ld.project, read, codeNames, config: ld, now: new Date(), only: flags });
+    }
+    catch (err) {
+        if (!(err instanceof SourceError))
+            fail(err);
+        console.error(pc.red(err.message));
+        process.exitCode = 3;
+        return;
+    }
+    if (opts.json)
+        console.log(JSON.stringify(report, null, 2));
+    else if (opts.md)
+        process.stdout.write(`${staleMarkdown(report)}\n`);
+    else
+        printStale(report);
+    process.exitCode = 0;
+});
 // --- hook --------------------------------------------------------------------
 const hook = program.command("hook").description("entry points for agent hooks (installed by flagrm init)");
 hook
@@ -327,9 +382,18 @@ addCommonOptions(program
     process.exitCode = missing ? 1 : 0;
 });
 // exitCode, not exit(): exit() can cut off output still being flushed to a pipe.
-program.parseAsync().catch((err) => {
-    if (!(err instanceof CliError))
+try {
+    await program.parseAsync();
+}
+catch (err) {
+    if (err instanceof CommanderError) {
+        // Commander printed the message already; --help and --version end with 0.
+        process.exitCode = err.exitCode === 0 ? 0 : 2;
+    }
+    else if (err instanceof CliError) {
+        console.error(pc.red(err.message));
+        process.exitCode = 2;
+    }
+    else
         throw err;
-    console.error(pc.red(err.message));
-    process.exitCode = 2;
-});
+}

package/dist/core/change-filter.js

@@ -9,7 +9,10 @@ import picomatch from "picomatch";
 import { CONFIG_FILENAMES, loadConfig } from "./config.js";
 import { AGENT_SKILL_DIRS, SKILLS } from "./install.js";
 import { relativePath } from "./util.js";
-/** The files `flagrm init`, `update` and `scope --write` write, relative to the config root. */
+/**
+ * The files `flagrm init`, `update` and `scope --write` write, relative to the
+ * config root.
+ */
 export const SETUP_PATTERNS = [
     ...CONFIG_FILENAMES,
     ".gitignore",

package/dist/core/config-snapshot.js

@@ -193,10 +193,6 @@ function withoutCommands(text) {
         delete config.tools;
         if (Array.isArray(config.projects))
             config.projects = config.projects.map(strip);
-        for (const legacy of ["frontend", "backend"]) {
-            if (config[legacy] && typeof config[legacy] === "object")
-                config[legacy] = strip(config[legacy]);
-        }
         return JSON.stringify(config);
     }
     return JSON.stringify(parsed);

package/dist/core/config.js

@@ -19,6 +19,8 @@ export function parseTools(value, where = "tools") {
     }
     return TOOL_IDS.filter((t) => tools.includes(t));
 }
+export const DEFAULT_LAUNCHDARKLY_BASE_URL = "https://app.launchdarkly.com";
+export const DEFAULT_LAUNCHDARKLY_TOKEN_ENV = "LD_API_TOKEN";
 export const DEFAULT_FRONTEND_METHODS = ["isEnabled", "isFeatureEnabled", "hasFeature", "getFlag", "isOn"];
 export const DEFAULT_BACKEND_METHODS = [
     "IsEnabledAsync",
@@ -31,16 +33,16 @@ export const DEFAULT_BACKEND_METHODS = [
 export const DEFAULT_BACKEND_ATTRIBUTES = ["FeatureGate", "Feature"];
 export const CONFIG_FILENAMES = ["flagrm.config.yaml", "flagrm.config.yml", "flagrm.config.json"];
 /** Known top-level `flagrm.config.yaml` keys — anything else is likely a typo. */
-const KNOWN_CONFIG_KEYS = [
-    "projects",
-    "tools",
-    "frontend",
-    "backend",
-    "frontendMethods",
-    "backendMethods",
-    "backendAttributes",
-    "exclude",
-    "include",
+const KNOWN_CONFIG_KEYS = ["projects", "tools", "exclude", "include", "launchdarkly"];
+const KNOWN_LAUNCHDARKLY_KEYS = [
+    "project",
+    "baseUrl",
+    "tokenEnv",
+    "environments",
+    "minDaysOn",
+    "temporaryOnly",
+    "tags",
+    "map",
 ];
 const KNOWN_PROJECT_KEYS = [
     "name",
@@ -56,6 +58,14 @@ const KNOWN_PROJECT_KEYS = [
     "methods",
     "attributes",
 ];
+/** Top-level keys removed in 1.0, with what replaces them. */
+const REMOVED_CONFIG_KEYS = {
+    frontend: "a `projects:` entry with `adapter: angular`",
+    backend: "a `projects:` entry with `adapter: dotnet`",
+    frontendMethods: "`methods:` on the angular project",
+    backendMethods: "`methods:` on the dotnet project",
+    backendAttributes: "`attributes:` on the dotnet project",
+};
 const PROJECT_NAME = /^[A-Za-z0-9][\w.-]*$/;
 function readConfigFile(configPath) {
     const raw = fs.readFileSync(configPath, "utf8");
@@ -64,10 +74,12 @@ function readConfigFile(configPath) {
         throw new Error(`Config file ${configPath} does not contain an object.`);
     }
     const file = parsed;
+    for (const [key, replacement] of Object.entries(REMOVED_CONFIG_KEYS)) {
+        if (key in file)
+            throw new Error(`${configPath}: "${key}" was removed in flagrm 1.0; use ${replacement}.`);
+    }
     // Checked here so a YAML string (`exclude: "**/gen/**"`) fails instead of being spread into characters.
-    for (const key of ["frontend", "backend"])
-        optionalString(file[key], key);
-    for (const key of ["frontendMethods", "backendMethods", "backendAttributes", "exclude", "include"]) {
+    for (const key of ["exclude", "include"]) {
         optionalStringList(file[key], key);
     }
     return file;
@@ -155,6 +167,32 @@ function optionalPositiveNumber(value, where) {
     }
     return value;
 }
+function optionalBoolean(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${where} must be true or false.`);
+    return value;
+}
+function optionalPositiveDays(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${where} must be a positive whole number of days.`);
+    }
+    return value;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function optionalStringMap(value, where) {
+    if (value === undefined)
+        return undefined;
+    if (!isObject(value) || !Object.values(value).every((v) => typeof v === "string" && v.trim())) {
+        throw new Error(`${where} must map LaunchDarkly keys to code names (strings).`);
+    }
+    return value;
+}
 function optionalStringList(value, where) {
     if (value === undefined)
         return undefined;
@@ -163,18 +201,71 @@ function optionalStringList(value, where) {
     }
     return value;
 }
-/** Per-adapter defaults for `methods`/`attributes`; the legacy top-level keys override the built-ins. */
-function adapterDefaults(adapter, file) {
-    const frontend = file.frontendMethods?.length ? file.frontendMethods : DEFAULT_FRONTEND_METHODS;
-    const backend = file.backendMethods?.length ? file.backendMethods : DEFAULT_BACKEND_METHODS;
-    const attributes = file.backendAttributes?.length ? file.backendAttributes : DEFAULT_BACKEND_ATTRIBUTES;
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** The `launchdarkly:` section with defaults applied; undefined when absent. */
+function parseLaunchDarkly(raw, quiet = false) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    const where = "launchdarkly";
+    if (!isObject(raw))
+        throw new Error(`${where} must be an object with at least a "project".`);
+    for (const key of ["token", "apiKey"]) {
+        if (key in raw) {
+            throw new Error(`${where}.${key}: never put the API token in the config file. Remove it and set the environment ` +
+                `variable named by ${where}.tokenEnv (default ${DEFAULT_LAUNCHDARKLY_TOKEN_ENV}) instead.`);
+        }
+    }
+    if (!quiet)
+        warnOnUnknownKeys(raw, KNOWN_LAUNCHDARKLY_KEYS, `"${where}"`);
+    const project = optionalString(raw.project, `${where}.project`);
+    if (!project)
+        throw new Error(`${where}.project is required: the LaunchDarkly project key.`);
+    const baseUrl = (optionalString(raw.baseUrl, `${where}.baseUrl`) ?? DEFAULT_LAUNCHDARKLY_BASE_URL).replace(/\/+$/, "");
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`${where}.baseUrl is not a URL: ${baseUrl}`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname))) {
+        throw new Error(`${where}.baseUrl must use https: the API token is sent to it.`);
+    }
+    if (raw.tags !== undefined && !isObject(raw.tags)) {
+        throw new Error(`${where}.tags must be an object with "include" and/or "exclude" lists.`);
+    }
+    const tags = (raw.tags ?? {});
+    if (!quiet)
+        warnOnUnknownKeys(tags, ["include", "exclude"], `"${where}.tags"`);
+    const environments = optionalStringList(raw.environments, `${where}.environments`);
+    if (environments?.length === 0)
+        throw new Error(`${where}.environments must name at least one environment.`);
+    return {
+        project,
+        baseUrl,
+        tokenEnv: optionalString(raw.tokenEnv, `${where}.tokenEnv`) ?? DEFAULT_LAUNCHDARKLY_TOKEN_ENV,
+        ...(environments ? { environments } : {}),
+        minDaysOn: optionalPositiveDays(raw.minDaysOn, `${where}.minDaysOn`) ?? 30,
+        temporaryOnly: optionalBoolean(raw.temporaryOnly, `${where}.temporaryOnly`) ?? true,
+        tags: {
+            include: optionalStringList(tags.include, `${where}.tags.include`) ?? [],
+            exclude: optionalStringList(tags.exclude, `${where}.tags.exclude`) ?? [],
+        },
+        map: optionalStringMap(raw.map, `${where}.map`) ?? {},
+    };
+}
+/** Per-adapter defaults for `methods`/`attributes`. */
+function adapterDefaults(adapter) {
     if (adapter === "angular")
-        return { methods: frontend, attributes: [] };
+        return { methods: DEFAULT_FRONTEND_METHODS, attributes: [] };
     if (adapter === "dotnet")
-        return { methods: backend, attributes };
-    return { methods: [...new Set([...frontend, ...backend])], attributes };
+        return { methods: DEFAULT_BACKEND_METHODS, attributes: DEFAULT_BACKEND_ATTRIBUTES };
+    return {
+        methods: [...new Set([...DEFAULT_FRONTEND_METHODS, ...DEFAULT_BACKEND_METHODS])],
+        attributes: DEFAULT_BACKEND_ATTRIBUTES,
+    };
 }
-function parseProject(raw, index, file, fileDir, quiet = false) {
+function parseProject(raw, index, fileDir, quiet = false) {
     const where = `projects[${index}]`;
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error(`${where} must be an object with name, adapter and path.`);
@@ -194,7 +285,7 @@ function parseProject(raw, index, file, fileDir, quiet = false) {
     const adapter = p.adapter;
     if (typeof p.path !== "string" || !p.path)
         throw new Error(`${where} ("${name}") is missing a "path".`);
-    const defaults = adapterDefaults(adapter, file);
+    const defaults = adapterDefaults(adapter);
     const testResults = optionalString(p.testResults, `${where}.testResults`);
     const project = {
         name,
@@ -220,10 +311,7 @@ function parseProject(raw, index, file, fileDir, quiet = false) {
 /**
  * Merge CLI options with an optional config file and validate everything.
  *
- * Projects come from `projects:` plus the legacy `frontend:`/`backend:` keys,
- * which become an `angular` project named `frontend` and a `dotnet` project
- * named `backend`. `--frontend`/`--backend` on the CLI replace the project of
- * that name (or add it).
+ * Projects come from the config file's `projects:` list.
  */
 export function loadConfig(cli, cwd = process.cwd()) {
     let file = {};
@@ -242,44 +330,18 @@ export function loadConfig(cli, cwd = process.cwd()) {
     if (file.projects !== undefined && !Array.isArray(file.projects)) {
         throw new Error(`"projects" must be a list of { name, adapter, path } entries.`);
     }
-    const projects = (file.projects ?? []).map((raw, i) => parseProject(raw, i, file, fileDir, cli.quiet));
-    const legacyProject = (name, adapter, dir) => ({
-        name,
-        adapter,
-        path: dir,
-        ...adapterDefaults(adapter, file),
-    });
-    if (file.frontend) {
-        projects.push(legacyProject("frontend", "angular", resolveProjectDir(fileDir, file.frontend, "Frontend")));
-    }
-    if (file.backend) {
-        projects.push(legacyProject("backend", "dotnet", resolveProjectDir(fileDir, file.backend, "Backend")));
-    }
+    const projects = (file.projects ?? []).map((raw, i) => parseProject(raw, i, fileDir, cli.quiet));
     const seen = new Set();
     for (const p of projects) {
         if (seen.has(p.name))
             throw new Error(`Duplicate project name "${p.name}" in ${configPath ?? "config"}.`);
         seen.add(p.name);
     }
-    // CLI shortcuts replace a same-named project (keeping its position) or append one.
-    for (const [name, adapter, raw] of [
-        ["frontend", "angular", cli.frontend],
-        ["backend", "dotnet", cli.backend],
-    ]) {
-        if (!raw)
-            continue;
-        const label = name === "frontend" ? "Frontend" : "Backend";
-        const project = legacyProject(name, adapter, resolveProjectDir(cwd, raw, label));
-        const existing = projects.findIndex((p) => p.name === name);
-        if (existing === -1)
-            projects.push(project);
-        else
-            projects[existing] = project;
-    }
     if (projects.length === 0) {
-        throw new Error("No projects configured. Add a `projects:` list to flagrm.config.yaml, or pass --frontend and/or --backend.");
+        throw new Error("No projects configured. Add a `projects:` list to flagrm.config.yaml (`flagrm init` writes one).");
     }
     const tools = parseTools(file.tools);
+    const launchdarkly = parseLaunchDarkly(file.launchdarkly, cli.quiet);
     return {
         root: fileDir,
         file: configPath && fs.existsSync(configPath) ? configPath : undefined,
@@ -287,5 +349,6 @@ export function loadConfig(cli, cwd = process.cwd()) {
         projects,
         exclude: [...(file.exclude ?? []), ...(cli.exclude ?? [])],
         include: [...(file.include ?? []), ...(cli.include ?? [])],
+        ...(launchdarkly ? { launchdarkly } : {}),
     };
 }

package/dist/core/discover.js

@@ -4,7 +4,7 @@
  * This is a UX aid: false negatives (a flag it misses) are fine — the agent
  * can still remove a flag by name. False positives are mildly annoying but
  * harmless since nothing is written. So the heuristics here are intentionally
- * simpler/looser than the scan code path.
+ * loose.
  */
 import path from "node:path";
 import { computeCodeMask, computeCommentMask, computeLexicalMask, escapeRegExp, LEX_COMMENT, LEX_STRING, methodNamePattern, } from "./scan.js";

package/dist/core/doctor.js

@@ -97,6 +97,14 @@ async function configChecks(cwd, configFile, options, add) {
         const config = loadConfig({ config: configFile }, cwd);
         root = config.root;
         projects = resolveProjects(config);
+        // Only `flagrm stale` needs the token, so a missing one warns: removals without LaunchDarkly still work.
+        // No request is made: doctor stays offline.
+        const ld = config.launchdarkly;
+        if (ld && !(options.env ?? process.env)[ld.tokenEnv]?.trim()) {
+            add("warn", `launchdarkly: ${ld.tokenEnv} is not set — flagrm stale can't read project "${ld.project}"`);
+        }
+        else if (ld)
+            add("ok", `launchdarkly: project "${ld.project}", token from ${ld.tokenEnv}`);
     }
     catch (err) {
         add("fail", `config: ${err instanceof Error ? err.message : String(err)}`);

package/dist/core/install.js

@@ -4,7 +4,7 @@
  * files: for Claude Code the skills and the Stop hook, for GitHub Copilot the
  * skills and `/flagrm-*` prompt files, for Codex the skills and the AGENTS.md
  * pointer. Every step reports what it did; nothing the user wrote is
- * overwritten, and nothing is deleted.
+ * overwritten or deleted.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -14,7 +14,7 @@ import { packageRoot, packageVersion } from "./package.js";
 import { runnerTestCommands, testResultsHint } from "./test-runner.js";
 import { saveTools } from "./tools.js";
 import { relativePath } from "./util.js";
-export const SKILLS = ["flagrm-remove", "flagrm-verify"];
+export const SKILLS = ["flagrm-remove", "flagrm-review"];
 /** Where each supported tool discovers repository skills. */
 export const TOOL_SKILL_DIRS = {
     "claude-code": ".claude/skills",
@@ -23,7 +23,7 @@ export const TOOL_SKILL_DIRS = {
 };
 /** Every tool's skills directory: Claude Code, GitHub Copilot, Codex. */
 export const AGENT_SKILL_DIRS = TOOL_IDS.map((t) => TOOL_SKILL_DIRS[t]);
-/** GitHub Copilot prompt files: `/flagrm-remove` and `/flagrm-verify` in Copilot Chat, each pointing at its skill. */
+/** GitHub Copilot prompt files: `/flagrm-remove` and `/flagrm-review` in Copilot Chat, each pointing at its skill. */
 export const PROMPT_FILES = {
     "flagrm-remove": [
         "---",
@@ -35,21 +35,21 @@ export const PROMPT_FILES = {
         "Follow `.github/skills/flagrm-remove/SKILL.md` to remove the feature flags named after this command.",
         "",
     ].join("\n"),
-    "flagrm-verify": [
+    "flagrm-review": [
         "---",
-        "description: Check a feature flag removal with flagrm and propose its commit message",
+        "description: Review a feature flag removal in a fresh session (flagrm verify, then the ON path and deleted tests)",
         "argument-hint: <flag>",
         "agent: agent",
         "---",
         "",
-        "Follow `.github/skills/flagrm-verify/SKILL.md` for the feature flag named after this command.",
+        "Follow `.github/skills/flagrm-review/SKILL.md` for the feature flag named after this command.",
         "",
     ].join("\n"),
 };
 /**
  * The Stop hook command. npx runs the project's own flagrm (a dev dependency)
- * and falls back to a global install. `--no-install` matters: the `flagrm` name
- * on npm belongs to an unrelated package, and a hook must never download code.
+ * and falls back to a global install. `--no-install` matters: a hook must never
+ * download code, so without a local or global flagrm it does nothing.
  * No redirects or `||`: Claude Code runs hooks in PowerShell on Windows
  * without Git Bash, so the command must parse in both shells.
  */
@@ -62,8 +62,8 @@ export const AGENTS_BLOCK = [
     AGENTS_START,
     "## Feature flag removal (flagrm)",
     "",
-    "To remove one or more feature flags, follow `.agents/skills/flagrm-remove/SKILL.md`. To check a removal",
-    "later, follow `.agents/skills/flagrm-verify/SKILL.md`.",
+    "To remove one or more feature flags, follow `.agents/skills/flagrm-remove/SKILL.md`. To review a removal",
+    "in a new session, follow `.agents/skills/flagrm-review/SKILL.md`.",
     AGENTS_END,
 ].join("\n");
 const CONFIG_HEADER = [
@@ -193,11 +193,12 @@ export function installedSkillVersion(skillDir) {
         return undefined;
     }
 }
-/** GitHub Copilot's `/flagrm-remove` and `/flagrm-verify` prompt files in `.github/prompts/`. */
+/** GitHub Copilot's `/flagrm-remove` and `/flagrm-review` prompt files in `.github/prompts/`. */
 export function installPrompts(cwd, mode) {
     const results = [];
+    const prompt = (skill) => path.join(cwd, ".github", "prompts", `${skill}.prompt.md`);
     for (const skill of SKILLS) {
-        const file = path.join(cwd, ".github", "prompts", `${skill}.prompt.md`);
+        const file = prompt(skill);
         const step = relativePath(cwd, file);
         const exists = fs.existsSync(file);
         if (mode === "init" && exists) {
@@ -372,7 +373,10 @@ export function initProject(root, tools = TOOL_IDS) {
         ...deselectedSteps(root, tools),
     ];
 }
-/** `flagrm update`: refresh what `init` installed in `root` for `tools` from this flagrm version; adds nothing new. */
+/**
+ * `flagrm update`: refresh what `init` installed in `root` for `tools` from this
+ * flagrm version. Adds nothing new, except the replacement of a renamed skill it deletes.
+ */
 export function updateProject(root, tools = TOOL_IDS) {
     return [...tools.flatMap((t) => toolSteps(root, t, "update")), ...deselectedSteps(root, tools)];
 }

package/dist/core/markdown.js

@@ -68,3 +68,60 @@ export function verifyMarkdown(report, root) {
     }
     return `${out.join("\n")}\n`;
 }
+/** One environment in a few words: `production true 45d`, `staging targeted (1 rule(s))`. */
+export function staleEnvironmentText(e) {
+    if (e.serves === "targeted")
+        return `${e.environment} targeted (${e.detail})`;
+    const days = e.days === undefined ? "" : ` ${e.days}d${e.sinceSource === "lastModified" ? "*" : ""}`;
+    return `${e.environment} ${JSON.stringify(e.value)}${days}`;
+}
+/** The conditions a report applied, in one line. */
+export function staleConditionsText(report) {
+    const c = report.conditions;
+    const parts = [
+        `boolean, true in ${c.environments.join(", ") || "no environment"} for ${c.minDaysOn}+ days`,
+        ...(c.temporaryOnly ? ["temporary"] : []),
+        ...(c.tags.include.length ? [`tags ${c.tags.include.join(", ")}`] : []),
+        ...(c.tags.exclude.length ? [`not tagged ${c.tags.exclude.join(", ")}`] : []),
+    ];
+    return parts.join("; ");
+}
+const STALE_TITLES = {
+    remove: "Ready to remove",
+    keep: "Keep",
+    unreferenced: "Not referenced in this repository",
+};
+/** `flagrm stale --md`: the flags per verdict, for a pull request or a pipeline summary. */
+export function staleMarkdown(report) {
+    const count = (v) => report.flags.filter((f) => f.verdict === v).length;
+    const out = [
+        `### flagrm stale: ${report.project} — ${count("remove")} ready to remove`,
+        "",
+        `_Conditions: ${staleConditionsText(report)}. Evaluated ${report.evaluatedAt}._`,
+    ];
+    const cell = (text) => text.replace(/\|/g, "\\|");
+    for (const verdict of ["remove", "keep"]) {
+        const flags = report.flags.filter((f) => f.verdict === verdict);
+        if (!flags.length)
+            continue;
+        const columns = ["Flag", "Code name", "Environments", ...(verdict === "keep" ? ["Reasons"] : [])];
+        out.push("", `**${STALE_TITLES[verdict]} (${flags.length})**`, "", `| ${columns.join(" | ")} |`, `|${"---|".repeat(columns.length)}`);
+        for (const f of flags) {
+            const cells = [
+                f.key ? `\`${f.key}\`` : "—",
+                f.codeName ? `\`${f.codeName}\`` : "—",
+                cell(f.environments.map(staleEnvironmentText).join(", ") || "—"),
+                ...(verdict === "keep" ? [cell(f.reasons.join("; "))] : []),
+            ];
+            out.push(`| ${cells.join(" | ")} |`);
+        }
+    }
+    const unreferenced = report.flags.filter((f) => f.verdict === "unreferenced").map((f) => f.key ?? "");
+    if (unreferenced.length) {
+        out.push("", `**${STALE_TITLES.unreferenced} (${unreferenced.length}):** ${codeList(unreferenced)}`, "", "_Another repository may still read these; flagrm doesn't recommend archiving them._");
+    }
+    if (report.flags.some((f) => f.environments.some((e) => e.sinceSource === "lastModified"))) {
+        out.push("", "_\\* days since the environment last changed: the audit log had no targeting change to date._");
+    }
+    return out.join("\n");
+}

package/dist/core/report.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { staleConditionsText, staleEnvironmentText } from "./markdown.js";
 import { reusedNote } from "./run-cache.js";
 import { plural, relativePath } from "./util.js";
 /** A path relative to the working directory, with `/` separators on every platform. */
@@ -189,3 +190,31 @@ export function printScope(setups, root, written) {
             console.log(pc.dim("  A solution filter can't help here: install the SDK or change global.json."));
     }
 }
+const STALE_STYLE = {
+    remove: { title: "Ready to remove", color: pc.green },
+    keep: { title: "Keep", color: pc.yellow },
+    unreferenced: { title: "Not referenced in this repository (another may still read them)", color: pc.dim },
+};
+/** `flagrm stale`: the flags grouped by verdict, each with its environments and reasons. */
+export function printStale(report) {
+    console.log(pc.bold(`LaunchDarkly project ${report.project}`) + pc.dim(` — ${staleConditionsText(report)}`));
+    for (const verdict of ["remove", "keep", "unreferenced"]) {
+        const flags = report.flags.filter((f) => f.verdict === verdict);
+        if (!flags.length)
+            continue;
+        const { title, color } = STALE_STYLE[verdict];
+        console.log(`\n${color(pc.bold(`${title} (${flags.length})`))}`);
+        for (const f of flags) {
+            const name = f.key && f.codeName && f.key !== f.codeName ? `${f.key} → ${f.codeName}` : (f.key ?? f.codeName);
+            const envs = f.environments.map(staleEnvironmentText).join(", ");
+            console.log(`  ${name}${envs ? pc.dim(`  ${envs}`) : ""}`);
+            for (const reason of verdict === "unreferenced" ? [] : f.reasons)
+                console.log(pc.dim(`      ${reason}`));
+        }
+    }
+    if (report.flags.length === 0)
+        console.log(pc.dim("\nNo flags."));
+    if (report.flags.some((f) => f.environments.some((e) => e.sinceSource === "lastModified"))) {
+        console.log(pc.dim("\n* days since the environment last changed: the audit log had no targeting change to date."));
+    }
+}