Skip to content

feat(opencode): OC Kit domain model (Phase 1) - #1

Closed
qkhalk wants to merge 3 commits into
mainfrom
oc-kit-domain
Closed

qkhalk wants to merge 3 commits into
mainfrom
oc-kit-domain

Conversation

@qkhalk

@qkhalk qkhalk commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

Implements Phase 1 of the OC Kit integration plan for the vibecoder880/opencode fork: the OC Kit domain model — typed schemas, manifest loading/validation, kit discovery, resolution, ownership tracking, checkpoints, and config access. The workflow engine, hook dispatcher, artifact manager, CLI, and installer are explicitly out of scope (later phases).

Changes

packages/opencode/src/ockit/ (new)

  • types.ts — Effect Schemas for Kit, KitSkill, KitAgent, Workflow/WorkflowStep, KitHook, Mode, WorkflowState, WorkflowRun, Artifact, Checkpoint, OwnershipEntry/OwnershipManifest, OCKitConfig.
  • manifest.ts — loadManifest reads kit.json (preferred) or kit.yaml (via Bun.YAML), validates against the Kit schema, errors as ManifestError (parse/schema failures are effectful, never sync throws).
  • registry.ts — OCKitRegistry service scans global <config>/kits and per-project config-dir kits/ lazily via InstanceState; all/get/require/dirs, NotFoundError, invalid manifests skipped.
  • resolver.ts — indexKit name-indexes declarations; resolveFromKit throws ResolveError; resolveAcross searches kits in order.
  • ownership.ts — loadOwnership/saveOwnership/claim/detectUserEdits/planUpdate implement the ownership manifest with sha256 conflict detection and replace/preserve planning.
  • checkpoint.ts — create/list/read snapshots under .oc/state/checkpoints recording per-file sha256.
  • config.ts — defaults/read/enabled/validate for the oc_kit section.
  • index.ts — export surface.

packages/core/src/v1/config/config.ts

  • Adds an optional oc_kit section to ConfigV1.Info (strictly backward-compatible).

packages/opencode/test/ockit/ (new)

  • Unit suites for manifest, registry, resolver, ownership, checkpoint, and config, following the repo's testEffect(layer) pattern.

Verification

  • CI-first per the project workflow contract: bun turbo test (test.yml) and bun typecheck (typecheck.yml) run on this PR.
  • No local build; no runtime wiring yet, so existing OpenCode behavior is unaffected.

vibecoder880 and others added 3 commits August 14, 2026 18:35
Record the fork's relationship to upstream anomalyco/opencode (1.18.18 line, no re-pin) and the phase 0+1 plan covering the OC Kit domain model, branch strategy, and CI-first verification.

Upstream: https://github.com/anomalyco/opencode
Introduce the OC Kit workflow/agent engineering layer in packages/opencode/src/ockit. Phase 1 delivers the typed domain model only; the workflow engine, hook dispatcher, artifact manager, CLI, and installer land in later phases.

Schemas (types.ts): Kit, KitSkill, KitAgent, Workflow/WorkflowStep, KitHook, Mode, WorkflowState, WorkflowRun, Artifact, Checkpoint, OwnershipEntry/Manifest, OCKitConfig as Effect Schemas.

Manifest (manifest.ts): loadManifest reads kit.json (prefers) or kit.yaml via Bun.YAML, validates against the Kit schema, and reports ManifestError. Parse/schema failures are effectful errors, never synchronous throws.

Registry (registry.ts): OCKitRegistry service scans global <config>/kits and per-project config-dir kits/ lazily via InstanceState; all/get/require/dirs with NotFoundError and invalid-manifest skips.

Resolver (resolver.ts): indexKit builds name-indexed maps; resolveFromKit throws ResolveError; resolveAcross searches kits in order.

Ownership (ownership.ts): load/save/claim/detectUserEdits/planUpdate implement the ownership manifest with sha256 conflict detection and replace/preserve planning.

Checkpoint (checkpoint.ts): create/list/read checkpoint snapshots under .oc/state/checkpoints recording per-file sha256.

Config (config.ts): defaults, read, enabled, validate for the oc_kit section.

Config schema (core): add optional oc_kit section to ConfigV1.Info.

Tests: unit suites under packages/opencode/test/ockit for manifest, registry, resolver, ownership, checkpoint, config.
Copilot AI lite review requested due to automatic review settings August 14, 2026 12:54
@github-actions

Copy link
Copy Markdown

This PR doesn't fully meet our contributing guidelines and PR template.

What needs to be fixed:

  • PR description is missing required template sections. Please use the PR template.

Please edit this PR description to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Implements Phase 1 of OC Kit for packages/opencode: introduces the typed OC Kit domain model plus manifest loading/validation, kit discovery/registry, name-based resolution, ownership tracking, checkpoints, and oc_kit config plumbing (kept optional/backward-compatible in core config).

Changes:

  • Added packages/opencode/src/ockit/ modules for OC Kit schemas/types and core domain services (manifest/registry/resolver/ownership/checkpoint/config) with an export surface.
  • Extended packages/core ConfigV1 schema with an optional oc_kit section.
  • Added packages/opencode/test/ockit/ unit tests covering the new OC Kit modules.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
