@enrichlayer/el-linear 1.18.1 → 1.19.0

package/README.md

@@ -356,6 +356,27 @@ preferences; those stay in personal config. Example team file:
 Run `el-linear config show` to see the resolved config and confirm which team
 config path is active (`teamConfig` field in the output).
 
+#### Migrating a personal-heavy config
+
+Before the team-config split, members typically carried full local copies of
+`members` / `teams` / `labels` / `statusDefaults` / `teamAliases` — and often
+a deprecated `brand: { name, reject }` key. Once a team config is in place
+those local copies just silently shadow the shared values (and silently
+*diverge* when they drift). To clean it up safely:
+
+```bash
+el-linear config migrate-from-personal           # dry-run — prints the plan per file
+el-linear config migrate-from-personal --apply   # write the slimmed files (with .bak-<ts> backups)
+```
+
+Targets the global personal config + every named profile's `config.json`. For
+each top-level shadowable key, the slim drops it **only** when the local copy
+is a strict subset of team (zero divergence, zero non-trivial personal-only
+entries); otherwise the key is left untouched and the divergence is reported
+in the plan so a human resolves it. The deprecated `brand` key is dropped
+when content-identical to a team `terms[]` entry, or converted to a personal
+`terms[]` entry when it differs (with a warning).
+
 ## Term enforcement (with brand-promotion examples)
 
 The `terms` rules let you keep a list of canonical names and the misspellings

