flagrm 0.4.1 → 0.5.0

package/dist/core/change-filter.js

@@ -7,14 +7,17 @@
  */
 import picomatch from "picomatch";
 import { CONFIG_FILENAMES, loadConfig } from "./config.js";
-import { AGENT_SKILL_DIRS, SKILLS } from "./install.js";
+import { AGENT_SKILL_DIRS, LEGACY_SKILLS, 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. Renamed skills count too: `update` deletes them, possibly mid-removal.
+ */
 export const SETUP_PATTERNS = [
     ...CONFIG_FILENAMES,
     ".gitignore",
     ".claude/settings.json",
-    ...AGENT_SKILL_DIRS.flatMap((dir) => SKILLS.map((skill) => `${dir}/${skill}/**`)),
+    ...AGENT_SKILL_DIRS.flatMap((dir) => [...SKILLS, ...Object.keys(LEGACY_SKILLS)].map((skill) => `${dir}/${skill}/**`)),
     ".github/prompts/flagrm-*.prompt.md",
     "AGENTS.md",
     "**/flagrm.slnf",

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",
@@ -41,6 +43,17 @@ const KNOWN_CONFIG_KEYS = [
     "backendAttributes",
     "exclude",
     "include",
+    "launchdarkly",
+];
+const KNOWN_LAUNCHDARKLY_KEYS = [
+    "project",
+    "baseUrl",
+    "tokenEnv",
+    "environments",
+    "minDaysOn",
+    "temporaryOnly",
+    "tags",
+    "map",
 ];
 const KNOWN_PROJECT_KEYS = [
     "name",
@@ -155,6 +168,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,6 +202,59 @@ function optionalStringList(value, where) {
     }
     return value;
 }
+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`; the legacy top-level keys override the built-ins. */
 function adapterDefaults(adapter, file) {
     const frontend = file.frontendMethods?.length ? file.frontendMethods : DEFAULT_FRONTEND_METHODS;
@@ -280,6 +372,7 @@ export function loadConfig(cli, cwd = process.cwd()) {
         throw new Error("No projects configured. Add a `projects:` list to flagrm.config.yaml, or pass --frontend and/or --backend.");
     }
     const tools = parseTools(file.tools);
+    const launchdarkly = parseLaunchDarkly(file.launchdarkly, cli.quiet);
     return {
         root: fileDir,
         file: configPath && fs.existsSync(configPath) ? configPath : undefined,
@@ -287,5 +380,6 @@ export function loadConfig(cli, cwd = process.cwd()) {
         projects,
         exclude: [...(file.exclude ?? []), ...(cli.exclude ?? [])],
         include: [...(file.include ?? []), ...(cli.include ?? [])],
+        ...(launchdarkly ? { launchdarkly } : {}),
     };
 }

package/dist/core/doctor.js

@@ -11,7 +11,7 @@ import { changeFilter, changeFilterAt } from "./change-filter.js";
 import { findConfigFile, loadConfig, TOOL_IDS } from "./config.js";
 import { projectCommands } from "./config-snapshot.js";
 import { gitState, isAncestor } from "./git.js";
-import { installedSkillVersion, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
+import { installedSkillVersion, LEGACY_SKILLS, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
 import { packageVersion } from "./package.js";
 import { resolveProjects } from "./registry.js";
 import { setupReport } from "./scope.js";
@@ -73,6 +73,11 @@ export async function runDoctor(cwd, options = {}) {
         }
         else
             add("ok", `${dir}: skills ${version}`);
+        for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+            if (fs.existsSync(path.join(root, dir, legacy))) {
+                add("warn", `${dir}/${legacy}: replaced by ${skill} (run flagrm update)`);
+            }
+        }
     }
     const hook = tools.includes("claude-code") ? stopHookState(root) : undefined;
     if (hook === "current")
@@ -97,6 +102,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,8 @@
  * 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. The only deletion: `update` replaces a renamed skill that flagrm
+ * installed (see {@link LEGACY_SKILLS}).
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -14,7 +15,13 @@ 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"];
+/**
+ * Skills an earlier flagrm installed under another name, and the skill that
+ * replaces each. `update` deletes the old one (only when flagrm's stamp shows
+ * flagrm wrote it) and installs its replacement; `init` deletes nothing.
+ */
+export const LEGACY_SKILLS = { "flagrm-verify": "flagrm-review" };
 /** Where each supported tool discovers repository skills. */
 export const TOOL_SKILL_DIRS = {
     "claude-code": ".claude/skills",
@@ -23,7 +30,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 +42,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 +69,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 = [
@@ -144,6 +151,28 @@ export function writeConfigTemplate(cwd, tools) {
 export function installSkills(cwd, mode, version = packageVersion(), source = path.join(packageRoot(), "skills"), tools = TOOL_IDS) {
     const results = [];
     for (const dir of tools.map((t) => TOOL_SKILL_DIRS[t])) {
+        const replaced = new Set();
+        for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+            const target = path.join(cwd, dir, legacy);
+            if (!fs.existsSync(target))
+                continue;
+            const step = relativePath(cwd, target);
+            if (mode === "init") {
+                results.push({ path: step, status: "skipped", note: `replaced by ${skill}: run flagrm update to delete it` });
+            }
+            else if (installedSkillVersion(target) === undefined) {
+                results.push({
+                    path: step,
+                    status: "skipped",
+                    note: "no flagrm-version stamp, so not deleted: delete it by hand",
+                });
+            }
+            else {
+                fs.rmSync(target, { recursive: true, force: true });
+                results.push({ path: step, status: "deleted", note: `replaced by ${skill}` });
+                replaced.add(skill);
+            }
+        }
         for (const skill of SKILLS) {
             const target = path.join(cwd, dir, skill);
             const exists = fs.existsSync(target);
@@ -151,7 +180,7 @@ export function installSkills(cwd, mode, version = packageVersion(), source = pa
                 results.push({ path: relativePath(cwd, target), status: "skipped" });
                 continue;
             }
-            if (mode === "update" && !exists)
+            if (mode === "update" && !exists && !replaced.has(skill))
                 continue;
             const before = exists ? snapshot(target) : undefined;
             fs.rmSync(target, { recursive: true, force: true });
@@ -193,18 +222,41 @@ 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`);
+    const replaced = new Set();
+    for (const [legacy, skill] of Object.entries(LEGACY_SKILLS)) {
+        const file = prompt(legacy);
+        if (!fs.existsSync(file))
+            continue;
+        const step = relativePath(cwd, file);
+        if (mode === "init") {
+            results.push({ path: step, status: "skipped", note: `replaced by ${skill}: run flagrm update to delete it` });
+        }
+        else if (!fs.readFileSync(file, "utf8").includes(`.github/skills/${legacy}/SKILL.md`)) {
+            results.push({
+                path: step,
+                status: "skipped",
+                note: `doesn't point at flagrm's ${legacy} skill, so not deleted`,
+            });
+        }
+        else {
+            fs.rmSync(file);
+            results.push({ path: step, status: "deleted", note: `replaced by ${skill}` });
+            replaced.add(skill);
+        }
+    }
     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) {
             results.push({ path: step, status: "skipped" });
             continue;
         }
-        if (mode === "update" && !exists)
+        if (mode === "update" && !exists && !replaced.has(skill))
             continue;
         const before = exists ? fs.readFileSync(file, "utf8") : undefined;
         if (before === PROMPT_FILES[skill]) {
@@ -372,7 +424,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. */
@@ -136,6 +137,7 @@ const STEP_STYLE = {
     updated: pc.green,
     unchanged: pc.dim,
     skipped: pc.dim,
+    deleted: pc.yellow,
 };
 /** One line per `init`/`update` step: `created   .claude/skills/flagrm-remove`. */
 export function printSteps(steps) {
@@ -189,3 +191,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."));
+    }
+}