feat: Add uv and tests

Author: kevinwang5658

package-lock.json

@@ -54,6 +54,7 @@
     "trash": "^10.0.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.97",
     "@apidevtools/json-schema-ref-parser": "^11.7.2",
     "@codifycli/plugin-test": "^1.0.0",
     "@fastify/merge-json-schemas": "^0.2.0",
@@ -70,14 +71,13 @@
     "@types/debug": "4.1.12",
     "@types/lodash.isequal": "^4.5.8",
     "@types/mock-fs": "^4.13.4",
-    "@types/uuid": "10.0.0",
     "@types/node": "^18",
     "@types/plist": "^3.0.5",
     "@types/semver": "^7.5.4",
+    "@types/uuid": "10.0.0",
     "commander": "^12.1.0",
     "eslint": "^10.0.3",
-    "eslint-config-oclif": "^6.0.146",
-    "eslint-config-oclif-typescript": "^3.1.14",
+    "eslint-config-oclif": "^6.0.156",
     "eslint-config-prettier": "^10.1.8",
     "glob": "^11.0.0",
     "merge-json-schemas": "^1.0.0",

package.json

@@ -0,0 +1,146 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const toolName = 'uv';
+const toolHomepage = 'https://docs.astral.sh/uv/#projects'
+
+const researchResults = [
+`Here's a summary of the research and proposed design:
+
+---
+
+## \`uv\` Resource Design
+
+### What was researched
+- **uv** is a blazing-fast Python tool from Astral that replaces pip, pyenv, pipx, poetry, and virtualenv in one binary.
+
+---
+
+### Installation
+| Platform | Method |
+|---|---|
+| macOS | \`brew install uv\` (Homebrew, preferred since Codify users likely have it) |
+| Linux | \`curl -LsSf https://astral.sh/uv/install.sh \\| sh\` with \`UV_NO_MODIFY_PATH=1\`, then manually add \`~/.local/bin\` to shell rc |
+
+No Rust or Python required. No other OS-level dependencies beyond curl on Linux.
+
+---
+
+### Proposed Resources
+
+**One resource: \`uv\`** (located at \`src/resources/python/uv/\`)
+
+| Parameter | Type | Description |
+|---|---|---|
+| \`pythonVersions\` | Stateful \`string[]\` | Python versions to install via \`uv python install\` (e.g. \`["3.12", "3.11"]\`) |
+| \`tools\` | Stateful \`string[]\` | CLI tools installed globally via \`uv tool install\` (e.g. \`["ruff", "black"]\`) |
+
+This follows the same pattern as **pyenv** (install tool + manage Python versions) and **NVM** (install tool + manage versions as stateful parameter).
+
+---
+
+### Key Design Decisions
+
+1. **Homebrew dependency on macOS** — Declared via \`dependencies: ['homebrew']\` mirroring the \`asdf\` resource pattern.
+2. **Two stateful parameters** — \`pythonVersions\` (parsed from \`uv python list --only-installed\`) and \`tools\` (parsed from \`uv tool list\`).
+3. **Version prefix matching** — Desired \`"3.12"\` matches installed \`"3.12.3"\` using \`startsWith\` in \`isElementEqual\`.
+4. **No sub-resources** — Unlike asdf (which has \`asdf-plugin\` and \`asdf-install\` sub-resources), uv's tool and Python management is simple enough to handle as stateful parameters on the main resource.
+`
+];
+
+// for await (const message of query({
+//   prompt:
+//     `Research and design a Codify resource for ${toolName} (the homepage is: ${toolHomepage})
+//
+// The research should include:
+// ** The installation method **
+// - The installation method for the tool of application (in the case ${toolName})
+// - The installation method should be the most standard installation method.
+// - Find the installation instructions for both macOS and Linux.
+//
+// ** Dependencies **
+// - Any dependencies or prerequisites for installation
+//
+// ** Configuration **
+// - Any configuration options or settings for the tool
+// - Any settings that we want the user to manage (which will later be exposed as parameters in the Codify resource)
+// - The default values for these settings
+//
+// ** Usages **
+// - Examples of how the tool can be used
+// - Any common use cases or scenarios
+// - Any use case we want to manage via the Codify resource or sub-resources or stateful parameters
+// - For example:
+//   - The homebrew resource installs homebrew but it also has the formulae and casks stateful parameters that manage installed packages.
+//   - The asdf resource installs asdf, a tool version manager, but it also has the plugins stateful parameter that manages installed plugins.
+//   - The asdf resource has sub resources for installing tool plugins and versions.
+//
+// The purpose of this research is to be used later by Claude to create the resources needed in code. Format the answer so that
+// it can be easily understood by Claude.
+//   `,
+//   options: {
+//     settingSources: ['project'],
+//     allowedTools: ["WebSearch", "WebFetch"],
+//     mcpServers: {},
+//     permissionMode: 'plan',
+//     cwd: '../'
+//   }
+// })) {
+//   // Print human-readable output
+//   if (message.type === "assistant" && message.message?.content) {
+//     for (const block of message.message.content) {
+//       if ("text" in block) {
+//         console.log(block.text); // Claude's reasoning
+//         researchResults.push(block.text);
+//       } else if ("name" in block) {
+//         console.log(`Tool: ${block.name}`); // Tool being called
+//       }
+//     }
+//   } else if (message.type === "result") {
+//     console.log(`Done: ${message.subtype}`); // Final result
+//   }
+// }
+
+// Checkout a new git branch
+// Launch a new docker container
+
+for await (const message of query({
+  prompt: `Use the research results to design a Codify resource for ${toolName} (the homepage is: ${toolHomepage}).
+  
+Guidelines:
+- Follow the other tools in the project under @src/resources/** as a guideline
+- Prefer to use Zod over JSON Schema  
+- Remember to write tests, follow the other test examples under @test/** as a guideline
+- Keep the resource simple and focused on the core functionality of ${toolName}
+- Use the research to guide the software design
+- Remember to split up functions if they get too long and complicated to understand. Create helper functions instead with idiomatic names.
+
+Steps:
+- Write code to fulfill the requirements laid out in the research.
+- Add the resource to @src/index.ts so that it is visible
+- Write tests for the code to test ${toolName}
+- Ensure typescript is correct using tsx
+- Run the test using 'npm run test:integration:dev -- $PathToTheTestFile'
+- Do not try to test the code in any other ways. It may brick the current computer if you do.
+
+Research:
+${researchResults.join('\n\n')}
+  `,
+  options: {
+    settingSources: ['project'],
+    permissionMode: "bypassPermissions", // Auto-approve file edits
+    cwd: '../'
+  }
+})) {
+  // Print human-readable output
+  if (message.type === "assistant" && message.message?.content) {
+    for (const block of message.message.content) {
+      if ("text" in block) {
+        console.log(block.text); // Claude's reasoning
+      } else if ("name" in block) {
+        console.log(`Tool: ${block.name}`); // Tool being called
+      }
+    }
+  } else if (message.type === "result") {
+    console.log(`Done: ${message.subtype}`); // Final result
+  }
+}

