feat(anchor-pnpm): new CLI for managing pnpm-workspace.yaml anchors

README.md

@@ -63,6 +63,7 @@ All packages are packaged underneath the `@stephansama` scope (for example: `@st
 | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | [ai-commit-msg](core/ai-commit-msg/README.md)                             | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Fai-commit-msg?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)               | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/ai-commit-msg?labelColor=211F1F)               | generate commit messages using ai                                                             |
 | [alfred-kaomoji](core/alfred-kaomoji/README.md)                           | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Falfred-kaomoji?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)              | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/alfred-kaomoji?labelColor=211F1F)              | Alfred Kaomoji Picker                                                                         |
+| [anchor-pnpm](core/anchor-pnpm/README.md)                                 | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Fanchor-pnpm?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)                 | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/anchor-pnpm?labelColor=211F1F)                 | Manage YAML anchor declarations in pnpm-workspace.yaml                                        |
 | [astro-iconify-svgmap](core/astro-iconify-svgmap/README.md)               | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Fastro-iconify-svgmap?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)        | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/astro-iconify-svgmap?labelColor=211F1F)        | Astro integration for generating iconify svgmaps for ssg sites                                |
 | [auto-readme](core/auto-readme/README.md)                                 | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Fauto-readme?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F)                 | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/auto-readme?labelColor=211F1F)                 | Generate lists and tables for your README automagically based on your repository and comments |
 | [catppuccin-jsonresume-theme](core/catppuccin-jsonresume-theme/README.md) | ![npm version image](https://img.shields.io/npm/v/%40stephansama%2Fcatppuccin-jsonresume-theme?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F) | ![npm downloads](https://img.shields.io/npm/dw/@stephansama/catppuccin-jsonresume-theme?labelColor=211F1F) | theme for resume cli website                                                                  |

core/anchor-pnpm/README.md

@@ -0,0 +1,42 @@
+# @stephansama/anchor-pnpm
+
+CLI for managing YAML anchor declarations in `pnpm-workspace.yaml`.
+
+Many pnpm catalog setups repeat the same version string across multiple packages in a catalog group:
+
+```yaml
+catalogs:
+  alpine:
+    alpinejs: 3.15.8
+    "@alpinejs/focus": 3.15.8
+```
+
+Sharing the version via a YAML anchor keeps them in lock-step:
+
+```yaml
+__versions:
+  - &alpine 3.15.8
+
+catalogs:
+  alpine:
+    alpinejs: *alpine
+    "@alpinejs/focus": *alpine
+```
+
+`anchor-pnpm` automates creating and maintaining that `__versions` block while preserving the surrounding YAML (anchors, comments, ordering) via the `yaml` package's Document API.
+
+## Commands
+
+- `anchor-pnpm list` — print every anchor name and resolved version.
+- `anchor-pnpm add <name> <version>` — append a new `&<name> <version>` entry.
+- `anchor-pnpm update <name> <version>` — set the scalar value of an existing anchor (all `*<name>` aliases follow automatically).
+- `anchor-pnpm remove <name>` — remove the anchor; errors if aliases still reference it (pass `--force` to inline them first).
+- `anchor-pnpm sync` — _scheduled, not yet implemented._ Auto-detect catalog groups with repeated versions and convert them to anchor+alias pairs.
+
+## Global flags
+
+```
+--workspace, -w   Path to pnpm-workspace.yaml  (default: auto-detect via @manypkg/find-root)
+--dry-run,  -d    Print the rewritten YAML to stdout instead of writing
+--verbose,  -v    Show detailed output
+```

core/anchor-pnpm/__snapshots__/tsnapi/cli.snapshot.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@stephansama/anchor-pnpm/cli`
+ */
+/* no exports */

core/anchor-pnpm/__snapshots__/tsnapi/cli.snapshot.js

@@ -0,0 +1,4 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@stephansama/anchor-pnpm/cli`
+ */
+/* no exports */

core/anchor-pnpm/__snapshots__/tsnapi/index.snapshot.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@stephansama/anchor-pnpm`
+ */
+// #region Functions
+export declare function add(_: Document, _: string, _: string): {
+  added: boolean;
+};
+export declare function list(_: Document): AnchorEntry[];
+export declare function loadWorkspace(_: string): Promise<Document.Parsed>;
+export declare function remove(_: Document, _: string, _?: {
+  force?: boolean;
+}): {
+  dangling: string[];
+  removed: boolean;
+};
+export declare function resolveWorkspacePath(_?: string): Promise<string>;
+export declare function saveWorkspace(_: string, _: Document): Promise<void>;
+export declare function sync(_: Document): SyncProposal[];
+export declare function update(_: Document, _: string, _: string): {
+  updated: boolean;
+};
+// #endregion

core/anchor-pnpm/__snapshots__/tsnapi/index.snapshot.js

@@ -0,0 +1,13 @@
+/**
+ * Generated by tsnapi — public API snapshot of `@stephansama/anchor-pnpm`
+ */
+// #region Functions
+export function add(_, _, _) {}
+export function list(_) {}
+export async function loadWorkspace(_) {}
+export function remove(_, _, _) {}
+export async function resolveWorkspacePath(_) {}
+export async function saveWorkspace(_, _) {}
+export function sync(_) {}
+export function update(_, _, _) {}
+// #endregion

core/anchor-pnpm/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@stephansama/anchor-pnpm",
+  "version": "0.1.0",
+  "description": "Manage YAML anchor declarations in pnpm-workspace.yaml",
+  "keywords": [
+    "anchor",
+    "anchor-pnpm",
+    "cli",
+    "pnpm",
+    "tanstack-intent",
+    "workspace",
+    "yaml"
+  ],
+  "homepage": "https://packages.stephansama.info/api/@stephansama/anchor-pnpm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stephansama/packages.git",
+    "directory": "core/anchor-pnpm"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Stephan Randle",
+    "email": "stephanrandle.dev@gmail.com",
+    "url": "https://stephansama.info"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./cli": "./dist/cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "anchor-pnpm": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:snapshot": "tsdown -u",
+    "dev": "tsdown --watch",
+    "lint": "eslint ./src/ --pass-on-no-patterns --no-error-on-unmatched-pattern",
+    "lint:fix": "eslint ./src/ --pass-on-no-patterns --no-error-on-unmatched-pattern --fix"
+  },
+  "dependencies": {
+    "@manypkg/find-root": "catalog:manypkg",
+    "cleye": "catalog:cli",
+    "yaml": "catalog:",
+    "zod": "catalog:schema"
+  },
+  "devDependencies": {
+    "tsdown": "catalog:"
+  },
+  "packageManager": "pnpm@10.29.3",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

