Skip to content
2 changes: 2 additions & 0 deletions packages/opencode/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -100,6 +101,7 @@ const cli = yargs(args)
.command(PrCommand)
.command(SessionCommand)
.command(PluginCommand)
.command(OCKitCommand)
.command(DbCommand)
.fail((msg, err) => {
if (
Expand Down
125 changes: 125 additions & 0 deletions packages/opencode/src/ockit/cli.ts
Original file line number Diff line number Diff line change
@@ -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 <target>",
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 }
1 change: 1 addition & 0 deletions packages/opencode/src/ockit/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,4 @@ export {
} from "./types"

export { Service as Registry, node as registryNode } from "./registry"
export * as OCKitCli from "./cli"
100 changes: 100 additions & 0 deletions packages/opencode/src/ockit/validator.ts
Original file line number Diff line number Diff line change
@@ -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 = <T>(
values: ReadonlyArray<T>,
kind: ValidationIssue["kind"],
label: string,
idOf: (value: T) => string,
) => {
const seen = new Set<string>()
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 }
8 changes: 5 additions & 3 deletions packages/opencode/test/cli/run/run-process.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
)
Expand Down
Loading
Loading