feat: add latest parameter for xcodes and update CLUADE.md

Author: test2

CLAUDE.md

@@ -501,6 +501,46 @@ parameterSettings: {
 }
 ```
 
+### "latest" Keyword for Version-List Parameters
+
+When a resource manages a list of installed versions (e.g. `nvm`'s Node versions, `pyenv`'s Python versions, `xcodes`' Xcode versions), always support a symbolic `'latest'` entry in that array alongside explicit version strings. This lets users write `versions: ['latest']` instead of having to know/hardcode the current newest release.
+
+**Requirements for `'latest'`:**
+- It must resolve to a real, concrete version at `addItem`/install time (e.g. by passing whatever "install latest" flag the underlying CLI supports — `xcodes install --latest`, `nvm install --lts`/`node`, `pyenv install` + `pyenv latest -k <major>`, etc. — or by resolving the latest version yourself before installing if the CLI has no such flag).
+- It must **not** show up as a perpetual diff in the plan. Once resolved, `refresh()` should normalize the real installed version back to the literal string `'latest'` in the array it returns whenever that installed version is the one which satisfies the `'latest'` entry in desired — so the framework's equality check treats them as converged instead of proposing an add/remove on every plan.
+- `removeItem` (and any other lifecycle method that receives an individual array element) must resolve `'latest'` back to the real installed version before acting — never pass the literal string `'latest'` to an uninstall/select command.
+
+**Reference implementation:** `src/resources/xcodes/xcode-versions-parameter.ts` (`LATEST_VERSION_KEYWORD`, `normalizeLatestKeyword`, `resolveInstalledVersion`). The pattern:
+
+```typescript
+export const LATEST_VERSION_KEYWORD = 'latest';
+
+export class MyVersionsParameter extends ArrayStatefulParameter<MyConfig, string> {
+  getSettings(): ArrayParameterSetting {
+    return { type: 'array', isElementEqual: (desired, current) => desired === current };
+  }
+
+  override async refresh(desired: string[] | null): Promise<string[] | null> {
+    const installed = await getInstalledVersions();
+    return normalizeLatestKeyword(installed, desired ?? []); // maps the newest unclaimed installed version back to 'latest'
+  }
+
+  override async addItem(version: string): Promise<void> {
+    const installArg = version === LATEST_VERSION_KEYWORD ? '--latest' : version;
+    await install(installArg);
+  }
+
+  override async removeItem(version: string): Promise<void> {
+    const resolved = version === LATEST_VERSION_KEYWORD ? await resolveNewestInstalled() : version;
+    if (resolved) await uninstall(resolved);
+  }
+}
+```
+
+Also add `'latest'` as a hardcoded first entry in that parameter's completions file (`completions/<resource>.$.<param>.ts`) so it surfaces as a suggestion in the editor alongside real fetched version numbers.
+
+Do **not** extend this convention to a resource's singular "selected/active version" parameter (e.g. `xcodes`' `selected`) unless the underlying CLI's select/activate command itself supports a latest-equivalent flag — most select commands only operate on already-installed exact versions.
+
 ### defaultConfig and exampleConfigs
 
 Every resource should have a `defaultConfig` and `exampleConfigs`. These are surfaced in the Codify Editor to help users get started quickly.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "default",
-  "version": "1.15.3-beta.2",
+  "version": "1.15.3-beta.3",
   "description": "Default plugin for Codify - provides 50+ declarative resources for managing development tools and system configuration across macOS and Linux",
   "main": "dist/index.js",
   "scripts": {

src/resources/xcodes/completions/xcodes.$.xcodeVersions.ts

@@ -19,5 +19,7 @@ function toXcodesVersionString(release: XcodeRelease): string {
 export default async function loadXcodeVersions(): Promise<string[]> {
   const response = await fetch(XCODE_RELEASES_URL);
   const releases = await response.json() as XcodeRelease[];
-  return releases.map(toXcodesVersionString);
+  // "latest" is a hardcoded sentinel supported by the xcodes resource
+  // (maps to `xcodes install --latest`), not a real xcodereleases.com entry.
+  return ['latest', ...releases.map(toXcodesVersionString)];
 }

src/resources/xcodes/xcode-versions-parameter.ts

@@ -1,12 +1,25 @@
-import { ArrayStatefulParameter, Plan, SpawnStatus, getPty } from '@codifycli/plugin-core';
+import { ArrayParameterSetting, ArrayStatefulParameter, Plan, SpawnStatus, getPty } from '@codifycli/plugin-core';
 
 import { XcodesConfig } from './xcodes-resource.js';
 
+export const LATEST_VERSION_KEYWORD = 'latest';
+
 export class XcodeVersionsParameter extends ArrayStatefulParameter<XcodesConfig, string> {
-  override async refresh(_desired: string[] | null): Promise<string[] | null> {
+  getSettings(): ArrayParameterSetting {
+    return {
+      type: 'array',
+      // "latest" never matches a real version string returned by refresh() on its own;
+      // refresh() below re-normalizes whichever installed version fulfilled "latest"
+      // back into the literal string "latest" so the framework treats them as equal.
+      isElementEqual: (desired, current) => desired === current,
+    };
+  }
+
+  override async refresh(desired: string[] | null): Promise<string[] | null> {
     const $ = getPty();
     const { data } = await $.spawnSafe('xcodes installed');
-    return parseInstalledVersions(data);
+    const installed = parseInstalledVersions(data);
+    return normalizeLatestKeyword(installed, desired ?? []);
   }
 
   override async addItem(version: string, plan: Plan<XcodesConfig>): Promise<void> {
@@ -17,17 +30,28 @@ export class XcodeVersionsParameter extends ArrayStatefulParameter<XcodesConfig,
     if (appleId) env['XCODES_USERNAME'] = appleId;
     if (appleIdPassword) env['XCODES_PASSWORD'] = appleIdPassword;
 
-    await $.spawn(`xcodes install "${version}"`, {
+    const installArg = version === LATEST_VERSION_KEYWORD ? '--latest' : `"${version}"`;
+    await $.spawn(`xcodes install ${installArg}`, {
       interactive: true,
       stdin: true,
       ...(Object.keys(env).length > 0 ? { env } : {}),
     });
 
     if (acceptLicense !== false) {
-      await this.acceptLicenseIfNeeded(version);
+      const installedVersion = await this.resolveInstalledVersion(version);
+      if (installedVersion) await this.acceptLicenseIfNeeded(installedVersion);
     }
   }
 
+  private async resolveInstalledVersion(version: string): Promise<string | null> {
+    if (version !== LATEST_VERSION_KEYWORD) return version;
+
+    const $ = getPty();
+    const { data } = await $.spawnSafe('xcodes installed');
+    const installed = parseInstalledVersions(data);
+    return installed.at(-1) ?? null;
+  }
+
   private async acceptLicenseIfNeeded(version: string): Promise<void> {
     const $ = getPty();
 
@@ -45,7 +69,9 @@ export class XcodeVersionsParameter extends ArrayStatefulParameter<XcodesConfig,
 
   override async removeItem(version: string): Promise<void> {
     const $ = getPty();
-    await $.spawn(`xcodes uninstall "${version}"`, { interactive: true });
+    const installedVersion = await this.resolveInstalledVersion(version);
+    if (!installedVersion) return;
+    await $.spawn(`xcodes uninstall "${installedVersion}"`, { interactive: true });
   }
 }
 
@@ -60,3 +86,20 @@ function parseInstalledVersions(output: string): string[] {
     })
     .filter((v): v is string => v !== null);
 }
+
+/**
+ * Replaces whichever installed version fulfills the "latest" sentinel with the
+ * literal string "latest" so the framework's equality check (desired === current)
+ * treats them as converged, instead of endlessly re-adding/removing.
+ */
+function normalizeLatestKeyword(installed: string[], desired: string[]): string[] {
+  if (!desired.includes(LATEST_VERSION_KEYWORD)) return installed;
+
+  const unclaimed = installed.filter((v) => !desired.includes(v));
+  if (unclaimed.length === 0) return installed;
+
+  // xcodes installed lists oldest-to-newest; the newest unclaimed version is
+  // the one that satisfies "latest".
+  const latestMatch = unclaimed.at(-1)!;
+  return installed.map((v) => (v === latestMatch ? LATEST_VERSION_KEYWORD : v));
+}

src/resources/xcodes/xcodes-resource.ts

@@ -17,7 +17,10 @@ const schema = z
   .object({
     xcodeVersions: z
       .array(z.string())
-      .describe('List of Xcode versions to install via xcodes (e.g. ["15.2", "14.3.1"]).')
+      .describe(
+        'List of Xcode versions to install via xcodes (e.g. ["15.2", "14.3.1"]). ' +
+        'Use "latest" to install the newest available Xcode release (runs `xcodes install --latest`).'
+      )
       .optional(),
     selected: z
       .string()