@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/worktree/worktree-audit.js

@@ -1,28 +1,3 @@
-/**
- * worktree-audit.js — reconcile the three views of "which worktrees exist".
- *
- * Orphan worktrees accumulate silently. In the observed session,
- * `.worktrees/verify-tables-ui` and `.worktrees/tmp-cleanup` were registered in
- * `git worktree list` yet ABSENT from `morph-spec fleet` — fleet only reports
- * worktrees whose branch matches `refs/heads/morph/*`, so anything else is
- * invisible by construction and therefore never cleaned up (C2).
- *
- * Nothing compared the three sources that must agree:
- *
- *   1. git's registry   — `git worktree list --porcelain`
- *   2. the disk         — directories under `worktrees/` (and legacy `.worktrees/`)
- *   3. morph's features — `.morph/features/{f}/feature.json`
- *
- * Read-only and fail-open: anything unresolvable yields no issue rather than a
- * throw. A diagnostic that invents problems is worse than one that misses some.
- * The mutations all live in `pruneWorktrees`, and each is deliberately the
- * safest possible: `git worktree prune` drops ADMIN RECORDS for directories
- * that are already gone, and the empty-residue sweep removes only directories
- * with zero entries inside — nothing that can hold work. Deleting a directory
- * that still HOLDS something stays a human decision, the same PROVE-or-DECLINE
- * discipline `teardownWorktree` follows.
- */
-
 import { execFileSync } from 'child_process';
 import { existsSync, readdirSync, readFileSync, rmdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
@@ -73,7 +48,6 @@ function agentLeftoverIssue(item) {
   };
 }
 
-/** Feature names morph knows about in the primary root. */
 function knownFeatures(root) {
   const names = new Set();
   try {
@@ -86,14 +60,7 @@ function knownFeatures(root) {
   return names;
 }
 
-/**
- * Is the feature's authoritative feature.json COMMITTED on its own branch?
- *
- * Not "does the branch exist": `git worktree add -b morph/{f}` creates the
- * branch as a side effect, so branch-existence is true for every registered
- * worktree and proves nothing. The blob is the real evidence — it is where the
- * per-feature state model says the truth lives.
- */
+// Branch existence proves nothing (`worktree add -b` creates it); the committed blob does.
 function featureCommittedOnBranch(root, feature) {
   try {
     execFileSync('git', ['cat-file', '-e', `morph/${feature}:.morph/features/${feature}/feature.json`], {
@@ -105,29 +72,8 @@ function featureCommittedOnBranch(root, feature) {
   }
 }
 
-/**
- * Does this worktree's branch still hold work that is NOT in the default
- * branch, or an OPEN PR?
- *
- * This is the predicate that separates "an orphan directory to clean up" from
- * "the only copy of somebody's work". Two independent pieces of evidence, and
- * ANY of them is enough to protect the worktree:
- *
- *   1. commits the default branch does not have (`git rev-list base..branch`)
- *   2. an OPEN pull request on that branch
- *
- * Fail-CLOSED, and that asymmetry is the whole design: whenever the answer
- * cannot be established — no default branch, no origin, git errored — the
- * worktree counts as UNINTEGRATED. The cost of being wrong that way is a
- * diagnostic that stays quiet; the cost of the opposite is a suggestion to
- * delete work that exists nowhere else.
- *
- * A squash-merged branch legitimately reports commits ahead, so the tree
- * comparison (`branch-classifier.js`) is consulted for the same reason
- * `branch prune` needs it — the two must not disagree about "is this in".
- *
- * @returns {{ unintegrated: boolean, evidence: string, pr: number|null }}
- */
+// Fail-CLOSED: when integration cannot be established the worktree counts as
+// unintegrated — a quiet diagnostic beats suggesting to delete the only copy.
 function unintegratedWork(root, branchRef, prIndex) {
   const branch = (branchRef || '').replace(/^refs\/heads\//, '');
   if (!branch) return { unintegrated: true, evidence: 'não foi possível resolver a branch do worktree', pr: null };
@@ -143,9 +89,7 @@ function unintegratedWork(root, branchRef, prIndex) {
   if (ahead === null) return { unintegrated: true, evidence: `não foi possível comparar com ${baseRef}`, pr: null };
   if (ahead === 0) return { unintegrated: false, evidence: `nenhum commit fora de ${baseRef}`, pr: pr?.number ?? null };
 
-  // Commits ahead, but the work may still be IN: a squash-merge leaves exactly
-  // that shape. Reuse the classifier so `doctor` and `branch prune` cannot
-  // reach opposite conclusions about the same branch.
+  // A squash-merge also leaves commits ahead; the classifier keeps `doctor` and `branch prune` agreeing.
   const verdict = classifyBranch({ name: branch, sha: '', current: false, worktreePath: null }, { baseRef, cwd: root, pr });
   if (verdict.kind === 'merged-ancestral' || verdict.kind === 'merged-squash') {
     return { unintegrated: false, evidence: verdict.reason, pr: pr?.number ?? null };
@@ -153,19 +97,6 @@ function unintegratedWork(root, branchRef, prIndex) {
   return { unintegrated: true, evidence: `${ahead} commit(s) fora de ${baseRef}`, pr: pr?.number ?? null };
 }
 
-/**
- * Every feature's `worktree` registration in the primary root — the OTHER
- * direction from `knownFeatures`/`dirsOnDisk`: not "does git/disk know about
- * this worktree", but "does the ROOT's feature.json still point somewhere
- * real". `create --worktree` writes this pointer once at birth
- * (`{path, branch, createdAt}`) and nothing updates it afterwards except
- * `finish`'s own teardown — so a directory removed any other way (by hand,
- * `git worktree prune` run directly, a failed teardown that still cleared the
- * field, an unrelated script) leaves it dangling with nothing to notice.
- *
- * @param {string} root
- * @returns {Array<{ feature: string, path: string, branch: string|null }>}
- */
 function featureRegistrations(root) {
   const out = [];
   try {
@@ -183,23 +114,15 @@ function featureRegistrations(root) {
   return out;
 }
 
-/**
- * Is this directory literally empty — zero entries, dotfiles included?
- *
- * The whole point of the distinction: an empty residue holds nothing that can
- * be lost, so it can be removed without a human looking at it. Anything else —
- * including a directory we cannot read — is reported as NON-empty, because the
- * safe answer to "might there be work in here?" is yes.
- */
+// Unreadable counts as occupied: emptiness is what licenses automatic removal.
 function isEmptyDir(path) {
   try {
     return readdirSync(path).length === 0;
   } catch {
-    return false; // unreadable → treat as occupied
+    return false;
   }
 }
 
-/** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
   const rootNorm = norm(root);
@@ -221,53 +144,8 @@ function dirsOnDisk(root) {
 }
 
 /**
- * Reconcile git's registry, the disk and morph's features.
- *
- * Issue types:
- *   • registered-missing        — git has a worktree whose directory is gone
- *   • non-morph-branch          — a registered worktree under worktrees/ on a
- *                                 branch that is not `morph/*`, so `fleet`
- *                                 cannot see it
- *   • unregistered-dir          — a directory under worktrees/ git never
- *                                 registered
- *   • no-feature                — a `morph/{f}` worktree for a feature morph
- *                                 does not know AND whose branch carries
- *                                 nothing that is not already integrated
- *   • unintegrated-work (info)  — the same shape, except the branch still holds
- *                                 commits the default does not, or an OPEN PR.
- *                                 Reported so the reader knows why no removal
- *                                 is suggested — this worktree may be the ONLY
- *                                 copy of the work
- *   • dangling-registration     — a feature's ROOT feature.json still points
- *                                 at a `worktree.path` that no longer exists
- *                                 (the symmetric OTHER direction from
- *                                 `no-feature`: the worktree is gone, but the
- *                                 root's pointer to it survived)
- *   • unregistered-registration — a feature's `worktree.path` names a
- *                                 directory that exists but git's own
- *                                 registry does not know as a worktree
- *
- *   • agent-worktree-leftover (info) — a sub-agent's `agent-<hex>` tree or
- *                                 `morph-task/agent-<hex>` branch left behind:
- *                                 `reapable` when the agent stopped and nothing
- *                                 is lost, otherwise the reason it is kept
- *
- *   • docker-stack-orphan (warn) — a `morph-*` docker stack of this repository
- *                                 still running for a feature this tree does
- *                                 not know, and
- *   • docker-port-held (warn)    — a port from a feature's block published by
- *                                 another compose project. Both come from
- *                                 `docker-audit.js`: the three sources above
- *                                 cannot see a CONTAINER, and a stack outlives
- *                                 every one of them
- *
- * @param {string} [cwd]
- * @param {object} [opts]
- * @param {Function} [opts.exec] - injectable executor handed to the docker
- *   audit, so the docker paths are testable with no daemon (the CI runners
- *   have none). Absent, the real `docker` CLI is used — and answers `[]` when
- *   it is not installed.
- * @returns {Array<{ type: string, detail: string, path?: string, feature?: string, fix: string }>}
+ * Reconciles git's worktree registry, the disk, morph's features and docker.
+ * Read-only and fail-open; `exec` is the docker executor seam.
  */
 export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   if (!isGitRepo(cwd)) return [];
@@ -275,9 +153,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   const rootNorm = norm(root);
   const issues = [];
 
-  // ONE `gh pr list` for the whole audit — null means UNKNOWN (no gh, not
-  // GitHub, not authenticated), never "no PRs"; `unintegratedWork` treats the
-  // two differently on purpose.
+  // null = UNKNOWN (no gh / not GitHub / unauthenticated), never "no PRs".
   const prIndex = buildPrIndex(root);
 
   const containers = containerDirs(root);
@@ -288,7 +164,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   for (const entry of registered) {
     const path = norm(entry.path);
     registeredPaths.add(path);
-    if (path === rootNorm) continue; // the primary root is not a worktree orphan
+    if (path === rootNorm) continue;
 
     if (!existsSync(path)) {
       issues.push({
@@ -306,12 +182,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       const task = entry.branch?.match(/^refs\/heads\/morph-task\/(.+)$/)?.[1] || null;
 
       if (!inContainer) {
-        // A worktree OUTSIDE morph's container was created behind morph's back
-        // (a native Claude Code run before the WorktreeCreate hook, a raw
-        // `git worktree add ../x`, another skill). It has no junctions, no port
-        // block, and nothing morph runs there — the exact shape that let a
-        // root's `.claude/` be emptied. Reported as `warn` (never a failure,
-        // NEVER pruned): the work inside may be the only copy.
+        // Never pruned: the work inside a tree created outside morph may be the only copy.
         const work = unintegratedWork(root, entry.branch, prIndex);
         issues.push({
           type: 'out-of-container',
@@ -327,10 +198,6 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
 
       if (task) {
         if (AGENT_TASK.test(task)) continue; // reported once, by the agent plan below
-        // `morph-task/*`: a task-isolation tree provisioned by the WorktreeCreate
-        // hook. Clean → nothing to say (the orchestrator removes it after the
-        // merge). With commits the default does not have → report, never
-        // suggest removal.
         const work = unintegratedWork(root, entry.branch, prIndex);
         if (work.unintegrated) {
           issues.push({
@@ -345,11 +212,6 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       }
 
       if (inContainer) {
-        // Same hazard as `no-feature` below, and it needs the same guard:
-        // "invisible to fleet" says nothing about whether the WORK is safe
-        // elsewhere. A worktree on a `feat/*` branch with an open PR is the
-        // most normal thing in the world, and suggesting its removal is a
-        // suggestion to destroy the only copy.
         const work = unintegratedWork(root, entry.branch, prIndex);
         issues.push(work.unintegrated
           ? {
@@ -365,10 +227,8 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
             type: 'non-morph-branch',
             path,
             detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga (e não há trabalho pendente: ${work.evidence})`,
-            // NEVER raw `git worktree remove` here: it follows the infra junctions
-            // out and empties the primary root's .claude/ and .morph/framework/.
-            // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
-            // --target precisely for worktrees like this one, with no feature.
+            // Never raw `git worktree remove`: it follows the infra junctions and
+            // empties the root's .claude/ and .morph/framework/.
             fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
           });
       }
@@ -376,13 +236,8 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
     }
 
     if (!features.has(feature) && !featureCommittedOnBranch(root, feature)) {
-      // "sem feature conhecida" is a bookkeeping fact, NOT a verdict on the
-      // work: a `finish` that archived the feature leaves exactly this shape,
-      // and so does a worktree whose PR is still open. In the observed session
-      // this branch recommended `worktree remove --target` for a worktree
-      // holding the ONLY copy of an open PR with 12 tasks and a 9.5 at Gate 3.
-      // So the diagnosis now depends on whether the WORK is integrated, and the
-      // suggestion to destroy appears only when it provably is.
+      // An archived feature or an open PR leaves this same shape: suggest removal
+      // only when the work is provably integrated.
       const work = unintegratedWork(root, entry.branch, prIndex);
       if (work.unintegrated) {
         issues.push({
@@ -420,19 +275,12 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
       detail: d.empty
         ? `${d.container}/${d.name} existe no disco, está VAZIO e o git não o registra — resíduo de um finish anterior`
         : `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
-      // An empty folder has nothing to lose, so it gets the automatic repair.
-      // One with content keeps the manual chore: there may be work in there,
-      // and the whole PROVE-or-DECLINE discipline exists for exactly that.
       fix: d.empty
         ? `morph-spec doctor --worktrees --prune`
         : `apague o diretório à mão depois de conferir que nada importante ficou nele`,
     });
   }
 
-  // The other direction: does the ROOT's own bookkeeping still point at a
-  // live worktree? `git worktree list`/disk only see what's PHYSICALLY
-  // there; a registration surviving past its worktree's removal is invisible
-  // to every check above.
   for (const reg of featureRegistrations(root)) {
     const path = norm(reg.path);
     if (!existsSync(reg.path)) {
@@ -454,13 +302,7 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
     }
   }
 
-  // The fourth source, and the only one that is not a file: the docker stacks.
-  // A container survives the removal of the worktree, of the branch and of the
-  // feature — none of the three reconciliations above can see it, and it keeps
-  // holding the feature's port block. The feature names come from HERE (the
-  // ones morph knows plus the ones the registered `morph/*` worktrees carry)
-  // rather than from a second scan inside docker-audit: two readings of the
-  // same fact are two chances to disagree about which stack is orphaned.
+  // Feature names are passed in so docker-audit never rescans and disagrees.
   const treeFeatures = new Set(features);
   for (const entry of registered) {
     const f = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1];
@@ -468,31 +310,13 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   }
   issues.push(...auditDockerStacks(root, { exec, features: treeFeatures }));
 
-  // What a worktree removal leaves behind in `.git/morph-spec/finish-backup/`
-  // past its retention — `warn`, pruned by `--prune` and by the next finish.
   issues.push(...auditFinishBackups(root));
 
   return issues;
 }
 
-/**
- * Remove the EMPTY directories under `worktrees/`/`.worktrees/` that git does
- * not register — the residue a finish leaves behind.
- *
- * "Empty" is the whole licence to act: a folder with zero entries cannot be
- * hiding uncommitted work, so asking a human about it is pure ceremony, and
- * the audit that only warns leaves it there forever. A directory with anything
- * in it keeps the manual path.
- *
- * Two guards beyond the emptiness check:
- *   • only directories directly inside morph's own worktree containers, never
- *     the containers themselves and never a path git registers;
- *   • `rmdirSync`, not `rm -rf` — it REFUSES a non-empty directory, so a file
- *     that appears between the check and the call is a failure, not a loss.
- *
- * @param {string} root
- * @returns {string[]} paths actually removed
- */
+// `rmdirSync`, never `rm -rf`: a file that appears after the emptiness check
+// makes it fail instead of being lost.
 function removeEmptyUnregisteredDirs(root) {
   const registeredPaths = new Set(parseWorktreeList(root).map((e) => norm(e.path)));
   const removed = [];
@@ -507,25 +331,9 @@ function removeEmptyUnregisteredDirs(root) {
 }
 
 /**
- * Drop git's admin records for worktrees whose directory is already gone,
- * remove the EMPTY unregistered residue directories, AND clear any feature's
- * `worktree` registration that names a directory that is now gone.
- *
- * These three are the ONLY prune offered, on purpose: none can destroy
- * anything, because everything they touch is either already absent from disk
- * or provably empty. Removing a directory that still HOLDS something is
- * exactly the operation that needs a human looking at it.
- *
- * Order is load-bearing: the empty directories go first, so a root pointer
- * naming one of them becomes dangling in time for the registration sweep below
- * to clear it — one command, not two runs.
- *
- * `clearDanglingWorktreeRegistration` re-checks the dangling predicate itself
- * (path unset, or still exists → no-op) rather than trusting a pre-computed
- * list, so this stays correct even called against a stale audit snapshot.
- *
- * @param {string} [cwd]
- * @returns {Promise<{ pruned: boolean, error?: string, removedEmptyDirs: string[], clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
+ * Touches only what is already gone from disk or provably empty. Order matters:
+ * empty dirs go first so a root pointer to one becomes dangling and is cleared
+ * in the same run.
  */
 export async function pruneWorktrees(cwd = process.cwd()) {
   if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', removedEmptyDirs: [], clearedRegistrations: [] };

package/src/lib/worktree/worktree-include.js

@@ -9,11 +9,9 @@ const NESTED_GIT = /(^|\/)\.git(\/|$)/;
 const gitOut = (cwd, args, input) => execFileSync('git', args, { cwd, stdio: ['pipe', 'pipe', 'ignore'], encoding: 'utf8', input });
 
 /**
- * Claude Code's `.worktreeinclude` for a worktree morph-spec creates (a WorktreeCreate hook replaces
- * the native creation, so the native copy never runs): files matching a pattern AND gitignored in the
- * tree are copied when the tree lacks them. Real files only; build artifacts and `node_modules` never.
- *
- * @returns {string[]} relative paths copied
+ * `.worktreeinclude` parity: a WorktreeCreate hook replaces the native creation, so the native copy
+ * never runs. Copies files matching a pattern AND gitignored in the tree, when the tree lacks them;
+ * never build artifacts or `node_modules`. Returns the relative paths copied.
  */
 export function copyWorktreeIncludes(worktreePath, root) {
   const file = join(root, INCLUDE_FILE);

package/src/scripts/global-install.js

@@ -1,4 +1,3 @@
-// src/scripts/global-install.js
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir, platform } from 'os';
@@ -10,10 +9,7 @@ import { installGlobalStatusline } from '../utils/hooks-installer.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
 
-/**
- * Ensure the npm global bin directory is in the user's PATH on Windows.
- * Adds it to the PowerShell $PROFILE so new terminals find `morph-spec`.
- */
+/** Windows only: adds the npm global bin to the PowerShell $PROFILE so new terminals find `morph-spec`. */
 export async function ensureNpmGlobalInPath() {
   if (platform() !== 'win32') return;
 
@@ -21,12 +17,11 @@ export async function ensureNpmGlobalInPath() {
   try {
     npmGlobalDir = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
   } catch {
-    return; // can't determine npm global dir
+    return;
   }
 
   if (!npmGlobalDir || !existsSync(npmGlobalDir)) return;
 
-  // --- PowerShell $PROFILE ---
   const psProfile = join(homedir(), 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
   const psProfileLegacy = join(homedir(), 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1');
 
@@ -44,7 +39,7 @@ export async function ensureNpmGlobalInPath() {
       let content = '';
       if (existsSync(profilePath)) {
         content = await readFile(profilePath, 'utf8');
-        if (content.includes(marker)) continue; // already patched
+        if (content.includes(marker)) continue;
       } else {
         await mkdir(dirname(profilePath), { recursive: true });
       }
@@ -56,7 +51,6 @@ export async function ensureNpmGlobalInPath() {
   }
 }
 
-// Run as postinstall script
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
   const { readFileSync } = await import('fs');

package/src/scripts/install-plugin.js

@@ -1,4 +1,3 @@
-// src/scripts/install-plugin.js
 import { join } from 'path';
 import { homedir } from 'os';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
@@ -10,7 +9,6 @@ const CACHE_DIR = join(PLUGINS_DIR, 'cache', 'claude-plugins-official');
 const INSTALLED_FILE = join(PLUGINS_DIR, 'installed_plugins.json');
 const GH_REPO = 'anthropics/claude-plugins-official';
 
-/** Fetch JSON from GitHub API (no auth — public repo) */
 async function fetchGitHub(path) {
   return new Promise((resolve, reject) => {
     const opts = {
@@ -29,7 +27,6 @@ async function fetchGitHub(path) {
   });
 }
 
-/** Download raw file content from a URL, following one redirect */
 async function downloadFile(rawUrl) {
   return new Promise((resolve, reject) => {
     const doGet = (url) => {
@@ -51,25 +48,21 @@ async function downloadFile(rawUrl) {
   });
 }
 
-/** Read installed_plugins.json safely */
 export function readInstalledPlugins() {
   if (!existsSync(INSTALLED_FILE)) return { version: 2, plugins: {} };
   try { return JSON.parse(readFileSync(INSTALLED_FILE, 'utf8')); }
   catch { return { version: 2, plugins: {} }; }
 }
 
-/** Check if plugin key exists in the plugins map */
 export function isPluginInstalled(plugins, name) {
   return `${name}@claude-plugins-official` in plugins;
 }
 
-/** Build an installed_plugins.json entry */
 export function buildInstallEntry(pluginName, installPath, gitCommitSha, version) {
   const now = new Date().toISOString();
   return { scope: 'user', installPath, version, installedAt: now, lastUpdated: now, gitCommitSha };
 }
 
-/** Resolve latest commit SHA for a plugin path in the repo */
 export async function resolvePluginVersion(pluginName) {
   const commits = await fetchGitHub(`/repos/${GH_REPO}/commits?path=${pluginName}&per_page=1`);
   if (!Array.isArray(commits) || commits.length === 0) {
@@ -79,7 +72,6 @@ export async function resolvePluginVersion(pluginName) {
   return { sha, shortSha: sha.slice(0, 12) };
 }
 
-/** Download all files for a plugin from the repo tree */
 async function downloadPluginFiles(pluginName, sha, destDir) {
   const tree = await fetchGitHub(`/repos/${GH_REPO}/git/trees/${sha}?recursive=1`);
   if (!tree.tree) throw new Error('GitHub tree API returned unexpected shape');
@@ -98,11 +90,7 @@ async function downloadPluginFiles(pluginName, sha, destDir) {
   }
 }
 
-/**
- * Install a Claude Code plugin from GitHub.
- * @param {string} pluginName - e.g. "context7"
- * @returns {{ installed: boolean, version: string, alreadyInstalled: boolean }}
- */
+/** @returns {{ installed: boolean, version: string, alreadyInstalled: boolean }} */
 export async function installPlugin(pluginName) {
   const data = readInstalledPlugins();
   if (isPluginInstalled(data.plugins, pluginName)) {