core/anchor-pnpm/src/anchors.ts

@@ -0,0 +1,217 @@
+import {
+	Alias,
+	Document,
+	isAlias,
+	isMap,
+	isPair,
+	isScalar,
+	isSeq,
+	Scalar,
+	YAMLSeq,
+} from "yaml";
+
+const VERSIONS_KEY = "__versions";
+const CATALOGS_KEY = "catalogs";
+
+export type AnchorEntry = { name: string; value: string };
+
+export type SyncProposal = {
+	anchorName: string;
+	catalog: string;
+	keys: string[];
+	version: string;
+};
+
+export function add(
+	document: Document,
+	name: string,
+	value: string,
+): { added: boolean } {
+	const seq = ensureVersionsSeq(document);
+	if (findAnchor(seq, name)) return { added: false };
+	const scalar = new Scalar(value);
+	scalar.anchor = name;
+	seq.add(scalar);
+	return { added: true };
+}
+
+export function applySyncProposal(
+	document: Document,
+	proposal: SyncProposal,
+): void {
+	add(document, proposal.anchorName, proposal.version);
+	const catalogs = document.get(CATALOGS_KEY);
+	if (!isMap(catalogs)) return;
+	const group = catalogs.get(proposal.catalog);
+	if (!isMap(group)) return;
+
+	for (const entry of group.items) {
+		if (!isPair(entry) || !isScalar(entry.key)) continue;
+		if (!proposal.keys.includes(String(entry.key.value))) continue;
+		entry.value = new Alias(proposal.anchorName);
+	}
+}
+
+export function list(document: Document): AnchorEntry[] {
+	const seq = getVersionsSeq(document);
+	if (!seq) return [];
+	const entries: AnchorEntry[] = [];
+	for (const item of seq.items) {
+		if (!isScalar(item) || !item.anchor) continue;
+		entries.push({ name: item.anchor, value: String(item.value) });
+	}
+	return entries;
+}
+
+export function remove(
+	document: Document,
+	name: string,
+	options: { force?: boolean } = {},
+): { dangling: string[]; removed: boolean } {
+	const seq = getVersionsSeq(document);
+	if (!seq) return { dangling: [], removed: false };
+
+	const dangling = collectAliasPaths(document, name);
+	if (dangling.length > 0 && !options.force) {
+		return { dangling, removed: false };
+	}
+
+	if (dangling.length > 0 && options.force) {
+		const scalar = findAnchor(seq, name);
+		replaceAliasesWithLiteral(document, name, scalar?.value);
+	}
+
+	const index = seq.items.findIndex(
+		(item) => isScalar(item) && item.anchor === name,
+	);
+	if (index === -1) return { dangling: [], removed: false };
+	seq.items.splice(index, 1);
+	return { dangling: [], removed: true };
+}
+
+export function sync(document: Document): SyncProposal[] {
+	const catalogs = document.get(CATALOGS_KEY);
+	if (!isMap(catalogs)) return [];
+
+	const proposals: SyncProposal[] = [];
+
+	for (const pair of catalogs.items) {
+		if (!isPair(pair) || !isScalar(pair.key) || !isMap(pair.value))
+			continue;
+		const catalogName = String(pair.key.value);
+		const versionToKeys = new Map<string, string[]>();
+
+		for (const entry of pair.value.items) {
+			if (!isPair(entry) || !isScalar(entry.key)) continue;
+			const value = entry.value;
+			if (!isScalar(value) || value.anchor) continue;
+			const versionString = String(value.value);
+			const keyString = String(entry.key.value);
+			versionToKeys.set(versionString, [
+				...(versionToKeys.get(versionString) ?? []),
+				keyString,
+			]);
+		}
+
+		for (const [version, keys] of versionToKeys) {
+			if (keys.length < 2) continue;
+			proposals.push({
+				anchorName: catalogName,
+				catalog: catalogName,
+				keys,
+				version,
+			});
+		}
+	}
+
+	return proposals;
+}
+
+export function update(
+	document: Document,
+	name: string,
+	value: string,
+): { updated: boolean } {
+	const seq = getVersionsSeq(document);
+	if (!seq) return { updated: false };
+	const scalar = findAnchor(seq, name);
+	if (!scalar) return { updated: false };
+	scalar.value = value;
+	return { updated: true };
+}
+
+function collectAliasPaths(document: Document, name: string): string[] {
+	const paths: string[] = [];
+	function walk(node: unknown, trail: string[]): void {
+		if (isAlias(node)) {
+			if (node.source === name) paths.push(trail.join(".") || "(root)");
+			return;
+		}
+		if (isMap(node)) {
+			for (const pair of node.items) {
+				if (!isPair(pair) || !isScalar(pair.key)) continue;
+				walk(pair.value, [...trail, String(pair.key.value)]);
+			}
+			return;
+		}
+		if (isSeq(node)) {
+			let index = 0;
+			for (const item of node.items) {
+				walk(item, [...trail, String(index++)]);
+			}
+		}
+	}
+	walk(document.contents, []);
+	return paths;
+}
+
+function ensureVersionsSeq(document: Document): YAMLSeq {
+	const existing = getVersionsSeq(document);
+	if (existing) return existing;
+	const seq = new YAMLSeq();
+	document.set(VERSIONS_KEY, seq);
+	return seq;
+}
+
+function findAnchor(seq: YAMLSeq, name: string): Scalar | undefined {
+	for (const item of seq.items) {
+		if (isScalar(item) && item.anchor === name) return item;
+	}
+	return undefined;
+}
+
+function getVersionsSeq(document: Document): undefined | YAMLSeq {
+	const node = document.get(VERSIONS_KEY);
+	return isSeq(node) ? node : undefined;
+}
+
+function replaceAliasesWithLiteral(
+	document: Document,
+	name: string,
+	literal: unknown,
+): void {
+	function visit(node: unknown): void {
+		if (isMap(node)) {
+			for (const pair of node.items) {
+				if (!isPair(pair)) continue;
+				if (isAlias(pair.value) && pair.value.source === name) {
+					pair.value = new Scalar(literal);
+				} else {
+					visit(pair.value);
+				}
+			}
+			return;
+		}
+		if (isSeq(node)) {
+			for (let index = 0; index < node.items.length; index++) {
+				const item = node.items[index];
+				if (isAlias(item) && item.source === name) {
+					node.items[index] = new Scalar(literal);
+				} else {
+					visit(item);
+				}
+			}
+		}
+	}
+	visit(document.contents);
+}