@mutagent/helix 0.1.0-alpha.14

package/mutagent-orchestrator/scripts/slack/post.ts

@@ -0,0 +1,115 @@
+// ---------------------------------------------------------------------------
+// slack/post — the SHARED Slack transport (SLACK-CORE). The ONE impure seam.
+//
+// Threading needs the Slack WEB API (`chat.postMessage` + `thread_ts`), NOT a
+// plain incoming webhook (webhooks cannot open/append a thread). We call it with
+// native `fetch` — NO `@slack/*` runtime dependency (packaging: no new deps).
+//
+// CONFIG-GATED NO-OP: with no bot token OR no channel, every call RETURNS null
+// WITHOUT touching the network — Slack is a strictly-optional sink. Unconfigured
+// ⇒ HTML report only, never an error. A network/HTTP failure ALSO returns null
+// (never throws): a broken Slack must never break a dogfood render.
+//
+// Testability: `fetch` is injectable via `deps.fetch` so a test can assert the
+// no-op path performs ZERO network calls.
+// ---------------------------------------------------------------------------
+
+/** A built thread message — `root` opens the thread, `reply` appends to it. */
+export interface SlackMsg {
+  kind: "root" | "reply";
+  text: string;
+}
+
+/** The init shape we hand to `fetch` (structural — avoids depending on DOM libs). */
+export interface FetchInit {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+
+/** The response shape we read back (only `json()` is used). */
+export interface FetchResponse {
+  json(): Promise<unknown>;
+}
+
+/** The minimal `fetch` shape this module needs (injectable for tests). */
+export type FetchLike = (input: string, init?: FetchInit) => Promise<FetchResponse>;
+
+/** Injectable dependencies — defaults to the global `fetch`. */
+export interface PostDeps {
+  fetch?: FetchLike;
+}
+
+/** The result of a successful post — the message `ts` (the thread anchor). */
+export interface PostResult {
+  ts: string;
+}
+
+const CHAT_POST_MESSAGE_URL = "https://slack.com/api/chat.postMessage";
+
+/** True only when BOTH a non-empty token and channel are present. */
+function configured(token: string | undefined, channel: string | undefined): boolean {
+  return typeof token === "string" && token.length > 0 && typeof channel === "string" && channel.length > 0;
+}
+
+/** POST to chat.postMessage; returns the `ts` on ok, else null. Never throws. */
+async function chatPostMessage(
+  body: Record<string, unknown>,
+  token: string,
+  deps: PostDeps,
+): Promise<PostResult | null> {
+  const doFetch = deps.fetch ?? (globalThis.fetch as unknown as FetchLike | undefined);
+  if (doFetch === undefined) return null;
+  try {
+    const res = await doFetch(CHAT_POST_MESSAGE_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json; charset=utf-8",
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+    });
+    const json = (await res.json()) as { ok?: boolean; ts?: string };
+    if (json.ok === true && typeof json.ts === "string") return { ts: json.ts };
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Arguments for opening a thread (posting the root message). */
+export interface PostMessageArgs {
+  channel: string;
+  text: string;
+  token?: string;
+}
+
+/**
+ * Post a top-level message → returns its `ts` (use it as `thread_ts` for
+ * replies). Config-gated no-op: no token/channel ⇒ null, no network.
+ */
+export async function postMessage(args: PostMessageArgs, deps: PostDeps = {}): Promise<PostResult | null> {
+  if (!configured(args.token, args.channel)) return null;
+  return chatPostMessage({ channel: args.channel, text: args.text }, args.token as string, deps);
+}
+
+/** Arguments for appending a threaded reply. */
+export interface PostReplyArgs {
+  channel: string;
+  thread_ts: string;
+  text: string;
+  token?: string;
+}
+
+/**
+ * Append a reply under `thread_ts`. Config-gated no-op: no token/channel (or no
+ * thread anchor) ⇒ null, no network.
+ */
+export async function postReply(args: PostReplyArgs, deps: PostDeps = {}): Promise<PostResult | null> {
+  if (!configured(args.token, args.channel) || args.thread_ts.length === 0) return null;
+  return chatPostMessage(
+    { channel: args.channel, thread_ts: args.thread_ts, text: args.text },
+    args.token as string,
+    deps,
+  );
+}

package/mutagent-orchestrator/scripts/sync-index.ts

@@ -0,0 +1,311 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// *sync — topology indexer for mutagent-system.
+//
+// Deterministically scans `mutagent-system/*` for skills/agents and emits a
+// structured topology index plus a rendered markdown table (the dashboard
+// SYSTEM-panel breakdown). No clock, no network, no env reads — same tree in,
+// same output out.
+//
+// A directory under <systemRoot> is INDEXED if it carries ANY marker:
+//   - SKILL.md            (top-level OR `.claude/skills/<x>/SKILL.md`)
+//   - .claude/agents/*.md
+//   - package.json with a `name`
+//   - CLAUDE.md
+// Dirs named `scripts` / `node_modules` / `dist`, and dotdirs, are EXCLUDED.
+//
+// Scanning logic lives in EXPORTED pure functions so it is unit-testable; the
+// CLI main() only parses args + prints.
+// ---------------------------------------------------------------------------
+
+export type Kind = "skill" | "agent" | "system_agent";
+
+export type AdlStage =
+  | "spec"
+  | "build"
+  | "evaluate"
+  | "diagnose"
+  | "improve"
+  | "orchestrator"
+  | "shared"
+  | "unknown";
+
+export interface TopologyEntry {
+  /** Directory name (the skill/agent id within mutagent-system). */
+  name: string;
+  /**
+   * `skill` (publishable/packaged unit) · `agent` (a per-dir markdown agent def in
+   * `.claude/agents/` or a CLAUDE.md boot dir) · `system_agent` (a cross-stage
+   * orchestrator agent def under `mutagent-orchestrator/assets/agents/`, e.g. `discovery`).
+   */
+  kind: Kind;
+  /** Path relative to the scanned systemRoot. */
+  path: string;
+  /** ADL stage this unit owns, inferred from its canonical name. */
+  adl_stage: AdlStage;
+  /** package.json `version`, or null when there is no package.json. */
+  version: string | null;
+  /** True when package.json declares a `bin` (a `pnpx <skill> init` surface). */
+  hasOnboarding: boolean;
+}
+
+export interface TopologyIndex {
+  /** The scanned root (absolute as supplied by the caller). */
+  root: string;
+  /** Detected entries, sorted by name. */
+  entries: TopologyEntry[];
+}
+
+interface Markers {
+  skillMd: boolean;
+  agentMd: boolean;
+  packageName: string | null;
+  packageVersion: string | null;
+  hasBin: boolean;
+  claudeMd: boolean;
+}
+
+// Directory names that are never indexed even if they carry a marker file.
+const EXCLUDED_DIRS = new Set(["scripts", "node_modules", "dist"]);
+
+// Canonical mutagent unit -> ADL stage. Keyed on the stable directory name.
+const STAGE_BY_NAME: Record<string, AdlStage> = {
+  "mutagent-agentspec": "spec",
+  "mutagent-builder": "build",
+  "mutagent-evaluator": "evaluate",
+  "mutagent-diagnostics": "diagnose",
+  "mutagent-optimize": "improve",
+  "mutagent-orchestrator": "orchestrator",
+  "mutagent-templates": "shared",
+};
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A dir is SKILL-marked if it has a top-level SKILL.md OR any
+ * `.claude/skills/<x>/SKILL.md` (the real on-disk home for shipped skills).
+ */
+function hasSkillMd(dir: string): boolean {
+  if (isFile(path.join(dir, "SKILL.md"))) return true;
+  const skillsDir = path.join(dir, ".claude", "skills");
+  if (!isDir(skillsDir)) return false;
+  return safeReaddir(skillsDir).some((sub) =>
+    isFile(path.join(skillsDir, sub, "SKILL.md")),
+  );
+}
+
+function hasAgentMd(dir: string): boolean {
+  const agentsDir = path.join(dir, ".claude", "agents");
+  if (!isDir(agentsDir)) return false;
+  return safeReaddir(agentsDir).some((f) => f.endsWith(".md"));
+}
+
+function readPackage(dir: string): {
+  name: string | null;
+  version: string | null;
+  hasBin: boolean;
+} {
+  const pkgPath = path.join(dir, "package.json");
+  if (!isFile(pkgPath)) return { name: null, version: null, hasBin: false };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+      name?: string;
+      version?: string;
+      bin?: unknown;
+    };
+    return {
+      name: typeof parsed.name === "string" ? parsed.name : null,
+      version: typeof parsed.version === "string" ? parsed.version : null,
+      hasBin: parsed.bin !== undefined && parsed.bin !== null,
+    };
+  } catch {
+    return { name: null, version: null, hasBin: false };
+  }
+}
+
+function readMarkers(dir: string): Markers {
+  const pkg = readPackage(dir);
+  return {
+    skillMd: hasSkillMd(dir),
+    agentMd: hasAgentMd(dir),
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+    hasBin: pkg.hasBin,
+    claudeMd: isFile(path.join(dir, "CLAUDE.md")),
+  };
+}
+
+function hasAnyMarker(m: Markers): boolean {
+  return m.skillMd || m.agentMd || m.packageName !== null || m.claudeMd;
+}
+
+/**
+ * Kind precedence (first match wins):
+ *   SKILL.md            -> skill   (a shipped skill, even if it also has agents)
+ *   .claude/agents/*.md -> agent   (a markdown agent definition)
+ *   CLAUDE.md           -> agent   (an agent boot/def dir, e.g. the orchestrator)
+ *   package.json name   -> skill   (a packaged unit with no skill/agent marker, e.g.
+ *                                   shared templates)
+ *   (default)           -> agent
+ *
+ * NOTE: agent markers (.claude/agents, CLAUDE.md) are checked BEFORE the package name,
+ * because the orchestrator carries a `name` (required to be a valid monorepo workspace
+ * member) yet is an AGENT, not a publishable skill. Templates (named, no CLAUDE.md)
+ * still resolves to skill via the package-name rule.
+ */
+function resolveKind(m: Markers): Kind {
+  if (m.skillMd) return "skill";
+  if (m.agentMd) return "agent";
+  if (m.claudeMd) return "agent";
+  if (m.packageName !== null) return "skill";
+  return "agent";
+}
+
+/** Map a canonical unit name to its ADL stage; unknown names => 'unknown'. */
+export function inferAdlStage(name: string): AdlStage {
+  return STAGE_BY_NAME[name] ?? "unknown";
+}
+
+/**
+ * Scan <systemRoot> for skill/agent directories. Pure: the root is a parameter
+ * so tests can point at fixtures. Returns an empty index when the root does not
+ * exist. Entries are sorted by name for deterministic output.
+ */
+export function scanTopology(systemRoot: string): TopologyIndex {
+  const entries: TopologyEntry[] = [];
+  if (!isDir(systemRoot)) return { root: systemRoot, entries };
+
+  for (const name of safeReaddir(systemRoot)) {
+    if (name.startsWith(".")) continue;
+    if (EXCLUDED_DIRS.has(name)) continue;
+
+    const dir = path.join(systemRoot, name);
+    if (!isDir(dir)) continue;
+
+    const markers = readMarkers(dir);
+    if (!hasAnyMarker(markers)) continue;
+
+    entries.push({
+      name,
+      kind: resolveKind(markers),
+      path: path.relative(systemRoot, dir) || name,
+      adl_stage: inferAdlStage(name),
+      version: markers.packageVersion,
+      hasOnboarding: markers.hasBin,
+    });
+  }
+
+  // System agents: markdown agent defs under the orchestrator's `assets/agents/`.
+  // These are NOT top-level dirs but ARE dispatchable subjects (e.g. `discovery`,
+  // the `*discover` route target). Emitted as kind:system_agent so *sync surfaces
+  // them distinctly and resolveDispatch can resolve route_target by name from the
+  // topology (it folds system_agent → SubjectKind.Agent for the frozen bundle).
+  const sysAgentsDir = path.join(
+    systemRoot,
+    "mutagent-orchestrator",
+    "assets",
+    "agents",
+  );
+  if (isDir(sysAgentsDir)) {
+    for (const f of safeReaddir(sysAgentsDir)) {
+      if (!f.endsWith(".md")) continue;
+      entries.push({
+        name: f.replace(/\.md$/, ""),
+        kind: "system_agent",
+        path: path.relative(systemRoot, path.join(sysAgentsDir, f)),
+        adl_stage: "orchestrator",
+        version: null,
+        hasOnboarding: false,
+      });
+    }
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  return { root: systemRoot, entries };
+}
+
+const TABLE_HEADER =
+  "| ADL Stage | Name | Kind | Version | Onboarding | Path |";
+const TABLE_SEPARATOR = "| --- | --- | --- | --- | --- | --- |";
+
+/**
+ * Render the topology index as a markdown table — the breakdown the dashboard
+ * SYSTEM panel shows. An empty index renders just header + separator.
+ */
+export function renderMarkdownTable(index: TopologyIndex): string {
+  const rows = index.entries.map(
+    (e) =>
+      `| ${e.adl_stage} | ${e.name} | ${e.kind} | ${e.version ?? "—"} | ${
+        e.hasOnboarding ? "✓" : "—"
+      } | ${e.path} |`,
+  );
+  return [TABLE_HEADER, TABLE_SEPARATOR, ...rows].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI — thin wrapper. Default root is this file's grandparent:
+//   scripts/ -> mutagent-orchestrator/ -> mutagent-system/
+// Flags: --json (index only) · --table (table only) · <root> positional override.
+// ---------------------------------------------------------------------------
+function defaultSystemRoot(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..", "..");
+}
+
+function main(argv: string[]): void {
+  const args = argv.slice(2);
+  const jsonOnly = args.includes("--json");
+  const tableOnly = args.includes("--table");
+  const positional = args.find((a) => !a.startsWith("--"));
+  const systemRoot = positional
+    ? path.resolve(positional)
+    : defaultSystemRoot();
+
+  const index = scanTopology(systemRoot);
+
+  if (jsonOnly) {
+    console.info(JSON.stringify(index, null, 2));
+    return;
+  }
+  if (tableOnly) {
+    console.info(renderMarkdownTable(index));
+    return;
+  }
+  console.info(renderMarkdownTable(index));
+  console.info("");
+  console.info(JSON.stringify(index, null, 2));
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv =
+    typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  main(argv);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mutagent/helix",
+  "version": "0.1.0-alpha.14",
+  "type": "module",
+  "description": "Helix — the MutagenT Agentic Development Lifecycle (ADL) bundle: the orchestrator that conducts spec → build → evaluate → diagnose → improve, shipped together with its lifecycle-stage skills (agentspec · builder · diagnostics · evaluator · optimize). Install with: pnpx @mutagent/helix init",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "mutagent-helix": "bin/mutagent-helix.mjs"
+  },
+  "files": [
+    "bin/",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "assets/",
+    ".claude/skills/mutagent-helix/",
+    "mutagent-orchestrator/orchestrator.md",
+    "mutagent-orchestrator/routing.yaml",
+    "mutagent-orchestrator/scripts/",
+    "mutagent-orchestrator/assets/agents/",
+    "mutagent-orchestrator/references/",
+    "mutagent-diagnostics/.claude/skills/mutagent-diagnostics/",
+    "mutagent-evaluator/.claude/skills/mutagent-evaluator/",
+    "mutagent-agentspec/.claude/skills/mutagent-agentspec/",
+    "mutagent-builder/.claude/skills/mutagent-builder/",
+    "mutagent-optimize/.claude/skills/mutagent-optimize/"
+  ],
+  "scripts": {
+    "check:generated-artifacts": "bash mutagent-tools/scripts/check-no-src-declarations.sh",
+    "lint": "eslint .claude/skills/mutagent-helix/scripts --ext .ts --max-warnings 0",
+    "typecheck": "tsc --noEmit && bun run check:generated-artifacts",
+    "build": "tsc --outDir dist && bun run check:generated-artifacts",
+    "test": "node scripts/release/stale-markers.mjs --self-test && node scripts/release/vendored-discovery.mjs --self-test && node scripts/release/version-drift.mjs --self-test && bun test ./.claude/skills/mutagent-helix/scripts/",
+    "sync:discovery": "node scripts/release/vendored-discovery.mjs --write",
+    "check:discovery": "node scripts/release/vendored-discovery.mjs --check",
+    "init": "bun run .claude/skills/mutagent-helix/scripts/cli/init.ts",
+    "bundle:cli": "bun build mutagent-tools/src/cli/index.ts --target=bun --outfile=bin/mutagent-cli.mjs",
+    "release:skill": "bun run scripts/release/release-skill.ts",
+    "release:lint": "bunx eslint scripts/release --config scripts/release/eslint.config.js --max-warnings 0",
+    "release:typecheck": "bunx tsc --noEmit -p scripts/release/tsconfig.json",
+    "release:build": "bun build scripts/release/release-skill.ts --target=bun --outdir dist/release",
+    "release:test": "bun test scripts/release/",
+    "prepublishOnly": "bun run check:generated-artifacts && bun run bundle:cli && node scripts/release/prepublish-guard.mjs"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/bun": "^1.1.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "smol-toml": "^1.3.0",
+    "typescript": "^5.5.0"
+  }
+}