UPSTREAM.md Documents fork/upstream relationship and divergence policy.
plans/260814-1636-oc-kit-phase0-1/plan.md Captures Phase 0/1 implementation plan and scope boundaries.
packages/opencode/src/ockit/types.ts Defines OC Kit domain schemas/types (Kit/Skill/Agent/Workflow/etc).
packages/opencode/src/ockit/manifest.ts Implements manifest loading/parsing/validation for kit.json/kit.yaml.
packages/opencode/src/ockit/registry.ts Adds registry service to discover/index kits from global + project config dirs.
packages/opencode/src/ockit/resolver.ts Adds in-memory resolver for kit declarations (per-kit and across kits).
packages/opencode/src/ockit/ownership.ts Adds ownership manifest load/save + conflict/edit detection + update planning.
packages/opencode/src/ockit/checkpoint.ts Adds checkpoint creation/list/read for managed-file snapshotting.
packages/opencode/src/ockit/config.ts Adds typed accessors/defaults/validation for oc_kit config section.
packages/opencode/src/ockit/index.ts Exposes the public OC Kit module surface.
packages/core/src/v1/config/config.ts Adds optional oc_kit section to ConfigV1.Info schema (backward compatible).
packages/opencode/test/ockit/manifest.test.ts Tests manifest load/validation and json/yaml preference.
packages/opencode/test/ockit/registry.test.ts Tests kit discovery/indexing and error/skip behavior.
packages/opencode/test/ockit/resolver.test.ts Tests indexing + resolver behavior and missing-id error path.
packages/opencode/test/ockit/ownership.test.ts Tests ownership claim/conflict detection/edit detection/update planning and persistence.
packages/opencode/test/ockit/checkpoint.test.ts Tests checkpoint create/list/read and missing checkpoint failure.
packages/opencode/test/ockit/config.test.ts Tests defaults and config validation/decoding.
Suppressed comments (2)

packages/opencode/src/ockit/checkpoint.ts:58

  • Checkpoint ids are documented as "newest first", but list() currently just reverses the directory entry order. Directory iteration order is not guaranteed, so this can return checkpoints in an arbitrary order. Sort ids first (they include Date.now(), so lexicographic sort matches creation time) before reversing.
  const entries = yield* fs.readDirectoryEntries(dir)
  const files = entries.filter((entry) => entry.type === "file" && entry.name.endsWith(".json"))
  const ids = files.map((entry) => entry.name.replace(/\.json$/, ""))
  return kit ? ids.filter((id) => id.includes(`-${kit}-`)).toReversed() : ids.toReversed()
})

packages/opencode/src/ockit/checkpoint.ts:68

  • read() calls JSON.parse(raw) directly; invalid JSON will throw synchronously instead of failing with a typed CheckpointError. Wrap parsing in Effect.try and map parse failures to CheckpointError.
  const raw = yield* fs.readFileStringSafe(path)
  if (raw === undefined) return yield* new CheckpointError({ path, message: `No checkpoint "${id}"` })
  const decoded = yield* Schema.decodeUnknown(Checkpoint)(JSON.parse(raw)).pipe(
    Effect.mapError((err) => new CheckpointError({ path, message: Schema.TreeFormatter.formatIssueSync(err.issue) })),
  )

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +38 to +46
/** Resolve a kit's own declarations by name; throws ResolveError when absent. */
export function resolveFromKit(index: KitIndex, kind: KitIndexKeys, id: string) {
const found = index[kind].get(id)
if (found) return found
throw new ResolveError({ kind, id, kit: index.kit.id })
}

type KitIndexKeys = "skills" | "agents" | "workflows" | "hooks"

Comment on lines +44 to +47
const raw = yield* Effect.try({
try: () => (hasJson ? JSON.parse(source) : Bun.YAML.parse(source)),
catch: (cause) => new ManifestError({ path, message: `Invalid ${KIT_MANIFEST_JSON} syntax: ${String(cause)}` }),
})
Comment on lines +27 to +32
const raw = yield* fs.readFileStringSafe(path)
if (raw === undefined) return { files: {} }
const decoded = yield* Schema.decodeUnknown(OwnershipManifest)(JSON.parse(raw)).pipe(
Effect.mapError((err) => new OwnershipError({ path, message: Schema.TreeFormatter.formatIssueSync(err.issue) })),
)
return decoded
Comment on lines +33 to +35
const fs = yield* FSUtil.Service
const id = `${Date.now()}-${input.kit}-${input.operation}`
const checkpoint: Checkpoint = {
Comment on lines +7 to +11
/**
* A workflow step references one capability (a skill) plus optional per-step
* overrides. `run` names the skill; `as` is an optional local alias used when
* the same skill is referenced more than once in a workflow.
*/
Comment on lines +19 to +22
export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("OCKit.NotFoundError", {
id: Schema.String,
available: Schema.Array(Schema.String),
}) {}
Comment on lines +21 to +25
async function writeGlobalKit(home: string, kitId: string, manifest: unknown) {
const dir = path.join(home, ".config", "opencode", "kits", kitId)
await fs.mkdir(dir, { recursive: true })
await Bun.write(path.join(dir, "kit.json"), JSON.stringify(manifest))
}
@qkhalk
qkhalk changed the base branch from dev to main August 14, 2026 14:25
@qkhalk qkhalk closed this Aug 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants