supered 0.2.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Small, evidence-first workflows for coding agents.",
   "author": {
     "name": "Farouk Hajjej",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
   "author": {
     "name": "Farouk Hajjej",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Small, evidence-first workflows for coding agents.",
   "homepage": "https://fhajjej-ship-it.github.io/Supered/",
   "license": "MIT",

package/README.md

@@ -30,6 +30,12 @@ Install with npx:
 npx supered install --target codex
 ```
 
+Check the install:
+
+```bash
+npx supered doctor --target codex
+```
+
 Or install the default Codex skill set with curl:
 
 ```bash
@@ -50,6 +56,7 @@ cd Supered
 npm test
 npm run validate
 node ./bin/supered.mjs install --target codex
+node ./bin/supered.mjs doctor --target codex
 ```
 
 For Claude or Gemini, replace `codex` with `claude` or `gemini`.
@@ -91,13 +98,14 @@ npm run smoke-install
 npm run verify-site
 npm run verify-package
 node ./bin/supered.mjs skills --json
+node ./bin/supered.mjs doctor --target codex --json
 ```
 
 The validator checks package metadata, plugin metadata, and skill frontmatter so the public repo does not drift into a half-installable state.
 
 `npm run verify-site` opens the landing page in Chromium at desktop and mobile sizes, checks the logo and workflow text, and writes screenshots to `artifacts/site/`.
 
-`npm run verify-package` builds the npm tarball and verifies `npx`-style installs for every supported host target.
+`npm run verify-package` builds the npm tarball and verifies `npx`-style installs plus Doctor checks for every supported host target.
 
 ## Design Principles
 

package/bin/supered.mjs

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { installSuperedSkills } from "../lib/host-install.js";
+import { inspectSuperedInstall } from "../lib/install-doctor.js";
 import { listSkills } from "../lib/manifest.js";
 import { validateReleaseBundle } from "../lib/release-bundle.js";
 
@@ -16,10 +17,12 @@ Usage:
   supered skills [--json]
   supered validate
   supered install --target <codex|claude|cursor|gemini|opencode> [--dest <path>]
+  supered doctor --target <codex|claude|cursor|gemini|opencode> [--dest <path>] [--json]
 
 Examples:
   npx supered install --target codex
   npx supered install --target gemini --dest ~/.gemini/skills
+  supered doctor --target codex
 `);
 }
 
@@ -62,6 +65,40 @@ async function installCommand() {
   console.log(`Installed Supered skills for ${result.target} at ${result.dest}.`);
 }
 
+async function doctorCommand() {
+  const targetIndex = args.indexOf("--target");
+  const destIndex = args.indexOf("--dest");
+  const target = targetIndex === -1 ? "" : args[targetIndex + 1];
+  const dest = destIndex === -1 ? undefined : args[destIndex + 1];
+  const json = args.includes("--json");
+
+  if (!target || (destIndex !== -1 && !dest)) {
+    throw new Error("Doctor requires --target <codex|claude|cursor|gemini|opencode>.");
+  }
+
+  const result = await inspectSuperedInstall({ root, target, dest });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status !== "ok") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (result.status === "ok") {
+    console.log(`Supered doctor passed for ${result.target} at ${result.dest}.`);
+    console.log(`${result.installedSkills.length} skills installed and current.`);
+    return;
+  }
+
+  console.log(`Supered doctor found ${result.issues.length} issue${result.issues.length === 1 ? "" : "s"} for ${result.target} at ${result.dest}.`);
+  for (const installIssue of result.issues) {
+    console.log(`- [${installIssue.code}] ${installIssue.message}`);
+  }
+  console.log(`Fix: ${result.fixCommand}`);
+  process.exitCode = 1;
+}
+
 try {
   if (!command || command === "help" || command === "--help") {
     printHelp();
@@ -71,6 +108,8 @@ try {
     await validateCommand();
   } else if (command === "install") {
     await installCommand();
+  } else if (command === "doctor") {
+    await doctorCommand();
   } else {
     throw new Error(`Unknown command: ${command}`);
   }

package/docs/install.md

@@ -6,12 +6,14 @@ Supered ships plain skill folders plus lightweight plugin manifests.
 
 ```bash
 npx supered install --target codex
+npx supered doctor --target codex
 ```
 
 Choose another host:
 
 ```bash
 npx supered install --target opencode
+npx supered doctor --target opencode
 ```
 
 ## One-line install
@@ -30,20 +32,34 @@ curl -fsSL https://raw.githubusercontent.com/fhajjej-ship-it/Supered/main/instal
 
 ```bash
 node ./bin/supered.mjs install --target codex
+node ./bin/supered.mjs doctor --target codex
 ```
 
 ## Claude
 
 ```bash
 node ./bin/supered.mjs install --target claude
+node ./bin/supered.mjs doctor --target claude
 ```
 
 ## Gemini
 
 ```bash
 node ./bin/supered.mjs install --target gemini
+node ./bin/supered.mjs doctor --target gemini
 ```
 
+## Doctor
+
+Doctor checks Install Health without changing files:
+
+```bash
+supered doctor --target codex
+supered doctor --target codex --json
+```
+
+It reports missing skills, changed skill files, missing destinations, and unsafe symlinks. The fix it prints is a reinstall command for the same target and destination.
+
 ## Manual
 
 Copy each folder in `skills/` into the skill directory used by your agent host.

package/docs/roadmap.md

@@ -19,6 +19,7 @@
 
 ## v0.3
 
+- Install Health checks through `supered doctor`.
 - Skill authoring guide with contribution tests.
 - Release automation for tags, notes, and metadata checks.
 - Optional templates for repo launch checklists.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A compact workflow kit for agentic coding sessions.",
   "mcpServers": {},
   "contextFileName": "GEMINI.md"

package/lib/install-doctor.js

@@ -0,0 +1,181 @@
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { defaultInstallDest, SKILL_ORDER } from "./supered-policy.js";
+
+function shellQuote(value) {
+  if (!/[\s'"\\]/.test(value)) {
+    return value;
+  }
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function fixCommand(target, dest) {
+  return `npx supered@latest install --target ${target} --dest ${shellQuote(dest)}`;
+}
+
+function issue(code, message, extra = {}) {
+  return {
+    code,
+    message,
+    ...extra
+  };
+}
+
+async function lstatOrNull(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function findSymlink(path) {
+  const entry = await lstatOrNull(path);
+  if (!entry) {
+    return null;
+  }
+  if (entry.isSymbolicLink()) {
+    return path;
+  }
+  if (!entry.isDirectory()) {
+    return null;
+  }
+
+  const children = await readdir(path);
+  for (const child of children) {
+    const linked = await findSymlink(join(path, child));
+    if (linked) {
+      return linked;
+    }
+  }
+  return null;
+}
+
+async function readInstalledSkill(dest, skill) {
+  const skillDir = join(dest, skill);
+  const linked = await findSymlink(skillDir);
+  if (linked) {
+    return {
+      linked
+    };
+  }
+
+  const skillFile = join(skillDir, "SKILL.md");
+  const fileStat = await lstatOrNull(skillFile);
+  if (!fileStat) {
+    return {
+      missing: true
+    };
+  }
+  if (fileStat.isSymbolicLink()) {
+    return {
+      linked: skillFile
+    };
+  }
+
+  return {
+    contents: await readFile(skillFile, "utf8")
+  };
+}
+
+export async function inspectSuperedInstall({ root = process.cwd(), target, dest, home = process.env.HOME } = {}) {
+  if (!target) {
+    throw new Error("Doctor requires --target.");
+  }
+
+  const installDest = dest ?? defaultInstallDest(target, home);
+  const sourceSkillsDir = resolve(root, "skills");
+  const issues = [];
+  const missingSkills = [];
+  const changedSkills = [];
+  const installedSkills = [];
+  const command = fixCommand(target, installDest);
+  const destStat = await lstatOrNull(installDest);
+
+  if (!destStat) {
+    return {
+      target,
+      dest: installDest,
+      status: "issues",
+      issues: [
+        issue("missing-destination", `Install destination does not exist: ${installDest}`, {
+          path: installDest
+        })
+      ],
+      installedSkills,
+      missingSkills: [...SKILL_ORDER],
+      changedSkills,
+      fixCommand: command
+    };
+  }
+
+  if (destStat.isSymbolicLink()) {
+    return {
+      target,
+      dest: installDest,
+      status: "issues",
+      issues: [
+        issue("symlinked-destination", `Install destination is a symlink: ${installDest}`, {
+          path: installDest
+        })
+      ],
+      installedSkills,
+      missingSkills,
+      changedSkills,
+      fixCommand: command
+    };
+  }
+
+  for (const skill of SKILL_ORDER) {
+    const expectedPath = join(sourceSkillsDir, skill, "SKILL.md");
+    const expected = await readFile(expectedPath, "utf8");
+    const installed = await readInstalledSkill(installDest, skill);
+
+    if (installed.linked) {
+      issues.push(
+        issue("unsafe-symlink", `Managed skill contains a symlink: ${installed.linked}`, {
+          skill,
+          path: installed.linked
+        })
+      );
+      continue;
+    }
+
+    if (installed.missing) {
+      missingSkills.push(skill);
+      issues.push(
+        issue("missing-skill", `Missing installed skill file: ${join(installDest, skill, "SKILL.md")}`, {
+          skill,
+          path: join(installDest, skill, "SKILL.md")
+        })
+      );
+      continue;
+    }
+
+    installedSkills.push(skill);
+    if (installed.contents !== expected) {
+      changedSkills.push(skill);
+      issues.push(
+        issue("changed-skill", `Installed skill differs from this Supered bundle: ${skill}`, {
+          skill,
+          path: join(installDest, skill, "SKILL.md")
+        })
+      );
+    }
+  }
+
+  return {
+    target,
+    dest: installDest,
+    status: issues.length === 0 ? "ok" : "issues",
+    issues,
+    installedSkills,
+    missingSkills,
+    changedSkills,
+    fixCommand: command
+  };
+}

package/lib/package-verification.js

@@ -90,6 +90,12 @@ export async function verifyNpmPackage({ root = process.cwd(), tempRoot } = {})
       for (const skill of SKILL_ORDER) {
         await stat(join(dest, skill, "SKILL.md"));
       }
+
+      await execFileAsync(
+        "npm",
+        ["exec", "--yes", "--package", tarball, "--", "supered", "doctor", "--target", target, "--dest", dest],
+        { cwd: root, env: npmPackEnv }
+      );
     }
 
     const result = {
@@ -98,6 +104,7 @@ export async function verifyNpmPackage({ root = process.cwd(), tempRoot } = {})
       tarballName: pack.filename,
       files,
       installedTargets: [...PACKAGE_TARGETS],
+      doctorTargets: [...PACKAGE_TARGETS],
       installedSkills: [...SKILL_ORDER],
       ...fileInspection
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
   "type": "module",
   "homepage": "https://fhajjej-ship-it.github.io/Supered/",