supered 0.2.0 → 0.3.0

package/lib/package-verification.js

@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { HOST_TARGETS, SKILL_ORDER } from "./supered-policy.js";
+
+const execFileAsync = promisify(execFile);
+const npmPackEnv = {
+  ...process.env,
+  npm_config_dry_run: "false"
+};
+
+export const PACKAGE_TARGETS = Object.keys(HOST_TARGETS);
+export const REQUIRED_PACKAGE_FILES = [
+  ".claude-plugin/",
+  ".codex-plugin/",
+  ".cursor-plugin/",
+  ".opencode/",
+  "1.svg",
+  "assets/",
+  "bin/",
+  "docs/",
+  "gemini-extension.json",
+  "install.sh",
+  "lib/",
+  "skills/",
+  "README.md",
+  "LICENSE"
+];
+export const EXCLUDED_PACKAGE_PREFIXES = [
+  "tests/",
+  "artifacts/",
+  "node_modules/"
+];
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function packageFilePaths(pack) {
+  return pack.files.map((file) => file.path);
+}
+
+export function inspectPackageFiles(files) {
+  return {
+    missingRequiredFiles: REQUIRED_PACKAGE_FILES.filter((path) => {
+      if (path.endsWith("/")) {
+        return !files.some((file) => file.startsWith(path));
+      }
+      return !files.includes(path);
+    }),
+    excludedFileViolations: files.filter((file) => EXCLUDED_PACKAGE_PREFIXES.some((prefix) => file.startsWith(prefix)))
+  };
+}
+
+export async function verifyNpmPackage({ root = process.cwd(), tempRoot } = {}) {
+  const workRoot = tempRoot ?? await mkdtemp(join(tmpdir(), "supered-package-"));
+  const cleanup = !tempRoot;
+
+  try {
+    const packageJson = await readJson(join(root, "package.json"));
+    const { stdout } = await execFileAsync("npm", ["pack", "--pack-destination", workRoot, "--json"], {
+      cwd: root,
+      env: npmPackEnv
+    });
+    const [pack] = JSON.parse(stdout);
+    const tarball = join(workRoot, pack.filename);
+    await stat(tarball);
+
+    const files = packageFilePaths(pack);
+    const fileInspection = inspectPackageFiles(files);
+
+    if (fileInspection.missingRequiredFiles.length > 0) {
+      throw new Error(`Npm package is missing required files: ${fileInspection.missingRequiredFiles.join(", ")}`);
+    }
+    if (fileInspection.excludedFileViolations.length > 0) {
+      throw new Error(`Npm package includes local-only files: ${fileInspection.excludedFileViolations.join(", ")}`);
+    }
+
+    for (const target of PACKAGE_TARGETS) {
+      const dest = join(workRoot, target);
+      await execFileAsync(
+        "npm",
+        ["exec", "--yes", "--package", tarball, "--", "supered", "install", "--target", target, "--dest", dest],
+        { cwd: root, env: npmPackEnv }
+      );
+
+      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 = {
+      packageName: packageJson.name,
+      version: packageJson.version,
+      tarballName: pack.filename,
+      files,
+      installedTargets: [...PACKAGE_TARGETS],
+      doctorTargets: [...PACKAGE_TARGETS],
+      installedSkills: [...SKILL_ORDER],
+      ...fileInspection
+    };
+    if (!cleanup) {
+      result.tarball = tarball;
+    }
+    return result;
+  } finally {
+    if (cleanup) {
+      await rm(workRoot, { recursive: true, force: true });
+    }
+  }
+}

package/lib/release-bundle.js

@@ -0,0 +1,135 @@
+import { access, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+import { collectManifest, listSkills } from "./manifest.js";
+import { REQUIRED_PACKAGE_FILES } from "./package-verification.js";
+import { HOST_TARGETS, SKILL_ORDER } from "./supered-policy.js";
+
+async function readText(root, path) {
+  return readFile(join(root, path), "utf8");
+}
+
+function add(errorList, condition, message) {
+  if (!condition) {
+    errorList.push(message);
+  }
+}
+
+function pushChecked(checked, paths) {
+  for (const path of paths) {
+    if (!checked.includes(path)) {
+      checked.push(path);
+    }
+  }
+}
+
+export async function validateReleaseBundle(root = process.cwd()) {
+  const errors = [];
+  const checked = [];
+  const manifest = await collectManifest(root);
+  const version = manifest.package.version;
+  const hostTargets = Object.keys(HOST_TARGETS);
+
+  pushChecked(checked, [
+    "package.json",
+    ".codex-plugin/plugin.json",
+    ".claude-plugin/plugin.json",
+    ".cursor-plugin/plugin.json",
+    "gemini-extension.json"
+  ]);
+
+  add(errors, manifest.package.name === "supered", "package.json name must be supered");
+  add(errors, manifest.package.publishConfig?.access === "public", "package.json publishConfig.access must be public");
+  add(errors, manifest.package.bin?.supered === "bin/supered.mjs", "package.json bin.supered must point at bin/supered.mjs");
+  add(errors, manifest.package.scripts?.["verify-site"] === "node ./scripts/verify-site.mjs", "verify-site script is missing");
+  add(
+    errors,
+    manifest.package.scripts?.["verify-package"] === "node ./scripts/verify-npm-package.mjs",
+    "verify-package script is missing"
+  );
+  add(
+    errors,
+    JSON.stringify(manifest.package.files) === JSON.stringify(REQUIRED_PACKAGE_FILES),
+    "package.json files list is not aligned"
+  );
+
+  add(errors, manifest.codexPlugin.name === "supered", ".codex-plugin/plugin.json name must be supered");
+  add(errors, manifest.codexPlugin.version === version, "Codex plugin version must match package.json");
+  add(errors, manifest.claudePlugin.version === version, "Claude plugin version must match package.json");
+  add(errors, manifest.cursorPlugin.version === version, "Cursor plugin version must match package.json");
+  add(errors, manifest.geminiExtension.version === version, "Gemini extension version must match package.json");
+  add(errors, manifest.codexPlugin.interface?.displayName === "Supered", "Codex plugin displayName must be Supered");
+  add(errors, manifest.codexPlugin.skills === "./skills/", "Codex plugin skills path must be ./skills/");
+  add(
+    errors,
+    JSON.stringify(manifest.codexPlugin.interface?.screenshots ?? []) === JSON.stringify(["./docs/preview.svg"]),
+    "Codex plugin screenshots must include docs preview"
+  );
+
+  const logoPath = manifest.codexPlugin.interface?.logo?.replace(/^\.\//, "");
+  if (logoPath) {
+    pushChecked(checked, [logoPath]);
+    try {
+      await access(join(root, logoPath));
+    } catch {
+      errors.push(`Missing logo file: ${logoPath}`);
+    }
+  } else {
+    errors.push("Codex plugin interface.logo is required");
+  }
+
+  const skills = await listSkills(root);
+  for (const skill of skills) {
+    checked.push(relative(root, skill.path));
+    add(errors, Boolean(skill.name), `${relative(root, skill.path)} is missing a name`);
+    add(errors, Boolean(skill.description), `${relative(root, skill.path)} is missing a description`);
+    add(errors, /^# /m.test(skill.body), `${relative(root, skill.path)} is missing an H1`);
+  }
+
+  const skillNames = skills.map((skill) => skill.name);
+  for (const expected of SKILL_ORDER) {
+    add(errors, skillNames.includes(expected), `Missing skill: ${expected}`);
+  }
+
+  pushChecked(checked, [
+    ".github/workflows/ci.yml",
+    "RELEASE_NOTES.md",
+    "docs/roadmap.md",
+    "docs/marketplace-checklist.md",
+    "docs/index.html",
+    "README.md",
+    "install.sh"
+  ]);
+
+  const ci = await readText(root, ".github/workflows/ci.yml");
+  for (const command of ["npm ci", "npm test", "npm run validate", "npm run smoke-install", "npm run verify-package", "npm run verify-site"]) {
+    add(errors, ci.includes(command), `CI must run ${command}`);
+  }
+
+  const releaseNotes = await readText(root, "RELEASE_NOTES.md");
+  add(errors, releaseNotes.includes(`# Supered v${version}`), `Release notes must include v${version}`);
+
+  const roadmap = await readText(root, "docs/roadmap.md");
+  add(errors, /^# Supered Roadmap/m.test(roadmap), "Roadmap must have a Supered heading");
+
+  const marketplace = await readText(root, "docs/marketplace-checklist.md");
+  add(errors, marketplace.includes("install.sh"), "Marketplace checklist must mention install.sh");
+  add(errors, marketplace.includes("verify-package"), "Marketplace checklist must mention package verification");
+
+  for (const host of hostTargets) {
+    const hostDoc = `docs/hosts/${host}.md`;
+    pushChecked(checked, [hostDoc]);
+    const doc = await readText(root, hostDoc);
+    add(errors, new RegExp(`# .*${host}`, "i").test(doc), `${hostDoc} must name the host`);
+    add(errors, doc.includes("install.sh"), `${hostDoc} must mention install.sh`);
+    add(errors, /SUPERED_TARGET|--target/.test(doc), `${hostDoc} must document target selection`);
+  }
+
+  return {
+    errors,
+    checked,
+    skills,
+    version,
+    hostTargets
+  };
+}

package/lib/supered-policy.js

@@ -0,0 +1,32 @@
+import { join } from "node:path";
+
+export const SKILL_ORDER = [
+  "using-supered",
+  "shape-the-task",
+  "make-a-map",
+  "build-in-slices",
+  "trace-the-fault",
+  "prove-the-change",
+  "ship-the-work"
+];
+
+export const HOST_TARGETS = {
+  codex: ".codex/skills",
+  claude: ".claude/skills",
+  cursor: ".cursor/skills",
+  gemini: ".gemini/skills",
+  opencode: ".opencode/skills"
+};
+
+export function defaultInstallDest(target, home = process.env.HOME) {
+  if (!home) {
+    throw new Error("HOME is not set; pass --dest explicitly.");
+  }
+
+  const targetPath = HOST_TARGETS[target];
+  if (!targetPath) {
+    throw new Error(`Unsupported target: ${target}`);
+  }
+
+  return join(home, targetPath);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.0",
+  "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/",