scripts/runbook.ts

@@ -26,6 +26,7 @@ import { PgcliResource } from './resources/pgcli/pgcli.js';
 import { Pip } from './resources/python/pip/pip.js';
 import { PipSync } from './resources/python/pip-sync/pip-sync.js';
 import { PyenvResource } from './resources/python/pyenv/pyenv.js';
+import { UvResource } from './resources/python/uv/uv.js';
 import { VenvProject } from './resources/python/venv/venv-project.js';
 import { Virtualenv } from './resources/python/virtualenv/virtualenv.js';
 import { VirtualenvProject } from './resources/python/virtualenv/virtualenv-project.js';
@@ -54,6 +55,7 @@ runPlugin(Plugin.create(
     new AliasesResource(),
     new HomebrewResource(),
     new PyenvResource(),
+    new UvResource(),
     new GitLfsResource(),
     new AwsCliResource(),
     new AwsProfileResource(),

src/index.ts

@@ -0,0 +1,69 @@
+import { ArrayParameterSetting, ArrayStatefulParameter, getPty, SpawnStatus } from '@codifycli/plugin-core';
+
+import { UvConfig } from './uv.js';
+
+/**
+ * uv python list --only-installed output example:
+ *   cpython-3.12.3-macos-aarch64-none
+ *   cpython-3.11.9-macos-aarch64-none
+ *
+ * We extract the version string (e.g. "3.12.3") from each line and match
+ * against the user-specified prefix (e.g. "3.12").
+ */
+export class UvPythonVersionsParameter extends ArrayStatefulParameter<UvConfig, string> {
+  getSettings(): ArrayParameterSetting {
+    return {
+      type: 'array',
+      // desired "3.12" matches installed "3.12.3" via startsWith
+      isElementEqual: (desired, current) => current.startsWith(desired),
+    };
+  }
+
+  override async refresh(desired: string[] | null): Promise<string[] | null> {
+    const $ = getPty();
+
+    const { status, data } = await $.spawnSafe('uv python list --only-installed');
+    if (status === SpawnStatus.ERROR) {
+      return null;
+    }
+
+    const installedVersions = parseInstalledPythonVersions(data);
+
+    // Replace full versions with the matching desired prefix so the framework
+    // can treat them as equal (e.g. "3.12.3" → "3.12" when desired is "3.12").
+    return normalizeToDesiredPrefixes(installedVersions, desired ?? []);
+  }
+
+  override async addItem(version: string): Promise<void> {
+    const $ = getPty();
+    await $.spawn(`uv python install ${version}`, { interactive: true });
+  }
+
+  override async removeItem(version: string): Promise<void> {
+    const $ = getPty();
+    await $.spawn(`uv python uninstall ${version}`, { interactive: true });
+  }
+}
+
+/** Extract semver strings like "3.12.3" from lines such as "cpython-3.12.3-macos-aarch64-none" */
+function parseInstalledPythonVersions(output: string): string[] {
+  return output
+    .split('\n')
+    .map((line) => {
+      const match = line.match(/cpython-(\d+\.\d+\.\d+)/);
+      return match ? match[1] : null;
+    })
+    .filter((v): v is string => v !== null);
+}
+
+/**
+ * For each installed full version (e.g. "3.12.3"), if a desired prefix matches
+ * it (e.g. "3.12"), replace the full version entry with the prefix so the
+ * framework sees them as equal.
+ */
+function normalizeToDesiredPrefixes(installed: string[], desired: string[]): string[] {
+  return installed.map((fullVersion) => {
+    const matchedPrefix = desired.find((prefix) => fullVersion.startsWith(prefix));
+    return matchedPrefix ?? fullVersion;
+  });
+}

src/resources/python/uv/python-versions-parameter.ts

@@ -0,0 +1,46 @@
+import { ArrayStatefulParameter, getPty, SpawnStatus } from '@codifycli/plugin-core';
+
+import { UvConfig } from './uv.js';
+
+/**
+ * uv tool list output example:
+ *   ruff v0.4.4
+ *       - ruff
+ *   black v24.4.2
+ *       - black
+ *       - blackd
+ *
+ * We extract the tool names from lines that do NOT start with whitespace (the
+ * header lines), taking everything before the first space.
+ */
+export class UvToolsParameter extends ArrayStatefulParameter<UvConfig, string> {
+  override async refresh(desired: string[] | null): Promise<string[] | null> {
+    const $ = getPty();
+
+    const { status, data } = await $.spawnSafe('uv tool list');
+    if (status === SpawnStatus.ERROR) {
+      return null;
+    }
+
+    return parseInstalledTools(data);
+  }
+
+  override async addItem(tool: string): Promise<void> {
+    const $ = getPty();
+    await $.spawn(`uv tool install ${tool}`, { interactive: true });
+  }
+
+  override async removeItem(tool: string): Promise<void> {
+    const $ = getPty();
+    await $.spawn(`uv tool uninstall ${tool}`, { interactive: true });
+  }
+}
+
+/** Extract tool names from the header lines of `uv tool list` output */
+function parseInstalledTools(output: string): string[] {
+  return output
+    .split('\n')
+    .filter((line) => line.length > 0 && !/^\s/.test(line))
+    .map((line) => line.split(' ')[0].trim())
+    .filter(Boolean);
+}