@app-vitals/agent-admin 0.0.0-stage → 0.1.0

package/src/specialty-manifest-loader.ts

@@ -0,0 +1,255 @@
+/**
+ * admin/src/specialty-manifest-loader.ts
+ *
+ * SpecialtyRegistry — resolves an agent's stored `typeName` to its parsed
+ * Specialty manifest by loading `specialties/{typeName}/manifest.yaml` from
+ * disk (relative to the repo root) and validating it via
+ * parseSpecialtyManifest().
+ *
+ * This is the runtime source of truth for an agent's default system crons
+ * (and, in time, its default plugins/tools/env contract). It replaces the
+ * former hardcoded SYSTEM_CRONS array in admin/src/system-crons.ts.
+ *
+ * Fallback contract: an unknown `typeName` (a value with no matching
+ * directory under specialties/) resolves to the "coding" manifest with a
+ * logged warning — never throws. This keeps the boot-path
+ * POST /agents/:id/crons/reconcile route from beginning to 5xx for an agent
+ * whose type was renamed or removed.
+ *
+ * Hard-failure contract: if the "coding" manifest itself (the universal
+ * fallback) cannot be loaded or fails validation, that is a configuration error
+ * (it names SHIPWRIGHT_SPECIALTIES_DIR / SHIPWRIGHT_DEFAULT_AGENT_TYPE) and the error propagates — we never silently degrade the fallback into a
+ * no-op that would strip every agent's system crons.
+ *
+ * The class takes an injectable reader/warner so unit tests can drive it
+ * without touching the filesystem (see agent-cron-jobs.unit.test.ts).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type SpecialtyManifest,
+  parseSpecialtyManifest,
+} from "./specialty-registry.ts";
+
+/** The universal fallback type — every agent degrades to this manifest. */
+export const DEFAULT_SPECIALTY_NAME = "coding";
+
+/** Reads a manifest's raw YAML text for a type; throws if it does not exist. */
+type ManifestReader = (typeName: string) => string;
+
+/** Sink for the unknown-typeName warning (defaults to console.warn). */
+type WarnFn = (message: string) => void;
+
+/**
+ * Lists the typeName of every discoverable specialty directory (e.g. the
+ * names of the subdirectories under specialties/). Used by listTypes() to
+ * discover candidates before resolving each one's manifest via `read`.
+ */
+type TypeDirLister = () => string[];
+
+/** A discovered specialty, as surfaced to the new-specialty picker. */
+export interface SpecialtyOption {
+  name: string;
+  displayName: string;
+}
+
+/**
+ * Repo root resolved relative to this module (admin/src/ → ../../). The
+ * specialties/ directory lives at the repo root alongside admin/.
+ */
+const REPO_ROOT = join(import.meta.dir, "..", "..");
+const BUILT_IN_SPECIALTIES_DIR = join(REPO_ROOT, "specialties");
+
+/**
+ * The specialties directory: SHIPWRIGHT_SPECIALTIES_DIR when set, else the
+ * repo-root specialties/ (today's location).
+ */
+export function resolveSpecialtiesDir(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return env.SHIPWRIGHT_SPECIALTIES_DIR || BUILT_IN_SPECIALTIES_DIR;
+}
+
+/**
+ * The universal fallback type: SHIPWRIGHT_DEFAULT_AGENT_TYPE when set, else
+ * "coding".
+ */
+/**
+ * The actionable error for a default specialty that cannot be loaded. The
+ * platform ships no specialty of its own, so this is a configuration problem:
+ * the operator must point the two env vars at a real specialties directory.
+ */
+export function missingDefaultSpecialtyError(
+  defaultTypeName: string,
+  typesDir: string,
+  cause?: unknown,
+): Error {
+  const detail = cause instanceof Error ? ` (${cause.message})` : "";
+  return new Error(
+    `SpecialtyRegistry: the default specialty "${defaultTypeName}" could not be loaded from "${typesDir}"${detail}. ` +
+      "Set SHIPWRIGHT_SPECIALTIES_DIR to a directory containing <type>/manifest.yaml and " +
+      "SHIPWRIGHT_DEFAULT_AGENT_TYPE to the name of a specialty in it.",
+  );
+}
+
+export function resolveDefaultSpecialtyName(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return env.SHIPWRIGHT_DEFAULT_AGENT_TYPE || DEFAULT_SPECIALTY_NAME;
+}
+
+/** Default reader: loads {typesDir}/{typeName}/manifest.yaml from disk. */
+export function defaultManifestReader(
+  typeName: string,
+  typesDir: string = resolveSpecialtiesDir(),
+): string {
+  return readFileSync(join(typesDir, typeName, "manifest.yaml"), "utf-8");
+}
+
+/** Default lister: the directory names under the specialties dir on disk. */
+export function defaultTypeDirLister(
+  typesDir: string = resolveSpecialtiesDir(),
+): string[] {
+  return readdirSync(typesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+/**
+ * Interface the reconcile path depends on — kept narrow so tests can supply a
+ * trivial double without constructing the real disk-backed registry.
+ */
+export interface SpecialtyManifestResolver {
+  /**
+   * Resolve `typeName` to its parsed manifest. Falls back to the "coding"
+   * manifest (with a warning) when the type is unknown. Never throws for an
+   * unknown type — only if the "coding" fallback itself fails to load.
+   */
+  getManifest(typeName: string): SpecialtyManifest;
+  /**
+   * Resolve `typeName` to its parsed manifest WITHOUT falling back to
+   * "coding" — returns undefined for an unknown type instead. No warning is
+   * logged (an unknown type here is an expected, callers-handle-it outcome,
+   * not a degraded-boot condition). Used by POST /admin/agents to reject an
+   * unknown requested `type` with 400 rather than silently seeding a
+   * "coding" agent under a different label.
+   */
+  tryGetManifest(typeName: string): SpecialtyManifest | undefined;
+  /**
+   * Discover every specialty directory (via the injected `list` fn) and
+   * resolve each to its {name, displayName} for populating the new-agent
+   * type picker. A directory whose manifest fails to load or parse is
+   * skipped (not thrown) — the picker still renders every other valid type
+   * rather than 500ing the whole /admin/agents/new page over one bad
+   * manifest. Order matches the underlying `list` fn's order.
+   */
+  listTypes(): SpecialtyOption[];
+}
+
+export class SpecialtyRegistry implements SpecialtyManifestResolver {
+  private readonly read: ManifestReader;
+  private readonly warn: WarnFn;
+  private readonly list: TypeDirLister;
+  private readonly defaultTypeName: string;
+  private readonly typesDir: string;
+  private readonly cache = new Map<string, SpecialtyManifest>();
+
+  /**
+   * `typesDir` and `defaultTypeName` default to SHIPWRIGHT_SPECIALTIES_DIR /
+   * SHIPWRIGHT_DEFAULT_AGENT_TYPE, then to today's repo-root specialties/
+   * and "coding". An injected `read`/`list` takes precedence over `typesDir`.
+   */
+  constructor(
+    opts: {
+      read?: ManifestReader;
+      warn?: WarnFn;
+      list?: TypeDirLister;
+      typesDir?: string;
+      defaultTypeName?: string;
+    } = {},
+  ) {
+    const typesDir = opts.typesDir ?? resolveSpecialtiesDir();
+    this.typesDir = typesDir;
+    this.read = opts.read ?? ((name) => defaultManifestReader(name, typesDir));
+    this.warn = opts.warn ?? ((m) => console.warn(m));
+    this.list = opts.list ?? (() => defaultTypeDirLister(typesDir));
+    this.defaultTypeName =
+      opts.defaultTypeName ?? resolveDefaultSpecialtyName();
+  }
+
+  getManifest(typeName: string): SpecialtyManifest {
+    const resolved = this.tryLoad(typeName);
+    if (resolved) return resolved;
+
+    // Unknown type — warn once and fall back to "coding". The fallback load is
+    // deliberately NOT wrapped in tryLoad: if "coding" can't load, that's a
+    // hard startup bug and must surface, not silently become a no-op.
+    this.warn(
+      `SpecialtyRegistry: unknown agent typeName "${typeName}" — ` +
+        `falling back to "${this.defaultTypeName}" manifest`,
+    );
+    if (typeName === this.defaultTypeName) {
+      // Guard against infinite intent: the default itself failed to load.
+      throw missingDefaultSpecialtyError(this.defaultTypeName, this.typesDir);
+    }
+    try {
+      return this.loadOrThrow(this.defaultTypeName);
+    } catch (err) {
+      throw missingDefaultSpecialtyError(
+        this.defaultTypeName,
+        this.typesDir,
+        err,
+      );
+    }
+  }
+
+  /**
+   * Resolve `typeName` without falling back to "coding" — see the interface
+   * doc comment. Thin public wrapper around the existing tryLoad() used
+   * internally by getManifest().
+   */
+  tryGetManifest(typeName: string): SpecialtyManifest | undefined {
+    return this.tryLoad(typeName);
+  }
+
+  listTypes(): SpecialtyOption[] {
+    const typeNames = this.list();
+    const options: SpecialtyOption[] = [];
+    for (const typeName of typeNames) {
+      const manifest = this.tryLoad(typeName);
+      if (!manifest) continue;
+      options.push({
+        name: manifest.metadata.name,
+        displayName: manifest.metadata.displayName,
+      });
+    }
+    return options;
+  }
+
+  /** Load + cache a manifest, returning undefined only if the file is missing. */
+  private tryLoad(typeName: string): SpecialtyManifest | undefined {
+    const cached = this.cache.get(typeName);
+    if (cached) return cached;
+    let raw: string;
+    try {
+      raw = this.read(typeName);
+    } catch {
+      return undefined;
+    }
+    return this.parseAndCache(typeName, raw);
+  }
+
+  /** Load + cache a manifest, propagating any read/parse error. */
+  private loadOrThrow(typeName: string): SpecialtyManifest {
+    const cached = this.cache.get(typeName);
+    if (cached) return cached;
+    return this.parseAndCache(typeName, this.read(typeName));
+  }
+
+  private parseAndCache(typeName: string, raw: string): SpecialtyManifest {
+    const manifest = parseSpecialtyManifest(raw);
+    this.cache.set(typeName, manifest);
+    return manifest;
+  }
+}

package/src/specialty-manifest-loader.unit.test.ts

@@ -0,0 +1,301 @@
+/**
+ * admin/src/specialty-manifest-loader.unit.test.ts
+ * Unit tests for SpecialtyRegistry — the disk-backed resolver from an agent's
+ * typeName to its parsed manifest, with the unknown-type "coding" fallback.
+ *
+ * Pure logic against an injected reader/warner — no filesystem, no DB. See
+ * docs/testing.md for the unit-layer contract.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  SpecialtyRegistry,
+  DEFAULT_SPECIALTY_NAME,
+  resolveSpecialtiesDir,
+  resolveDefaultSpecialtyName,
+} from "./specialty-manifest-loader.ts";
+
+/** A minimal valid Specialty manifest YAML for a given type name. */
+function manifestYaml(name: string): string {
+  return `apiVersion: shipwright.dev/v1alpha1
+kind: Specialty
+metadata:
+  name: ${name}
+  displayName: ${name}
+  description: test manifest
+  version: 1.0.0
+  skills: []
+identity:
+  templatesDir: workspace/
+crons:
+  - name: ${name}-cron
+    schedule: "* * * * *"
+    prompt: /noop
+plugins: []
+tools: []
+env:
+  required: []
+  optional: []
+members: []
+repos: []
+chat: true
+voice: true
+`;
+}
+
+describe("SpecialtyRegistry", () => {
+  it("resolves a known typeName to its parsed manifest", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => manifestYaml(t),
+    });
+    const manifest = registry.getManifest("coding");
+    expect(manifest.metadata.name).toBe("coding");
+    expect(manifest.crons[0]?.name).toBe("coding-cron");
+  });
+
+  it("falls back to the coding manifest with a warning for an unknown typeName", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => {
+        if (t === DEFAULT_SPECIALTY_NAME) return manifestYaml("coding");
+        throw new Error(`ENOENT: no manifest for ${t}`);
+      },
+      warn: (m) => warnings.push(m),
+    });
+
+    const manifest = registry.getManifest("renamed-type");
+
+    expect(manifest.metadata.name).toBe("coding");
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("renamed-type");
+    expect(warnings[0]).toContain("coding");
+  });
+
+  it("throws (does not silently no-op) when the coding fallback itself cannot load", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: () => {
+        throw new Error("ENOENT: coding manifest missing");
+      },
+      warn: () => {},
+    });
+
+    // Requesting the default type when it can't load must surface a hard error
+    // rather than degrade into an empty cron set that would strip system crons.
+    expect(() => registry.getManifest("coding")).toThrow();
+  });
+
+  it("names SHIPWRIGHT_SPECIALTIES_DIR and SHIPWRIGHT_DEFAULT_AGENT_TYPE when the default specialty is missing", () => {
+    const registry = new SpecialtyRegistry({
+      read: () => {
+        throw new Error("ENOENT: no manifest");
+      },
+      warn: () => {},
+      typesDir: "/nonexistent/specialties",
+      defaultTypeName: "absent",
+    });
+
+    for (const typeName of ["absent", "some-other-type"]) {
+      let message = "";
+      try {
+        registry.getManifest(typeName);
+      } catch (err) {
+        message = (err as Error).message;
+      }
+      expect(message).toContain('default specialty "absent"');
+      expect(message).toContain("/nonexistent/specialties");
+      expect(message).toContain("SHIPWRIGHT_SPECIALTIES_DIR");
+      expect(message).toContain("SHIPWRIGHT_DEFAULT_AGENT_TYPE");
+      expect(message).not.toContain("startup-time bug");
+    }
+  });
+
+  it("caches a resolved manifest — the reader is called once per type", () => {
+    let reads = 0;
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => {
+        reads++;
+        return manifestYaml(t);
+      },
+    });
+
+    registry.getManifest("coding");
+    registry.getManifest("coding");
+
+    expect(reads).toBe(1);
+  });
+
+  // ─── tryGetManifest — non-fallback lookup ────────────────────────────────
+  //
+  // Unlike getManifest(), tryGetManifest() must NOT fall back to "coding" for
+  // an unknown typeName — it returns undefined instead. This is what lets
+  // POST /agents distinguish "resolved to the exact requested type" from
+  // "silently degraded", which the cron-reconcile boot path (getManifest())
+  // deliberately does not need to distinguish.
+
+  it("tryGetManifest resolves a known typeName to its parsed manifest", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => manifestYaml(t),
+    });
+    const manifest = registry.tryGetManifest("coding");
+    expect(manifest?.metadata.name).toBe("coding");
+  });
+
+  it("tryGetManifest returns undefined for an unknown typeName — no fallback, no warning", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => {
+        if (t === DEFAULT_SPECIALTY_NAME) return manifestYaml("coding");
+        throw new Error(`ENOENT: no manifest for ${t}`);
+      },
+      warn: (m) => warnings.push(m),
+    });
+
+    const manifest = registry.tryGetManifest("nonexistent-type");
+
+    expect(manifest).toBeUndefined();
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("tryGetManifest shares the cache with getManifest — reader called once per type", () => {
+    let reads = 0;
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      read: (t) => {
+        reads++;
+        return manifestYaml(t);
+      },
+    });
+
+    registry.getManifest("coding");
+    registry.tryGetManifest("coding");
+
+    expect(reads).toBe(1);
+  });
+
+  // ─── listTypes — populates the new-specialty picker ─────────────────────
+  //
+  // Discovers every directory under specialties/ via the injected `list` fn,
+  // then resolves each one's manifest via the existing `read` path — so
+  // listTypes() shares the same disk-free-in-tests DI contract as
+  // getManifest()/tryGetManifest().
+
+  it("listTypes lists every discovered type as {name, displayName}", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => ["coding"],
+      read: (t) => manifestYaml(t),
+    });
+
+    const types = registry.listTypes();
+
+    expect(types).toEqual([{ name: "coding", displayName: "coding" }]);
+  });
+
+  it("listTypes resolves displayName from each manifest's metadata.displayName", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => ["coding"],
+      read: () => `apiVersion: shipwright.dev/v1alpha1
+kind: Specialty
+metadata:
+  name: coding
+  displayName: Coding Agent
+  description: test manifest
+  version: 1.0.0
+  skills: []
+identity:
+  templatesDir: workspace/
+crons: []
+plugins: []
+tools: []
+env:
+  required: []
+  optional: []
+members: []
+repos: []
+chat: true
+voice: true
+`,
+    });
+
+    const types = registry.listTypes();
+
+    expect(types).toEqual([{ name: "coding", displayName: "Coding Agent" }]);
+  });
+
+  it("listTypes lists multiple discovered types", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => ["coding", "research"],
+      read: (t) => manifestYaml(t),
+    });
+
+    const types = registry.listTypes();
+
+    expect(types).toEqual([
+      { name: "coding", displayName: "coding" },
+      { name: "research", displayName: "research" },
+    ]);
+  });
+
+  it("listTypes skips a directory whose manifest fails to load or parse", () => {
+    const warnings: string[] = [];
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => ["coding", "broken"],
+      read: (t) => {
+        if (t === "broken") throw new Error("ENOENT: broken manifest");
+        return manifestYaml(t);
+      },
+      warn: (m) => warnings.push(m),
+    });
+
+    const types = registry.listTypes();
+
+    expect(types).toEqual([{ name: "coding", displayName: "coding" }]);
+  });
+
+  it("listTypes returns an empty array when no type directories are discovered", () => {
+    const registry = new SpecialtyRegistry({
+      defaultTypeName: DEFAULT_SPECIALTY_NAME,
+      list: () => [],
+      read: (t) => manifestYaml(t),
+    });
+
+    expect(registry.listTypes()).toEqual([]);
+  });
+});
+
+describe("specialties option resolution", () => {
+  it("defaults to coding and the repo-root specialties/ with no env set", () => {
+    expect(resolveDefaultSpecialtyName({})).toBe("coding");
+    expect(resolveSpecialtiesDir({})).toMatch(/specialties$/);
+  });
+
+  it("honours SHIPWRIGHT_DEFAULT_AGENT_TYPE and SHIPWRIGHT_SPECIALTIES_DIR", () => {
+    expect(
+      resolveDefaultSpecialtyName({ SHIPWRIGHT_DEFAULT_AGENT_TYPE: "base" }),
+    ).toBe("base");
+    expect(
+      resolveSpecialtiesDir({ SHIPWRIGHT_SPECIALTIES_DIR: "/tmp/types" }),
+    ).toBe("/tmp/types");
+  });
+
+  it("falls back to the configured defaultTypeName for an unknown type", () => {
+    const registry = new SpecialtyRegistry({
+      read: (name) => {
+        if (name === "base") return manifestYaml("base");
+        throw new Error("ENOENT");
+      },
+      warn: () => {},
+      defaultTypeName: "base",
+    });
+    expect(registry.getManifest("missing").metadata.name).toBe("base");
+  });
+});

