supered 0.1.3 → 0.2.1

package/gemini-extension.json

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

package/install.sh

@@ -6,6 +6,13 @@ SUPERED_REF="${SUPERED_REF:-main}"
 SUPERED_TARGET="${SUPERED_TARGET:-codex}"
 SUPERED_SOURCE_DIR="${SUPERED_SOURCE_DIR:-}"
 SUPERED_DEST="${SUPERED_DEST:-}"
+SUPERED_SKILLS='using-supered
+shape-the-task
+make-a-map
+build-in-slices
+trace-the-fault
+prove-the-change
+ship-the-work'
 
 usage() {
   cat <<'EOF'
@@ -71,6 +78,23 @@ default_dest() {
   esac
 }
 
+reject_symlink() {
+  [ ! -L "$1" ] || die "Refusing to install symlink: $1"
+}
+
+reject_source_symlinks() {
+  reject_symlink "$1"
+  linked="$(find "$1" -type l -print -quit)"
+  [ -z "$linked" ] || die "Refusing to install symlink: $linked"
+}
+
+reject_destination_symlinks() {
+  [ ! -L "$dest" ] || die "Refusing to install into symlinked destination: $dest"
+  for skill in $SUPERED_SKILLS; do
+    [ ! -L "$dest/$skill" ] || die "Refusing to install into symlinked destination: $dest/$skill"
+  done
+}
+
 download_source() {
   tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/supered.XXXXXX")"
   archive="$tmp_dir/supered.tar.gz"
@@ -100,7 +124,19 @@ if [ -z "$dest" ]; then
   dest="$(default_dest)"
 fi
 
+for skill in $SUPERED_SKILLS; do
+  skill_dir="$source_dir/skills/$skill"
+  [ -d "$skill_dir" ] || die "Missing skill directory: $skill_dir"
+  reject_source_symlinks "$skill_dir"
+  [ -f "$skill_dir/SKILL.md" ] || die "Missing skill file: $skill_dir/SKILL.md"
+done
+
+reject_destination_symlinks
 mkdir -p "$dest"
-cp -R "$source_dir/skills/." "$dest/"
+reject_destination_symlinks
+
+for skill in $SUPERED_SKILLS; do
+  cp -R "$source_dir/skills/$skill" "$dest/"
+done
 
 printf 'Installed Supered for %s at %s\n' "$SUPERED_TARGET" "$dest"

package/lib/eval-pack.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SKILL_ORDER } from "./supered-policy.js";
+
+export const EVAL_CATALOG_VERSION = "0.1";
+export const SCORING_DIMENSIONS = [
+  "clarity",
+  "actionability",
+  "guardrails",
+  "evidence",
+  "outcome"
+];
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function add(errorList, condition, message) {
+  if (!condition) {
+    errorList.push(message);
+  }
+}
+
+export async function readEvalPack(root = process.cwd()) {
+  return {
+    catalog: await readJson(join(root, "docs", "evals", "scenarios.json")),
+    report: await readJson(join(root, "docs", "evals", "baseline-results.json"))
+  };
+}
+
+export async function validateEvalPack(root = process.cwd()) {
+  const errors = [];
+  const { catalog, report } = await readEvalPack(root);
+  const scenarioIds = new Set();
+  const coveredSkills = new Set();
+
+  add(errors, catalog.product === "Supered", "Eval Pack catalog product must be Supered");
+  add(errors, catalog.version === EVAL_CATALOG_VERSION, `Eval Pack catalog version must be ${EVAL_CATALOG_VERSION}`);
+  add(errors, catalog.scoring?.maxScore === 5, "Eval Pack scoring maxScore must be 5");
+  add(
+    errors,
+    JSON.stringify(catalog.scoring?.dimensions ?? []) === JSON.stringify(SCORING_DIMENSIONS),
+    "Eval Pack scoring dimensions are not aligned"
+  );
+  add(errors, catalog.scenarios?.length === 10, "Eval Pack must include 10 scenarios");
+
+  for (const scenario of catalog.scenarios ?? []) {
+    add(errors, /^S\d{2}$/.test(scenario.id), `${scenario.id} must use an S00-style id`);
+    add(errors, !scenarioIds.has(scenario.id), `${scenario.id} must be unique`);
+    scenarioIds.add(scenario.id);
+
+    add(errors, scenario.title?.length >= 12, `${scenario.id} needs a specific title`);
+    add(errors, scenario.prompt?.length >= 80, `${scenario.id} prompt is too thin`);
+    add(errors, scenario.context?.length >= 80, `${scenario.id} context is too thin`);
+    add(errors, scenario.successCriteria?.length >= 3, `${scenario.id} needs success criteria`);
+    add(errors, scenario.expectedEvidence?.length >= 2, `${scenario.id} needs evidence expectations`);
+    add(errors, scenario.primarySkills?.length >= 1, `${scenario.id} needs a primary skill`);
+
+    for (const skill of scenario.primarySkills ?? []) {
+      coveredSkills.add(skill);
+      add(errors, SKILL_ORDER.includes(skill), `${scenario.id} references unknown skill ${skill}`);
+    }
+  }
+
+  for (const skill of SKILL_ORDER) {
+    add(errors, coveredSkills.has(skill), `Eval Pack does not exercise ${skill}`);
+  }
+
+  add(errors, report.product === "Supered", "Eval Pack report product must be Supered");
+  add(errors, report.catalogVersion === EVAL_CATALOG_VERSION, "Eval Pack report catalogVersion is not aligned");
+  add(errors, report.results?.length === 10, "Eval Pack report must include 10 results");
+  add(errors, report.summary?.averageScore >= 4.2, "Eval Pack baseline average should show useful outcomes");
+
+  for (const result of report.results ?? []) {
+    add(errors, scenarioIds.has(result.scenarioId), `${result.scenarioId} does not match a known scenario`);
+    add(
+      errors,
+      JSON.stringify(Object.keys(result.scores ?? {}).sort()) === JSON.stringify([...SCORING_DIMENSIONS].sort()),
+      `${result.scenarioId} scores must cover every scoring dimension`
+    );
+    for (const score of Object.values(result.scores ?? {})) {
+      add(errors, Number.isInteger(score), "Eval Pack scores must be integers");
+      add(errors, score >= 1 && score <= 5, "Eval Pack scores must be between 1 and 5");
+    }
+    add(errors, result.notes?.length >= 80, `${result.scenarioId} needs explanatory scoring notes`);
+    add(errors, result.recommendedSkill?.length > 0, `${result.scenarioId} needs a recommended skill`);
+  }
+
+  return {
+    errors,
+    catalog,
+    report,
+    summary: {
+      scenarioCount: catalog.scenarios?.length ?? 0,
+      resultCount: report.results?.length ?? 0,
+      averageScore: report.summary?.averageScore ?? 0,
+      coveredSkills: SKILL_ORDER.filter((skill) => coveredSkills.has(skill))
+    }
+  };
+}

package/lib/host-install.js

@@ -0,0 +1,88 @@
+import { cp, lstat, mkdir, readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { defaultInstallDest, SKILL_ORDER } from "./supered-policy.js";
+
+async function assertNoSymlinks(path) {
+  const entry = await lstat(path);
+  if (entry.isSymbolicLink()) {
+    throw new Error(`Refusing to install symlink: ${path}`);
+  }
+
+  if (!entry.isDirectory()) {
+    return;
+  }
+
+  const children = await readdir(path);
+  await Promise.all(children.map((child) => assertNoSymlinks(join(path, child))));
+}
+
+async function assertSkillIsInstallable(skillsDir, skill) {
+  const skillDir = join(skillsDir, skill);
+  await assertNoSymlinks(skillDir);
+
+  const skillFile = join(skillDir, "SKILL.md");
+  try {
+    await stat(skillFile);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Missing skill file: ${skillFile}`);
+    }
+    throw error;
+  }
+}
+
+async function assertDestinationPathIsSafe(dest) {
+  try {
+    const destination = await lstat(dest);
+    if (destination.isSymbolicLink()) {
+      throw new Error(`Refusing to install into symlinked destination: ${dest}`);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+async function assertManagedDestinationsAreSafe(dest) {
+  for (const skill of SKILL_ORDER) {
+    const skillDest = join(dest, skill);
+    try {
+      const destination = await lstat(skillDest);
+      if (destination.isSymbolicLink()) {
+        throw new Error(`Refusing to install into symlinked destination: ${skillDest}`);
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+}
+
+export async function installSuperedSkills({ root = process.cwd(), target, dest, home = process.env.HOME } = {}) {
+  if (!target) {
+    throw new Error("Install requires --target.");
+  }
+
+  const installDest = dest ?? defaultInstallDest(target, home);
+  const skillsDir = resolve(root, "skills");
+
+  await assertDestinationPathIsSafe(installDest);
+  await assertManagedDestinationsAreSafe(installDest);
+  for (const skill of SKILL_ORDER) {
+    await assertSkillIsInstallable(skillsDir, skill);
+  }
+
+  await mkdir(installDest, { recursive: true });
+  for (const skill of SKILL_ORDER) {
+    await cp(join(skillsDir, skill), join(installDest, skill), { recursive: true });
+  }
+
+  return {
+    target,
+    dest: installDest,
+    installedSkills: [...SKILL_ORDER]
+  };
+}

package/lib/manifest.js

@@ -1,15 +1,9 @@
-import { access, readFile, readdir } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { readFile, readdir } from "node:fs/promises";
+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"
-];
+import { SKILL_ORDER } from "./supered-policy.js";
+
+export { SKILL_ORDER } from "./supered-policy.js";
 
 async function readJson(path) {
   return JSON.parse(await readFile(path, "utf8"));
@@ -72,66 +66,6 @@ export async function collectManifest(root = process.cwd()) {
 }
 
 export async function validateProject(root = process.cwd()) {
-  const errors = [];
-  const checked = ["package.json"];
-  const manifest = await collectManifest(root);
-  checked.push(".codex-plugin/plugin.json");
-  checked.push(".claude-plugin/plugin.json");
-  checked.push(".cursor-plugin/plugin.json");
-  checked.push("gemini-extension.json");
-
-  if (manifest.package.name !== "supered") {
-    errors.push("package.json name must be supered");
-  }
-
-  if (manifest.codexPlugin.name !== "supered") {
-    errors.push(".codex-plugin/plugin.json name must be supered");
-  }
-
-  if (manifest.codexPlugin.interface?.displayName !== "Supered") {
-    errors.push("Codex plugin displayName must be Supered");
-  }
-
-  if (manifest.codexPlugin.skills !== "./skills/") {
-    errors.push("Codex plugin skills path must be ./skills/");
-  }
-
-  const logoPath = manifest.codexPlugin.interface?.logo?.replace(/^\.\//, "");
-  if (logoPath) {
-    checked.push(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));
-    if (!skill.name) {
-      errors.push(`${relative(root, skill.path)} is missing a name`);
-    }
-    if (!skill.description) {
-      errors.push(`${relative(root, skill.path)} is missing a description`);
-    }
-    if (!/^# /m.test(skill.body)) {
-      errors.push(`${relative(root, skill.path)} is missing an H1`);
-    }
-  }
-
-  const skillNames = skills.map((skill) => skill.name);
-  for (const expected of SKILL_ORDER) {
-    if (!skillNames.includes(expected)) {
-      errors.push(`Missing skill: ${expected}`);
-    }
-  }
-
-  return {
-    errors,
-    checked,
-    skills
-  };
+  const { validateReleaseBundle } = await import("./release-bundle.js");
+  return validateReleaseBundle(root);
 }

package/lib/package-verification.js

@@ -0,0 +1,113 @@
+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"));
+      }
+    }
+
+    const result = {
+      packageName: packageJson.name,
+      version: packageJson.version,
+      tarballName: pack.filename,
+      files,
+      installedTargets: [...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.1.3",
+  "version": "0.2.1",
   "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
   "type": "module",
   "homepage": "https://fhajjej-ship-it.github.io/Supered/",