@app-vitals/agent-admin 0.16.2 → 1.1.0

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

@@ -1,364 +0,0 @@
-/**
- * admin/src/specialty-manifest-loader.unit.test.ts
- * Unit tests for SpecialtyRegistry — the disk-backed resolver from an agent's
- * specialty to its parsed manifest, with the unknown-type default-type 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 {
-  DEFAULT_SPECIALTY_NAME,
-  resolveDefaultSpecialtyName,
-  resolveSpecialtiesDir,
-  SpecialtyRegistry,
-} 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 specialty to its parsed manifest", () => {
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      read: (t) => manifestYaml(t),
-    });
-    const manifest = registry.getManifest("specialist");
-    expect(manifest.metadata.name).toBe("specialist");
-    expect(manifest.crons[0]?.name).toBe("specialist-cron");
-  });
-
-  it("falls back to the default (specialist) manifest with a warning for an unknown specialty", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      read: (t) => {
-        if (t === DEFAULT_SPECIALTY_NAME) return manifestYaml("specialist");
-        throw new Error(`ENOENT: no manifest for ${t}`);
-      },
-      warn: (m) => warnings.push(m),
-    });
-
-    const manifest = registry.getManifest("renamed-type");
-
-    expect(manifest.metadata.name).toBe("specialist");
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]).toContain("renamed-type");
-    expect(warnings[0]).toContain("specialist");
-  });
-
-  it("never throws: an unloadable default degrades to an empty-crons manifest with warnings naming the env knobs", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      read: () => {
-        throw new Error("ENOENT: no manifest");
-      },
-      warn: (m) => warnings.push(m),
-      typesDir: "/nonexistent/specialties",
-      defaultTypeName: "absent",
-    });
-
-    for (const specialty of ["absent", "some-other-type"]) {
-      warnings.length = 0;
-      const manifest = registry.getManifest(specialty);
-      expect(manifest.crons).toEqual([]);
-      expect(manifest.plugins).toEqual([]);
-      const all = warnings.join("\n");
-      expect(all).toContain('default specialty "absent"');
-      expect(all).toContain("/nonexistent/specialties");
-      expect(all).toContain("SHIPWRIGHT_SPECIALTIES_DIR");
-      expect(all).toContain("SHIPWRIGHT_DEFAULT_AGENT_TYPE");
-    }
-  });
-
-  it("uses the default manifest silently when the default type itself is requested and loads", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      read: (t) => manifestYaml(t),
-      warn: (m) => warnings.push(m),
-    });
-    expect(registry.getManifest(DEFAULT_SPECIALTY_NAME).metadata.name).toBe(
-      "specialist",
-    );
-    expect(warnings).toEqual([]);
-  });
-
-  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("specialist");
-    registry.getManifest("specialist");
-
-    expect(reads).toBe(1);
-  });
-
-  // ─── tryGetManifest — non-fallback lookup ────────────────────────────────
-  //
-  // Unlike getManifest(), tryGetManifest() must NOT fall back to the default type for
-  // an unknown specialty — 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 specialty to its parsed manifest", () => {
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      read: (t) => manifestYaml(t),
-    });
-    const manifest = registry.tryGetManifest("specialist");
-    expect(manifest?.metadata.name).toBe("specialist");
-  });
-
-  it("tryGetManifest returns undefined for an unknown specialty — no fallback, no warning", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      read: (t) => {
-        if (t === DEFAULT_SPECIALTY_NAME) return manifestYaml("specialist");
-        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 resolves the built-in default type when no specialty is discoverable", () => {
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      list: () => {
-        throw new Error("ENOENT: no such file or directory");
-      },
-      read: (t) => {
-        throw new Error(`ENOENT: no manifest for ${t}`);
-      },
-      warn: () => {},
-    });
-
-    expect(registry.tryGetManifest(DEFAULT_SPECIALTY_NAME)?.metadata.name).toBe(
-      DEFAULT_SPECIALTY_NAME,
-    );
-    expect(registry.tryGetManifest("nonexistent-type")).toBeUndefined();
-  });
-
-  it("tryGetManifest does not synthesize the default type when other specialties are discoverable", () => {
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      list: () => ["coding"],
-      read: (t) => {
-        if (t === "coding") return manifestYaml("coding");
-        throw new Error(`ENOENT: no manifest for ${t}`);
-      },
-      warn: () => {},
-    });
-
-    expect(registry.tryGetManifest(DEFAULT_SPECIALTY_NAME)).toBeUndefined();
-  });
-
-  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("specialist");
-    registry.tryGetManifest("specialist");
-
-    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 falls back to the built-in default option when no type directories are discovered", () => {
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      list: () => [],
-      read: (t) => manifestYaml(t),
-    });
-
-    expect(registry.listTypes()).toEqual([
-      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
-    ]);
-  });
-
-  it("listTypes warns and returns the built-in default when the list fn throws (missing dir)", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      defaultTypeName: DEFAULT_SPECIALTY_NAME,
-      warn: (m) => warnings.push(m),
-      list: () => {
-        throw new Error("ENOENT: no such file or directory");
-      },
-      read: (t) => manifestYaml(t),
-    });
-
-    expect(registry.listTypes()).toEqual([
-      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
-    ]);
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]).toContain("ENOENT");
-  });
-
-  it("listTypes does not throw on a nonexistent typesDir with the real lister", () => {
-    const warnings: string[] = [];
-    const registry = new SpecialtyRegistry({
-      typesDir: "/nonexistent/agent-types",
-      warn: (m) => warnings.push(m),
-    });
-
-    expect(registry.listTypes()).toEqual([
-      { name: DEFAULT_SPECIALTY_NAME, displayName: "Specialist Agent" },
-    ]);
-    expect(warnings.length).toBeGreaterThan(0);
-  });
-});
-
-describe("specialties option resolution", () => {
-  it("defaults to specialist and the shipped agent-types/ with no env set", () => {
-    expect(resolveDefaultSpecialtyName({})).toBe("specialist");
-    expect(resolveSpecialtiesDir({})).toMatch(/agent-types$/);
-  });
-
-  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

@@ -1,35 +0,0 @@
-/**
- * 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);
-  });
-});

package/src/specialty-registry.ts

@@ -1,236 +0,0 @@
-/**
- * admin/src/specialty-registry.ts
- *
- * Specialty manifest schema — the single source of truth for the
- * `shipwright.dev/v1alpha1` / `Specialty` YAML manifest that declares an
- * specialty's identity, crons, plugins, tools, env contract, membership,
- * repos, and chat/voice toggles.
- *
- * Named "specialty-registry" (not "manifest") to avoid colliding with the
- * two existing "manifest" concepts in this repo: the Kubernetes manifests in
- * ./agent-manifest.ts and the Slack app manifest. This module is unrelated
- * to either — it's a declarative spec fed into scripts/CLI tooling, not a
- * wire type, so it uses plain `zod` rather than `@hono/zod-openapi`'s
- * `.openapi()`-augmented `z` (kept simple for JSON Schema conversion).
- *
- * Manifests are treated as a trust boundary: they may originate from
- * third-party contributors, so every object schema is `.strict()` (unknown
- * keys rejected, not silently stripped) and the env contract is
- * deliberately keys-only — no `value`/`default` field is permitted on an
- * env entry, so a manifest can declare *that* a var is needed without ever
- * carrying a real value.
- */
-
-import { isOrgRepo } from "@app-vitals/agent-lib/org-repo";
-import { parse as parseYaml } from "yaml";
-import { z } from "zod";
-
-/** RFC1123 label pattern (see admin/src/agent-manifest.ts's sanitizeAgentName). */
-const RFC1123_NAME = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/;
-
-// ─── metadata.skills[] (A2A-aligned) ───────────────────────────────────────
-
-/**
- * Minimal A2A (Agent2Agent) "skill" shape: what the specialty can do, as a
- * small catalog entry. Kept intentionally narrow — id/name/description plus
- * optional free-form tags — since this repo has no existing A2A convention
- * to align with beyond the general shape of an agent capability card.
- */
-const SpecialtySkillSchema = z
-  .object({
-    id: z.string().min(1),
-    name: z.string().min(1),
-    description: z.string().min(1),
-    tags: z.array(z.string()).optional(),
-  })
-  .strict();
-
-// ─── metadata ───────────────────────────────────────────────────────────────
-
-const SpecialtyMetadataSchema = z
-  .object({
-    name: z
-      .string()
-      .regex(RFC1123_NAME, "metadata.name must be a valid RFC1123 label"),
-    displayName: z.string().min(1),
-    description: z.string().min(1),
-    version: z.string().min(1),
-    skills: z.array(SpecialtySkillSchema),
-  })
-  .strict();
-
-// ─── identity ───────────────────────────────────────────────────────────────
-
-const SpecialtyIdentitySchema = z
-  .object({
-    templatesDir: z.string().min(1),
-  })
-  .strict();
-
-// ─── crons[] ────────────────────────────────────────────────────────────────
-
-/**
- * A single cron template declared inside a Specialty manifest. Distinct
- * from the runtime, DB-backed AgentCronJobSchema (admin/src/openapi-schemas.ts)
- * and CreateAgentCronJobInput (admin/src/agent-cron-jobs.ts) — those describe
- * per-agent-instance rows already created in Postgres; this describes a
- * *template* inside a versioned spec. `parentCron` here is a name reference
- * resolved within this manifest's own crons[] array (validated by the
- * top-level schema's superRefine below), not a DB id reference.
- */
-const SpecialtyCronSchema = z
-  .object({
-    name: z.string().min(1),
-    schedule: z.string().min(1),
-    prompt: z.string().min(1),
-    preCheck: z.string().optional(),
-    silent: z.boolean().optional().default(false),
-    enabled: z.boolean().optional().default(true),
-    parentCron: z.string().optional(),
-  })
-  .strict();
-
-// ─── env contract ───────────────────────────────────────────────────────────
-
-/**
- * A single env contract entry. Keys-only by design: a manifest declares that
- * a var is needed (and whether it's secret) — it never carries a `value` or
- * `default`. `.strict()` ensures an unexpected `value` key is rejected, not
- * silently stripped, since manifests are potential third-party input.
- */
-const SpecialtyEnvEntrySchema = z
-  .object({
-    key: z.string().min(1),
-    description: z.string().min(1),
-    secret: z.boolean(),
-  })
-  .strict();
-
-const SpecialtyEnvSchema = z
-  .object({
-    required: z.array(SpecialtyEnvEntrySchema),
-    optional: z.array(SpecialtyEnvEntrySchema),
-  })
-  .strict();
-
-// ─── resources override (optional) ─────────────────────────────────────────
-
-/**
- * Optional override of the default agent container resources (see
- * resolveAgentContainerResources in admin/src/agent-manifest.ts). All fields
- * optional — a manifest may override just one of requests/limits.
- *
- * Not yet wired to any provisioner — parsed as part of
- * SpecialtyManifestSchema.resources but inert until a future task consumes it
- * ahead of resolveAgentContainerResources's env-override layer (see that
- * function's precedence-rule doc comment).
- */
-const SpecialtyResourceListSchema = z
-  .object({
-    cpu: z.string().optional(),
-    memory: z.string().optional(),
-    "ephemeral-storage": z.string().optional(),
-  })
-  .strict();
-
-const SpecialtyResourcesSchema = z
-  .object({
-    requests: SpecialtyResourceListSchema.optional(),
-    limits: SpecialtyResourceListSchema.optional(),
-  })
-  .strict();
-
-// ─── Top-level Specialty manifest ──────────────────────────────────────────
-
-export const SpecialtyManifestSchema = z
-  .object({
-    apiVersion: z.literal("shipwright.dev/v1alpha1"),
-    kind: z.literal("Specialty"),
-    metadata: SpecialtyMetadataSchema,
-    identity: SpecialtyIdentitySchema,
-    crons: z.array(SpecialtyCronSchema),
-    plugins: z.array(z.string()),
-    tools: z.array(z.string()),
-    env: SpecialtyEnvSchema,
-    members: z.array(z.string()),
-    repos: z.array(
-      z.string().refine(isOrgRepo, {
-        message: "each repo must be in org/repo format",
-      }),
-    ),
-    chat: z.boolean(),
-    voice: z.boolean(),
-    resources: SpecialtyResourcesSchema.optional(),
-  })
-  .strict()
-  .superRefine((manifest, ctx) => {
-    const cronNames = new Set(manifest.crons.map((c) => c.name));
-    manifest.crons.forEach((cron, index) => {
-      if (cron.parentCron === undefined) return;
-      if (cron.parentCron === cron.name) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["crons", index, "parentCron"],
-          message: `parentCron "${cron.parentCron}" cannot reference its own cron entry`,
-        });
-        return;
-      }
-      if (!cronNames.has(cron.parentCron)) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["crons", index, "parentCron"],
-          message: `parentCron "${cron.parentCron}" does not match any cron name in this manifest`,
-        });
-      }
-    });
-  });
-
-export type SpecialtyManifest = z.infer<typeof SpecialtyManifestSchema>;
-
-// ─── Parsing ────────────────────────────────────────────────────────────────
-
-/**
- * Parse and validate a YAML Specialty manifest string.
- *
- * Pure — no I/O. `content` is the already-read YAML text; throws a
- * descriptive Error (with the underlying ZodError's field-path issues
- * embedded in `message`, and the ZodError itself reachable via `cause`) if
- * the manifest fails schema validation.
- */
-export function parseSpecialtyManifest(content: string): SpecialtyManifest {
-  const raw: unknown = parseYaml(content);
-  const result = SpecialtyManifestSchema.safeParse(raw);
-  if (!result.success) {
-    const details = result.error.issues
-      .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-      .join("; ");
-    throw new Error(`invalid Specialty manifest — ${details}`, {
-      cause: result.error,
-    });
-  }
-  return result.data;
-}
-
-// ─── JSON Schema generation ─────────────────────────────────────────────────
-
-/**
- * Build the JSON-serializable JSON Schema object for SpecialtyManifestSchema.
- *
- * Pure — no file I/O — so both scripts/generate-specialty-schema.ts's CLI
- * entrypoint and its content test can call this directly instead of shelling
- * out. Uses zod 4's built-in `z.toJSONSchema` (draft-07 target, to stay
- * contract-compatible with the previous zod-to-json-schema output).
- */
-export function buildSpecialtyJsonSchema(): Record<string, unknown> {
-  const { $schema, ...definition } = z.toJSONSchema(SpecialtyManifestSchema, {
-    target: "draft-7",
-    io: "input",
-  });
-  // Wrap as a named definition (`$ref` + `definitions`) — the shape the
-  // previous zod-to-json-schema output used, so consumers see no change.
-  return {
-    $ref: "#/definitions/SpecialtyManifest",
-    definitions: { SpecialtyManifest: definition },
-    $schema,
-  };
-}