package/dist/commands/config.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { getActiveTeamConfigInfo, getActiveTeamConfigPath, loadConfig, loadLocalConfig, } from "../config/config.js";
-import { resolveActiveProfile } from "../config/paths.js";
+import { planMigration, } from "../config/migrate-from-personal.js";
+import { CONFIG_PATH, isSafeProfileName, PROFILES_DIR, resolveActiveProfile, } from "../config/paths.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { updateConfig } from "./init/shared.js";
 /**
@@ -185,4 +186,166 @@ export function setupConfigCommands(program) {
         fs.writeFileSync(localPath, `${JSON.stringify(updated, null, 2)}\n`, "utf8");
         outputSuccess({ data: updated });
     }));
+    // ── config migrate-from-personal ──────────────────────────────────
+    //
+    // Slim personal/profile configs that duplicate keys the team config now
+    // provides (DEV-4458). The companion pure logic + tests live in
+    // `src/config/migrate-from-personal.ts`. This command just discovers
+    // the target files, reads the active team config, calls planMigration
+    // for each, and on --apply backs up + atomically rewrites them.
+    config
+        .command("migrate-from-personal")
+        .description("Slim personal/profile configs against the active team config — drops duplicated members/teams/labels/statusDefaults/teamAliases entries, and migrates the deprecated 'brand' key to a 'terms[]' entry. Dry-run by default; pass --apply to write.")
+        .option("--apply", "Write the slimmed files (with timestamped .bak-<ts> backups + atomic replace). Default is dry-run — only prints the plan.")
+        .option("--file <path>", "Scope to one file. Default: ~/.config/el-linear/config.json plus every <profiles>/<name>/config.json with a safe name.")
+        .addHelpText("after", `\nThe slim only drops a shadowable top-level key when the personal copy is a strict subset of team (zero divergence and zero non-trivial personal-only entries). Anything that would silently shadow a team value, or carry a personal-only entry team doesn't have, is left untouched and reported in the plan so a human can decide.\n\nThe active team config is never a target — passing --file <team-path> is rejected, and a profile config that happens to coincide with the team path is skipped silently with a warning. The first --apply may re-format JSON to 2-space indent + trailing newline; this is harmless but the .bak-<ts> backup preserves the original byte-for-byte.\n\nUses the currently-active team config for every target. If you have profiles pointing at different team configs, run --file <path> per profile with EL_LINEAR_TEAM_CONFIG set.\n\nExamples:\n  el-linear config migrate-from-personal\n  el-linear config migrate-from-personal --apply\n  el-linear config migrate-from-personal --file ~/.config/el-linear/profiles/foo/config.json --apply`)
+        .action(handleAsyncCommand(async (opts) => {
+        const teamPath = getActiveTeamConfigPath();
+        if (!teamPath) {
+            throw new Error("No active team config found. Set one with `el-linear config team set-path <path>` (or EL_LINEAR_TEAM_CONFIG) before running migrate-from-personal — without a team layer there's nothing to dedupe against.");
+        }
+        let team;
+        try {
+            team = JSON.parse(fs.readFileSync(teamPath, "utf8"));
+        }
+        catch (err) {
+            throw new Error(`Failed to read team config at ${teamPath}: ${err.message}`);
+        }
+        const apply = opts.apply ?? false;
+        const resolvedTeamPath = path.resolve(teamPath);
+        // Self-diff guard: refuse to migrate the team config against itself
+        // (cycle-1 nit). Without this, every shadowable key in team would
+        // classify as "drop" (a key is trivially a subset of itself) and
+        // --apply would gut the team config.
+        if (opts.file &&
+            path.resolve(expandHome(opts.file)) === resolvedTeamPath) {
+            throw new Error(`--file resolves to the active team config (${resolvedTeamPath}). Refusing to migrate the team config against itself.`);
+        }
+        const targetsBeforeFilter = opts.file
+            ? [path.resolve(expandHome(opts.file))]
+            : enumerateMigrationTargets();
+        const targets = [];
+        for (const t of targetsBeforeFilter) {
+            if (path.resolve(t) === resolvedTeamPath) {
+                outputWarning(`Skipping ${t} — it resolves to the active team config; migrating it against itself would erase team-shared keys.`);
+                continue;
+            }
+            targets.push(t);
+        }
+        const results = targets.map((file) => migrateOneFile(file, team, apply));
+        // Forward per-file plan warnings to the standard _warnings envelope
+        // (cycle-1 nit) so scripters reading the stable warning channel see
+        // them without having to inspect each target.
+        for (const r of results) {
+            for (const w of r.warnings)
+                outputWarning(`${r.file}: ${w}`);
+        }
+        // --file <single>: an unreadable / unparseable target is a hard
+        // failure (cycle-1 nit). Default enumeration stays soft so one bad
+        // profile doesn't crash the run for the rest.
+        if (opts.file && results.length === 1 && results[0].error) {
+            throw new Error(results[0].error);
+        }
+        outputSuccess({
+            data: {
+                teamConfigPath: teamPath,
+                applied: apply,
+                targetCount: results.length,
+                targets: results,
+            },
+        });
+    }));
+}
+/**
+ * Enumerate every personal/profile config file the migration tool should
+ * consider by default: the global personal config, plus each profile dir
+ * whose name passes `isSafeProfileName` and whose `config.json` exists.
+ */
+function enumerateMigrationTargets() {
+    const out = [];
+    if (fs.existsSync(CONFIG_PATH))
+        out.push(CONFIG_PATH);
+    if (fs.existsSync(PROFILES_DIR)) {
+        const entries = fs.readdirSync(PROFILES_DIR);
+        for (const name of entries.sort()) {
+            if (!isSafeProfileName(name))
+                continue;
+            const p = path.join(PROFILES_DIR, name, "config.json");
+            if (fs.existsSync(p))
+                out.push(p);
+        }
+    }
+    return out;
+}
+function migrateOneFile(file, team, apply) {
+    let rawText;
+    let personal;
+    try {
+        rawText = fs.readFileSync(file, "utf8");
+        personal = JSON.parse(rawText);
+    }
+    catch (err) {
+        return {
+            file,
+            changed: false,
+            before: { sizeBytes: 0, keys: [] },
+            after: { sizeBytes: 0, keys: [] },
+            keys: [],
+            brand: { status: "absent" },
+            warnings: [],
+            error: `Could not read/parse: ${err.message}`,
+        };
+    }
+    const { slimmed, plan } = planMigration(personal, team);
+    const slimmedText = `${JSON.stringify(slimmed, null, 2)}\n`;
+    const beforeBytes = Buffer.byteLength(rawText, "utf8");
+    const afterBytes = Buffer.byteLength(slimmedText, "utf8");
+    const changed = slimmedText !== rawText;
+    const result = {
+        file,
+        changed,
+        before: { sizeBytes: beforeBytes, keys: Object.keys(personal) },
+        after: { sizeBytes: afterBytes, keys: Object.keys(slimmed) },
+        keys: plan.keys,
+        brand: plan.brand,
+        warnings: plan.warnings,
+    };
+    if (apply && changed) {
+        // Backup names include milliseconds (sub-second collisions on rapid
+        // re-apply would otherwise overwrite the original backup) AND copy
+        // with COPYFILE_EXCL so a same-millisecond collision throws instead
+        // of clobbering. Same for the temp file via `wx` flag.
+        const { backup, tmp } = acquireBackupAndTempPaths(file);
+        fs.copyFileSync(file, backup, fs.constants.COPYFILE_EXCL);
+        fs.writeFileSync(tmp, slimmedText, { encoding: "utf8", flag: "wx" });
+        fs.renameSync(tmp, file);
+        result.backup = backup;
+    }
+    return result;
+}
+function backupTimestamp() {
+    const d = new Date();
+    const pad = (n) => n.toString().padStart(2, "0");
+    const pad3 = (n) => n.toString().padStart(3, "0");
+    return (`${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+        `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}` +
+        `-${pad3(d.getMilliseconds())}`);
+}
+/**
+ * Pick a `.bak-<ts>` and `.tmp-<ts>` pair that don't collide with anything
+ * on disk. Millisecond resolution makes a collision extraordinarily rare,
+ * but a tight retry loop closes the remaining gap (and the `COPYFILE_EXCL`
+ * / `wx` flags at the call site fail loudly if the gap is ever crossed).
+ */
+function acquireBackupAndTempPaths(file) {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const ts = backupTimestamp();
+        const suffix = attempt === 0 ? ts : `${ts}-${attempt}`;
+        const backup = `${file}.bak-${suffix}`;
+        const tmp = `${file}.tmp-${suffix}`;
+        if (!fs.existsSync(backup) && !fs.existsSync(tmp)) {
+            return { backup, tmp };
+        }
+    }
+    throw new Error(`Could not pick a unique backup name for ${file} after 100 attempts; clean up old .bak-/.tmp- siblings and retry.`);
 }

package/dist/config/migrate-from-personal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export declare const TEAM_SHADOWABLE_KEYS: readonly ["members", "teams", "labels", "statusDefaults", "teamAliases"];
+export type TeamShadowableKey = (typeof TEAM_SHADOWABLE_KEYS)[number];
+export type JsonValue = string | number | boolean | null | {
+    [k: string]: JsonValue;
+} | JsonValue[];
+export type JsonObject = {
+    [k: string]: JsonValue;
+};
+/** Per-key decision in the plan. */
+export interface KeyAction {
+    key: string;
+    action: "drop" | "keep-divergent" | "keep-additions" | "absent";
+    /** Leaves whose personal value matched team exactly. */
+    matchCount: number;
+    /** Leaves whose personal value differs from team (would be a silent shadow). */
+    divergentCount: number;
+    /** Non-trivial personal-only leaves (would be lost if dropped). */
+    additionCount: number;
+    /** First few divergent / addition paths, for human-readable context. */
+    sampleDivergent?: string[];
+    sampleAdditions?: string[];
+}
+/** What we did with the deprecated `brand` key. */
+export interface BrandAction {
+    status: "absent" | "drop-duplicate" | "convert-to-term" /** Couldn't convert safely (e.g. existing personal `terms` is malformed). */ | "keep-malformed";
+    /** When status === "convert-to-term", the new entry appended to terms[]. */
+    convertedTo?: {
+        canonical: string;
+        reject: string[];
+    };
+    reason?: string;
+}
+export interface MigrationPlan {
+    keys: KeyAction[];
+    brand: BrandAction;
+    warnings: string[];
+}
+export interface MigrationResult {
+    slimmed: JsonObject;
+    plan: MigrationPlan;
+}
+/** A canonical JSON-friendly deep equality. */
+export declare function deepEqual(a: JsonValue, b: JsonValue): boolean;
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export declare function planMigration(personal: JsonObject, team: JsonObject): MigrationResult;

package/dist/config/migrate-from-personal.js

@@ -0,0 +1,236 @@
+/**
+ * Plan + apply the personal-to-team-backed config slim.
+ *
+ * After the team-config split (DEV-4172 / ALL-964) members typically still
+ * carry full duplicates of the now-shared keys in their personal/profile
+ * configs. The duplicates are silent shadows when identical and silent
+ * divergences when they drift. This module computes a per-file plan:
+ *
+ *  - **Top-level shadowable keys** (`members`, `teams`, `labels`,
+ *    `statusDefaults`, `teamAliases`) are *dropped* only when the personal
+ *    copy is a strict subset of team (zero divergence and zero non-trivial
+ *    personal-only entries). Otherwise the key is left untouched and the
+ *    diff is reported, so a human resolves it.
+ *  - The deprecated `brand: { name, reject }` key is dropped when content-
+ *    identical to an existing team `terms[]` entry; otherwise it is
+ *    *converted* into a personal `terms[]` entry (no shadowing of team).
+ *  - Genuinely personal keys (`defaultTeam`, `defaultLabels`,
+ *    `teamConfigPath`, anything not in the shadowable set or `brand`) are
+ *    never touched.
+ *
+ * Pure: no fs / no process / no logging. The caller does I/O. DEV-4458.
+ */
+/** Top-level keys typically owned by the team config layer. */
+export const TEAM_SHADOWABLE_KEYS = [
+    "members",
+    "teams",
+    "labels",
+    "statusDefaults",
+    "teamAliases",
+];
+/** A canonical JSON-friendly deep equality. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === "object") {
+        const ak = Object.keys(a).sort();
+        const bk = Object.keys(b).sort();
+        if (ak.length !== bk.length)
+            return false;
+        if (ak.some((k, i) => k !== bk[i]))
+            return false;
+        return ak.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function isTriviallyEmpty(v) {
+    if (v === undefined || v === null)
+        return true;
+    if (Array.isArray(v))
+        return v.length === 0;
+    if (typeof v === "object")
+        return Object.keys(v).length === 0;
+    return false;
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Walk personal and classify each LEAF against team at the same path:
+ *   match     — present in team with the same value
+ *   divergent — present in team with a different value (would silently shadow)
+ *   addition  — absent from team and non-trivially non-empty (would be lost)
+ *
+ * Trivially-empty containers (e.g. `members.handles.github = {}`) are not
+ * counted as additions — dropping them loses no information.
+ */
+function classifyDeep(personal, team, path, out) {
+    if (personal === undefined)
+        return;
+    // Both objects → recurse into keys.
+    if (isPlainObject(personal) && isPlainObject(team)) {
+        for (const k of Object.keys(personal)) {
+            classifyDeep(personal[k], team[k], path ? `${path}.${k}` : k, out);
+        }
+        return;
+    }
+    // Personal is a leaf (primitive / array / object without a matching team obj).
+    if (team === undefined) {
+        if (!isTriviallyEmpty(personal))
+            out.additions.push(path);
+        return;
+    }
+    if (deepEqual(personal, team)) {
+        out.matches += 1;
+    }
+    else {
+        out.divergent.push(path);
+    }
+}
+function planTopLevelKey(key, personal, team) {
+    if (personal === undefined) {
+        return {
+            key,
+            action: "absent",
+            matchCount: 0,
+            divergentCount: 0,
+            additionCount: 0,
+        };
+    }
+    const acc = { matches: 0, divergent: [], additions: [] };
+    classifyDeep(personal, team, key, acc);
+    const action = acc.divergent.length === 0 && acc.additions.length === 0
+        ? "drop"
+        : acc.divergent.length > 0
+            ? "keep-divergent"
+            : "keep-additions";
+    const ka = {
+        key,
+        action,
+        matchCount: acc.matches,
+        divergentCount: acc.divergent.length,
+        additionCount: acc.additions.length,
+    };
+    if (acc.divergent.length > 0)
+        ka.sampleDivergent = acc.divergent.slice(0, 5);
+    if (acc.additions.length > 0)
+        ka.sampleAdditions = acc.additions.slice(0, 5);
+    return ka;
+}
+function readBrand(personal) {
+    const raw = personal.brand;
+    if (!isPlainObject(raw))
+        return null;
+    const name = raw.name;
+    const reject = raw.reject;
+    if (typeof name !== "string")
+        return null;
+    if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+        return null;
+    }
+    return { name, reject: reject };
+}
+function readTeamTerms(team) {
+    const t = team.terms;
+    if (!Array.isArray(t))
+        return [];
+    const out = [];
+    for (const e of t) {
+        if (!isPlainObject(e))
+            continue;
+        const canonical = e.canonical;
+        const reject = e.reject;
+        if (typeof canonical !== "string")
+            continue;
+        if (!Array.isArray(reject) || !reject.every((r) => typeof r === "string")) {
+            continue;
+        }
+        out.push({ canonical, reject: reject });
+    }
+    return out;
+}
+function brandMatchesTerm(brand, term) {
+    return brand.name === term.canonical && deepEqual(brand.reject, term.reject);
+}
+/**
+ * Compute the slimmed config + the plan that explains it. Pure.
+ *
+ * @param personal The personal/profile config object as parsed from disk.
+ * @param team     The active team config object as parsed from disk. Pass
+ *                 `{}` if no team config is configured — every shadowable
+ *                 key becomes either `keep-additions` or `keep-divergent`,
+ *                 so nothing gets dropped (correct: without team there is
+ *                 nothing to fall back to).
+ */
+export function planMigration(personal, team) {
+    const warnings = [];
+    const slimmed = { ...personal };
+    const keyActions = TEAM_SHADOWABLE_KEYS.map((key) => planTopLevelKey(key, personal[key], team[key]));
+    for (const ka of keyActions) {
+        if (ka.action === "drop")
+            delete slimmed[ka.key];
+    }
+    // Brand → terms.
+    let brand;
+    const brandShape = readBrand(personal);
+    if (brandShape === null) {
+        brand = { status: "absent" };
+    }
+    else {
+        const teamTerms = readTeamTerms(team);
+        const dup = teamTerms.find((t) => brandMatchesTerm(brandShape, t));
+        if (dup !== undefined) {
+            delete slimmed.brand;
+            brand = {
+                status: "drop-duplicate",
+                reason: `brand is content-identical to team terms entry "${dup.canonical}"`,
+            };
+        }
+        else if (personal.terms !== undefined && !Array.isArray(personal.terms)) {
+            // Refuse to convert: an existing personal `terms` field is not an
+            // array (likely a hand-edit gone wrong). The strict-subset gate
+            // elsewhere never silently destroys info — neither should this
+            // path. Leave brand AND terms as-is; surface as a warning so a
+            // human can resolve.
+            brand = {
+                status: "keep-malformed",
+                reason: "existing personal 'terms' field is not an array; leaving 'brand' and 'terms' untouched for human review",
+            };
+            warnings.push(`Cannot convert deprecated 'brand': existing 'terms' field is not an array (got ${typeof personal.terms}). Left 'brand' and 'terms' as-is — fix 'terms' to a proper array of { canonical, reject } entries and re-run.`);
+        }
+        else {
+            // Convert: append a personal terms entry, drop brand.
+            delete slimmed.brand;
+            const existing = Array.isArray(slimmed.terms)
+                ? slimmed.terms
+                : [];
+            const converted = {
+                canonical: brandShape.name,
+                reject: brandShape.reject,
+            };
+            slimmed.terms = [...existing, { ...converted }];
+            brand = {
+                status: "convert-to-term",
+                convertedTo: converted,
+                reason: teamTerms.length === 0
+                    ? "team config has no terms; converted brand to a personal terms entry"
+                    : "brand does not match any team terms entry; converted to a personal terms entry",
+            };
+            if (teamTerms.length > 0) {
+                warnings.push(`brand on this file diverges from team terms — preserved as a personal terms entry. Review whether the team config should adopt it.`);
+            }
+        }
+    }
+    return { slimmed, plan: { keys: keyActions, brand, warnings } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",