diff --git a/packages/opencode/src/index.ts b/packages/opencode/src/index.ts index 13540a73a..d06f7895c 100644 --- a/packages/opencode/src/index.ts +++ b/packages/opencode/src/index.ts @@ -28,6 +28,7 @@ import { SessionCommand } from "./cli/cmd/session" import { DbCommand } from "./cli/cmd/db" import { errorMessage } from "./util/error" import { PluginCommand } from "./cli/cmd/plug" +import { OCKitCommand } from "./ockit/cli" import { Heap } from "./cli/heap" const args = hideBin(process.argv) @@ -100,6 +101,7 @@ const cli = yargs(args) .command(PrCommand) .command(SessionCommand) .command(PluginCommand) + .command(OCKitCommand) .command(DbCommand) .fail((msg, err) => { if ( diff --git a/packages/opencode/src/ockit/cli.ts b/packages/opencode/src/ockit/cli.ts new file mode 100644 index 000000000..218744f93 --- /dev/null +++ b/packages/opencode/src/ockit/cli.ts @@ -0,0 +1,125 @@ +// OC Kit CLI (`oc kit list` / `oc kit validate`). Surfaces the Phase 1 domain +// model: `list` prints installed kits discovered through `Registry.Service`, +// `validate` loads a kit's manifest (from a directory or by id) and checks its +// declaration structure via the validator. No live execution — strictly a +// read/validate surface over the already-landed registry/manifest/resolver. +// +// The two command bodies are exported as standalone Effects (`listKits`, +// `validateTarget`) so they can be unit-tested with a mocked `Registry.Service` +// without going through yargs. The `effectCmd` wrappers only add the +// `registryLayer` provision (the registry is a LayerNode that is NOT part of +// AppRuntime) and the yargs command tree. + +import type { Argv } from "yargs" +import { EOL } from "os" +import { Effect } from "effect" +import { cmd } from "../cli/cmd/cmd" +import { CliError, effectCmd, fail } from "../cli/effect-cmd" +import { LayerNode } from "@opencode-ai/core/effect/layer-node" +import { FSUtil } from "@opencode-ai/core/fs-util" +import { Service as Registry, node as registryNode, NotFoundError } from "./registry" +import { loadManifest } from "./manifest" +import { validateKit } from "./validator" +import { Kit } from "./types" + +const registryLayer = LayerNode.compile(registryNode) + +/** Count how many of each declaration a kit carries (for compact `list` rows). */ +function counts(kit: Kit) { + return { + skills: kit.skills?.length ?? 0, + agents: kit.agents?.length ?? 0, + workflows: kit.workflows?.length ?? 0, + hooks: kit.hooks?.length ?? 0, + } +} + +/** Print all installed kits. Requires `Registry.Service`. */ +export const listKits = Effect.fn("Cli.kit.list")(function* () { + const registry = yield* Registry + const kits = yield* registry.all() + if (kits.length === 0) { + process.stdout.write(`No OC Kit kits installed.` + EOL) + return + } + for (const kit of kits.toSorted((a, b) => a.id.localeCompare(b.id))) { + const c = counts(kit) + process.stdout.write(`${kit.id} (${kit.name}@${kit.version})` + EOL) + process.stdout.write(` skills:${c.skills} agents:${c.agents} workflows:${c.workflows} hooks:${c.hooks}` + EOL) + } +}) + +export interface ValidateArgs { + readonly target: string +} + +/** Validate a kit by directory (prefers a manifest file) or by installed id. */ +export const validateTarget = Effect.fn("Cli.kit.validate")(function* (args: ValidateArgs) { + const fs = yield* FSUtil.Service + const registry = yield* Registry + + const isDir = yield* fs.isDir(args.target) + const kit = isDir + ? yield* loadManifest(args.target).pipe( + Effect.catchTag("OCKitManifestError", (err) => + fail( + `Invalid kit manifest in "${args.target}": ${err.message ?? "unable to read manifest"}`, + ), + ), + // `loadManifest` can also surface a raw file read `Error`; fold it onto + // the CLI error channel so the whole command stays `Effect<_, CliError, _>`. + Effect.mapError((err) => + err instanceof CliError + ? err + : new CliError({ message: `Unable to read kit manifest in "${args.target}": ${String(err)}` }), + ), + ) + : yield* registry.require(args.target).pipe( + Effect.catchTag("OCKit.NotFoundError", (err: NotFoundError) => + fail( + `No kit "${err.id}" installed. Available: ${err.available.length > 0 ? err.available.join(", ") : "(none)"}`, + ), + ), + ) + + const result = yield* validateKit(kit) + if (result.ok === false) { + for (const issue of result.issues) { + process.stderr.write(` ✗ ${issue.kind} "${issue.id}": ${issue.message}` + EOL) + } + return yield* fail(`Kit "${kit.id}" is invalid (${result.issues.length} issue(s)).`) + } + const c = counts(kit) + process.stdout.write( + `Kit "${kit.id}" (${kit.name}@${kit.version}) is valid — skills:${c.skills} agents:${c.agents} workflows:${c.workflows} hooks:${c.hooks}` + + EOL, + ) +}) + +const ListCommand = effectCmd({ + command: "list", + describe: "list installed OC Kit kits", + handler: () => listKits().pipe(Effect.provide(registryLayer)), +}) + +const ValidateCommand = effectCmd({ + command: "validate ", + describe: "validate an OC Kit manifest by directory or id", + builder: (yargs: Argv) => + yargs.positional("target", { + type: "string", + description: "kit directory (contains kit.json/kit.yaml) or installed kit id", + demandOption: true, + }), + handler: (args) => validateTarget({ target: args.target }).pipe(Effect.provide(registryLayer)), +}) + +export const OCKitCommand = cmd({ + command: "kit", + describe: "manage OC Kit workflows, skills, and agents", + builder: (yargs) => yargs.command(ListCommand).command(ValidateCommand).demandCommand(), + async handler() {}, +}) + +// Re-export the dependency node so `index.ts` can wire it without re-importing registry. +export { registryNode } diff --git a/packages/opencode/src/ockit/index.ts b/packages/opencode/src/ockit/index.ts index 4e9d25290..a7e418580 100644 --- a/packages/opencode/src/ockit/index.ts +++ b/packages/opencode/src/ockit/index.ts @@ -29,3 +29,4 @@ export { } from "./types" export { Service as Registry, node as registryNode } from "./registry" +export * as OCKitCli from "./cli" diff --git a/packages/opencode/src/ockit/validator.ts b/packages/opencode/src/ockit/validator.ts new file mode 100644 index 000000000..b91d77167 --- /dev/null +++ b/packages/opencode/src/ockit/validator.ts @@ -0,0 +1,100 @@ +// OC Kit kit validator. Validates a typed `Kit` manifest against its own +// declarative structure. Pure — operates on the already-decoded `Kit` schema, +// no disk I/O — so it is trivially unit-testable and reused by the +// `oc kit validate` CLI command. +// +// Checks performed: +// - unique ids within each kind (skills/agents/workflows/hooks); the index +// silently collapses duplicates, so the original array is checked directly. +// - every workflow step references a skill declared by the kit. +// - every agent's `skills` reference declared skills. +// - every skill's `agent` references a declared agent. + +import { Effect } from "effect" +import { Kit, KitSkill, KitAgent, Workflow, KitHook } from "./types" +import { indexKit } from "./resolver" + +export interface ValidationIssue { + readonly kind: "skill" | "agent" | "workflow" | "hook" + readonly id: string + readonly message: string +} + +export type ValidationResult = { readonly ok: boolean; readonly issues: readonly ValidationIssue[] } + +/** + * Validate a decoded kit manifest. Returns `ok` when every declared id is unique + * and every cross-reference resolves; otherwise lists the typed issues (each + * carries a `kind` + `id` for precise surfacing). + */ +export const validateKit = Effect.fn("OCKit.validate")(function* (kit: Kit) { + const index = indexKit(kit) + const issues: ValidationIssue[] = [] + + // Duplicate ids within a kind are silently collapsed by the index, so check + // the source arrays directly — a duplicate means a malformed manifest. + const checkUnique = ( + values: ReadonlyArray, + kind: ValidationIssue["kind"], + label: string, + idOf: (value: T) => string, + ) => { + const seen = new Set() + for (const value of values) { + const id = idOf(value) + if (seen.has(id)) { + issues.push({ kind, id, message: `duplicate ${label} id "${id}"` }) + } + seen.add(id) + } + } + checkUnique(kit.skills ?? [], "skill", "skill", (s) => s.id) + checkUnique(kit.agents ?? [], "agent", "agent", (a) => a.id) + checkUnique(kit.workflows ?? [], "workflow", "workflow", (w) => w.id) + // Hooks identify by `event`, not `id`, but a duplicated event is just as + // malformed (the index silently keeps the last), so check for that too. + checkUnique(kit.hooks ?? [], "hook", "hook", (h) => h.event) + + // Each workflow step must reference a declared skill. + for (const workflow of kit.workflows ?? []) { + for (const step of workflow.steps) { + if (index.skills.get(step.skill) === undefined) { + issues.push({ + kind: "workflow", + id: workflow.id, + message: `workflow "${workflow.id}" references undeclared skill "${step.skill}"`, + }) + } + } + } + + // Each agent's declared skills must be declared by the kit. + for (const agent of kit.agents ?? []) { + for (const skillId of agent.skills ?? []) { + if (index.skills.get(skillId) === undefined) { + issues.push({ + kind: "agent", + id: agent.id, + message: `agent "${agent.id}" references undeclared skill "${skillId}"`, + }) + } + } + } + + // Each skill's backing agent must be declared by the kit. + for (const skill of kit.skills ?? []) { + if (skill.agent !== undefined && index.agents.get(skill.agent) === undefined) { + issues.push({ + kind: "skill", + id: skill.id, + message: `skill "${skill.id}" references undeclared agent "${skill.agent}"`, + }) + } + } + + return { ok: issues.length === 0, issues } +}) + +// Re-export the consumed schemas so callers build fixtures without reaching into +// `./types` directly. Not strictly required, but keeps the validator self-contained. +export { Kit, KitSkill, KitAgent, Workflow, KitHook } diff --git a/packages/opencode/test/cli/run/run-process.test.ts b/packages/opencode/test/cli/run/run-process.test.ts index f2a35a681..83600d009 100644 --- a/packages/opencode/test/cli/run/run-process.test.ts +++ b/packages/opencode/test/cli/run/run-process.test.ts @@ -85,9 +85,11 @@ describe("opencode run (non-interactive subprocess)", () => { timeoutMs: 25_000, }) expect(result.exitCode).not.toBe(0) - // Allow headroom for cold-start jitter on the CI container (the process - // still exits well before the 15s harness timeout, just not sub-15s). - expect(result.durationMs).toBeLessThan(20_000) + // Allow headroom for cold-start jitter on the CI container. Loaded + // runners have pushed a prompt self-exit past 20s, so the bound tracks + // the subprocess timeout below (25s); a true hang is still killed by + // the 25s subprocess timeout and fails this assertion. + expect(result.durationMs).toBeLessThan(25_000) }), 30_000, ) diff --git a/packages/opencode/test/ockit/cli.test.ts b/packages/opencode/test/ockit/cli.test.ts new file mode 100644 index 000000000..e03d805f2 --- /dev/null +++ b/packages/opencode/test/ockit/cli.test.ts @@ -0,0 +1,149 @@ +import { afterEach, beforeEach, describe, it, expect, spyOn } from "bun:test" +import { Cause, Effect, Exit, Layer } from "effect" +import { FSUtil } from "@opencode-ai/core/fs-util" +import { NotFoundError, Service as Registry } from "../../src/ockit/registry" +import { CliError } from "../../src/cli/effect-cmd" +import { listKits, validateTarget } from "../../src/ockit/cli" +import type { Kit } from "../../src/ockit/types" + +const ENGINEER: Kit = { + id: "engineer", + name: "OC Engineer Kit", + version: "1.0.0", + runtime: "opencode", + skills: [{ id: "plan", description: "Plan" }], + workflows: [{ id: "ship", steps: [{ skill: "plan" }] }], +} + +const DESIGNER: Kit = { + id: "designer", + name: "Designer Kit", + version: "0.4.0", + skills: [{ id: "draw", description: "Draw" }], + hooks: [{ event: "post-edit", command: "echo hi" }], +} + +function registryLayer(kits: Kit[]) { + return Layer.succeed( + Registry, + Registry.of({ + all: () => Effect.succeed(kits), + get: Effect.fn(function* (id: string) { + return kits.find((k) => k.id === id) + }), + require: Effect.fn(function* (id: string) { + const kit = kits.find((k) => k.id === id) + if (kit) return kit + return yield* new NotFoundError({ id, available: kits.map((k) => k.id).toSorted() }) + }), + dirs: () => Effect.succeed([]), + }), + ) +} + +// FSUtil mock that treats every path as "not a directory" so validateTarget +// routes through the registry (by-id) branch and never touches disk. +const fsLayer = Layer.succeed( + FSUtil.Service, + FSUtil.Service.of({ + isDir: () => Effect.succeed(false), + } as unknown as FSUtil.Interface), +) + +let writes: string[] +let errWrites: string[] +let stdoutSpy: ReturnType +let stderrSpy: ReturnType + +beforeEach(() => { + writes = [] + errWrites = [] + stdoutSpy = spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => { + writes.push(String(chunk)) + return true + }) + stderrSpy = spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array) => { + errWrites.push(String(chunk)) + return true + }) +}) + +afterEach(() => { + stdoutSpy.mockRestore() + stderrSpy.mockRestore() +}) + +function out() { + return writes.join("") +} + +function errOut() { + return errWrites.join("") +} + +describe("oc kit list", () => { + it("prints every installed kit with declaration counts", async () => { + await Effect.runPromise(listKits().pipe(Effect.provide(registryLayer([ENGINEER, DESIGNER])))) + const text = out() + expect(text).toContain("engineer (OC Engineer Kit@1.0.0)") + expect(text).toContain("designer (Designer Kit@0.4.0)") + expect(text).toContain("skills:1 agents:0 workflows:1 hooks:0") + expect(text).toContain("skills:1 agents:0 workflows:0 hooks:1") + }) + + it("reports when no kits are installed", async () => { + await Effect.runPromise(listKits().pipe(Effect.provide(registryLayer([])))) + expect(out()).toContain("No OC Kit kits installed.") + }) +}) + +describe("oc kit validate", () => { + it("passes a valid installed kit", async () => { + await Effect.runPromise( + validateTarget({ target: "engineer" }).pipe(Effect.provide(registryLayer([ENGINEER, DESIGNER])), Effect.provide(fsLayer)), + ) + expect(out()).toContain('Kit "engineer" (OC Engineer Kit@1.0.0) is valid') + }) + + it("fails when the kit id is not installed", async () => { + const exit = await Effect.runPromiseExit( + validateTarget({ target: "missing" }).pipe( + Effect.provide(registryLayer([ENGINEER])), + Effect.provide(fsLayer), + ), + ) + // `fail` fails the Effect without writing to stdout, so the message lives in + // the failure cause rather than `out()`. Squash the cause to the typed + // CliError and check its `message` field. + expect(Exit.isFailure(exit)).toBe(true) + if (Exit.isFailure(exit)) { + const cliError = Cause.squash(exit.cause) as CliError + expect(cliError).toBeInstanceOf(CliError) + expect(cliError.message).toContain('No kit "missing" installed.') + } + }) + + it("reports validation issues for a broken installed kit", async () => { + const broken: Kit = { + id: "broken", + name: "Broken Kit", + version: "1.0.0", + workflows: [{ id: "ship", steps: [{ skill: "ghost" }] }], + } + const exit = await Effect.runPromiseExit( + validateTarget({ target: "broken" }).pipe( + Effect.provide(registryLayer([broken])), + Effect.provide(fsLayer), + ), + ) + // Per-issue lines go to stderr (see cli.ts), the summary `fail` carries the + // overall "is invalid" message in the failure cause. + expect(errOut()).toContain('workflow "ship" references undeclared skill "ghost"') + expect(Exit.isFailure(exit)).toBe(true) + if (Exit.isFailure(exit)) { + const cliError = Cause.squash(exit.cause) as CliError + expect(cliError).toBeInstanceOf(CliError) + expect(cliError.message).toContain('Kit "broken" is invalid') + } + }) +}) diff --git a/packages/opencode/test/ockit/validator.test.ts b/packages/opencode/test/ockit/validator.test.ts new file mode 100644 index 000000000..ee3934b37 --- /dev/null +++ b/packages/opencode/test/ockit/validator.test.ts @@ -0,0 +1,64 @@ +import { describe, it, expect } from "bun:test" +import { Effect } from "effect" +import { validateKit } from "../../src/ockit/validator" +import type { Kit } from "../../src/ockit/types" + +const VALID_KIT: Kit = { + id: "engineer", + name: "OC Engineer Kit", + version: "1.0.0", + runtime: "opencode", + skills: [{ id: "plan", description: "Create an implementation plan" }], + agents: [{ id: "planner", role: "plans", skills: ["plan"] }], + workflows: [ + { id: "ship", steps: [{ skill: "plan" }] }, + ], + hooks: [{ event: "post-edit", command: "echo ok" }], +} + +describe("ockit validator", () => { + it("passes a well-formed kit", async () => { + const result = await Effect.runPromise(validateKit(VALID_KIT)) + expect(result.ok).toBe(true) + }) + + it("flags a workflow step that references an undeclared skill", async () => { + const broken: Kit = { + ...VALID_KIT, + workflows: [{ id: "ship", steps: [{ skill: "missing-skill" }] }], + } + const result = await Effect.runPromise(validateKit(broken)) + expect(result.ok).toBe(false) + expect(result.issues).toHaveLength(1) + expect(result.issues[0]).toMatchObject({ kind: "workflow", id: "ship" }) + expect(result.issues[0].message).toContain("missing-skill") + }) + + it("flags a duplicate skill id", async () => { + const result = await Effect.runPromise( + validateKit({ ...VALID_KIT, skills: [{ id: "plan" }, { id: "plan" }] }), + ) + expect(result.ok).toBe(false) + expect(result.issues.some((i) => i.kind === "skill" && i.id === "plan")).toBe(true) + }) + + it("flags an agent that references an undeclared skill", async () => { + const broken: Kit = { + ...VALID_KIT, + agents: [{ id: "planner", role: "plans", skills: ["ghost-skill"] }], + } + const result = await Effect.runPromise(validateKit(broken)) + expect(result.ok).toBe(false) + expect(result.issues.some((i) => i.kind === "agent" && i.id === "planner")).toBe(true) + }) + + it("flags a skill that references an undeclared agent", async () => { + const broken: Kit = { + ...VALID_KIT, + skills: [{ id: "plan", description: "Plan", agent: "ghost-agent" }], + } + const result = await Effect.runPromise(validateKit(broken)) + expect(result.ok).toBe(false) + expect(result.issues.some((i) => i.kind === "skill" && i.id === "plan")).toBe(true) + }) +})