package/src/specialty-registry.schema.unit.test.ts

@@ -0,0 +1,35 @@
+/**
+ * admin/src/specialty-registry.schema.unit.test.ts
+ * Regenerates the Specialty JSON Schema in-memory from its Zod source and
+ * diffs it (deep-equal, not string-equal) against the committed
+ * docs/schemas/specialty.schema.json artifact. This guarantees the
+ * committed artifact can never silently drift from the Zod source —
+ * `scripts/generate-specialty-schema.ts` must be re-run (and its output
+ * re-committed) whenever SpecialtyManifestSchema changes.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "bun:test";
+import { buildSpecialtyJsonSchema } from "./specialty-registry.ts";
+
+// docs/schemas/ in the monorepo, agent-types/ in the extracted layout.
+const committedSchemaPath = [
+  join(import.meta.dir, "..", "..", "docs", "schemas", "specialty.schema.json"),
+  join(import.meta.dir, "..", "..", "agent-types", "specialty.schema.json"),
+].find((candidate) => existsSync(candidate)) as string;
+
+describe("docs/schemas/specialty.schema.json", () => {
+  it("matches the JSON Schema regenerated from SpecialtyManifestSchema", () => {
+    const regenerated = buildSpecialtyJsonSchema();
+    const committedRaw = readFileSync(committedSchemaPath, "utf-8");
+    const committed = JSON.parse(committedRaw);
+    expect(regenerated).toEqual(committed);
+  });
+
+  it("ends with exactly one trailing newline (matches the generator's write format)", () => {
+    const committedRaw = readFileSync(committedSchemaPath, "utf-8");
+    expect(committedRaw.endsWith("\n")).toBe(true);
+    expect(committedRaw.endsWith("\n\n")).toBe(false);
+  });
+});