flagrm 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -2,10 +2,47 @@
 
 All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
-[Semantic Versioning](https://semver.org/). Before 1.0, a minor version may
+[Semantic Versioning](https://semver.org/); the README's "Versioning" section
+says what a minor release won't break. Before 1.0, a minor version could
 contain breaking changes.
 
-## [Unreleased]
+## [1.0.0] - 2026-11-08
+
+### Added
+
+- README "Versioning" section: from 1.0, commands, options, exit codes,
+  config keys, `--json` output, the `.flagrm/` files, the skill names and the
+  Stop hook command stay compatible within a major version.
+- Releases are staged on npm from a `v*` tag by GitHub Actions, with
+  provenance, and go live only after a maintainer approves them with 2FA.
+
+### Fixed
+
+- A usage error found while parsing the command line (unknown option or
+  command, missing argument) exits 2, as documented, instead of 1, which
+  `verify` uses for a failed removal.
+
+### Removed
+
+- **Breaking:** the `--frontend` and `--backend` options, and the top-level
+  `frontend:`, `backend:`, `frontendMethods:`, `backendMethods:` and
+  `backendAttributes:` config keys. List each project under `projects:`
+  instead, with `methods:` and `attributes:` on the project. A config that
+  still has one of these keys is rejected with a message naming its
+  replacement:
+
+  ```yaml
+  projects:
+    - { name: frontend, adapter: angular, path: ./frontend }
+    - { name: backend, adapter: dotnet, path: ./backend }
+  ```
+
+- **Breaking:** `flagrm update` no longer replaces the `flagrm-verify` skill
+  and prompt file of flagrm 0.4 and earlier, and `doctor` no longer warns
+  about them. Coming from 0.4 or earlier, run `flagrm update` with flagrm 0.5
+  first, or run `flagrm init` (it adds `flagrm-review`) and delete the
+  `flagrm-verify` skill directories and `.github/prompts/flagrm-verify.prompt.md`
+  by hand.
 
 ## [0.5.0] - 2026-10-23
 
@@ -317,6 +354,7 @@ removes the flag through the `flagrm-remove` skill, and flagrm checks the result
   `doctor` warns about an incremental `dotnet build`, which hides existing
   warnings from the dead-code comparison.
 
+[1.0.0]: https://github.com/dino-cosic/flagrm/releases/tag/v1.0.0
 [0.5.0]: https://github.com/dino-cosic/flagrm/releases/tag/v0.5.0
 [0.4.1]: https://github.com/dino-cosic/flagrm/releases/tag/v0.4.1
 [0.4.0]: https://github.com/dino-cosic/flagrm/releases/tag/v0.4.0

package/README.md

@@ -31,8 +31,8 @@ deterministic definition of "done":
 Angular and .NET projects work out of the box. Any other stack works through the
 generic adapter.
 
-> **Status:** flagrm is at version 0.4. Until 1.0, a minor release may contain
-> breaking changes.
+> **Status:** flagrm follows semantic versioning from 1.0. See
+> [Versioning](#versioning) for what a minor release won't break.
 
 ## Quick start
 
@@ -232,9 +232,7 @@ narrower test command makes "no new failures" mean less.
   `flagrm.slnf`, adds it to `.git/info/exclude` and points the project's build
   and test at it. See [When the machine can't build everything](#when-the-machine-cant-build-everything).
 - **`update`**: refreshes files from this flagrm version, for the config's
-  `tools:`. It replaces the `flagrm-verify` skill and prompt file of earlier
-  versions with `flagrm-review`, deleting them only when flagrm installed
-  them.
+  `tools:`.
 - **`list`**: flow names include renamed imports of a flag registry
   (`import { FeatureFlags as AppFeatureFlags }`) and, in Angular, the fields,
   getters, methods and locals holding a flag and a child component's input
@@ -314,7 +312,11 @@ path. `build` and `test` are resolved one at a time:
 | `lint` | Optional lint or type-check command, run like `build` and `test` |
 | `covers` | Globs (relative to `path`) of the files the project's commands check |
 | `timeout` | Seconds after which a build or test command fails, for example a test runner left in watch mode |
+| `globs` | Globs (relative to `path`) of the files to scan for flags, replacing the adapter's default language globs |
+| `methods` | Method names that evaluate a flag (`isEnabled`, `IsEnabledAsync`, ...), replacing the adapter's defaults |
+| `attributes` | .NET attributes that gate code on a flag, replacing the defaults `FeatureGate` and `Feature` |
 | `tools` | The AI coding tools whose files `init` and `update` manage (`claude-code`, `copilot`, `codex`) |
+| `include` | Extra globs (relative to each project's path) to scan, on top of the language globs, such as `**/*.razor.cs` |
 | `exclude` | Paths that don't count as part of a removal |
 
 **`testResults`.** Only files written during the run are read, and every
@@ -455,6 +457,22 @@ flagrm does not coordinate the two: each repository gets its own verdict, the
 agent has to record the flag's name in each (it may differ between UI and
 API), and the order of the two removals is up to you.
 
+## Versioning
+
+flagrm follows [semantic versioning](https://semver.org/). Within 1.x, these
+stay compatible:
+
+- commands, their options and exit codes;
+- `flagrm.config.yaml` keys and their meaning;
+- `--json` output and the `.flagrm/` files: fields may be added, none removed
+  or changed, and a baseline recorded by 1.x is read by every later 1.x;
+- the skill names (`/flagrm-remove`, `/flagrm-review`) and the Stop hook
+  command `init` installs.
+
+Not covered: the text and markdown output, the wording of the skills, and
+detection itself. A minor release may find more flag usages or unused code,
+so a removal that passed `verify` before can fail it after an upgrade.
+
 ## Development
 
 ```sh

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";
@@ -34,7 +34,9 @@ program
     .description("Guardrails for removing feature flags with an AI coding agent: set up the skills and hook (init, update, " +
     "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());
+    .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]);
@@ -46,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"));
 }
@@ -382,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

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

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

@@ -33,18 +33,7 @@ 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",
-    "launchdarkly",
-];
+const KNOWN_CONFIG_KEYS = ["projects", "tools", "exclude", "include", "launchdarkly"];
 const KNOWN_LAUNCHDARKLY_KEYS = [
     "project",
     "baseUrl",
@@ -69,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");
@@ -77,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;
@@ -255,18 +254,18 @@ function parseLaunchDarkly(raw, quiet = false) {
         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;
-    const backend = file.backendMethods?.length ? file.backendMethods : DEFAULT_BACKEND_METHODS;
-    const attributes = file.backendAttributes?.length ? file.backendAttributes : DEFAULT_BACKEND_ATTRIBUTES;
+/** 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.`);
@@ -286,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,
@@ -312,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 = {};
@@ -334,42 +330,15 @@ 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);

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

@@ -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, LEGACY_SKILLS, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
+import { installedSkillVersion, SKILLS, stopHookState, TOOL_SKILL_DIRS } from "./install.js";
 import { packageVersion } from "./package.js";
 import { resolveProjects } from "./registry.js";
 import { setupReport } from "./scope.js";
@@ -73,11 +73,6 @@ 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")

package/dist/core/install.js

@@ -4,8 +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. The only deletion: `update` replaces a renamed skill that flagrm
- * installed (see {@link LEGACY_SKILLS}).
+ * overwritten or deleted.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -16,12 +15,6 @@ import { runnerTestCommands, testResultsHint } from "./test-runner.js";
 import { saveTools } from "./tools.js";
 import { relativePath } from "./util.js";
 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",
@@ -151,28 +144,6 @@ 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);
@@ -180,7 +151,7 @@ export function installSkills(cwd, mode, version = packageVersion(), source = pa
                 results.push({ path: relativePath(cwd, target), status: "skipped" });
                 continue;
             }
-            if (mode === "update" && !exists && !replaced.has(skill))
+            if (mode === "update" && !exists)
                 continue;
             const before = exists ? snapshot(target) : undefined;
             fs.rmSync(target, { recursive: true, force: true });
@@ -226,28 +197,6 @@ export function installedSkillVersion(skillDir) {
 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 = prompt(skill);
         const step = relativePath(cwd, file);
@@ -256,7 +205,7 @@ export function installPrompts(cwd, mode) {
             results.push({ path: step, status: "skipped" });
             continue;
         }
-        if (mode === "update" && !exists && !replaced.has(skill))
+        if (mode === "update" && !exists)
             continue;
         const before = exists ? fs.readFileSync(file, "utf8") : undefined;
         if (before === PROMPT_FILES[skill]) {

package/dist/core/report.js

@@ -137,7 +137,6 @@ 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagrm",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Guardrails for removing feature flags with AI coding agents (Claude Code, Copilot, Codex): skills, a baseline, a verify gate and a Stop hook.",
   "type": "module",
   "license": "Apache-2.0",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/dino-cosic/flagrm.git"
   },
-  "homepage": "https://github.com/dino-cosic/flagrm#readme",
+  "homepage": "https://flagrm.com/",
   "bugs": {
     "url": "https://github.com/dino-cosic/flagrm/issues"
   },