@cairn-tool/cairn 2.0.0

package/dist/agent/targets/opencode.js

@@ -0,0 +1,215 @@
+import { PROFILE_SCHEMA_VERSION } from "./schema.js";
+/**
+ * OpenCode.
+ *
+ * Written against the `customize-opencode` skill the 1.18.23 binary embeds,
+ * which is the host's own configuration reference and supersedes the
+ * `@opencode-ai/plugin` types installed beside it.
+ *
+ * The load-bearing negative fact is that **unknown top-level keys in
+ * `opencode.json` are rejected with `ConfigInvalidError` and the host refuses
+ * to start**. So Cairn never writes a bundle manifest there: the plugin
+ * manifest goes in `.opencode-plugin/`, a directory OpenCode does not read, the
+ * same convention `.codex-plugin/` and `.cursor-plugin/` already use.
+ */
+export const opencodeProfile = {
+    schemaVersion: PROFILE_SCHEMA_VERSION,
+    id: "opencode",
+    host: {
+        displayName: "OpenCode",
+        documentationRevision: "2026-08-29",
+        minimumVersion: null,
+        // `opencode --version` against the installed binary this was written from.
+        verifiedThrough: "1.18.23",
+        versionCommand: ["opencode", "--version"],
+        nativeValidator: null,
+    },
+    profiles: ["plugin", "project"],
+    manifest: {
+        // Deliberately not `opencode.json`: an unknown key there stops the host.
+        directory: ".opencode-plugin",
+        file: "plugin.json",
+        fields: [
+            { name: "name", required: true, support: "exact" },
+            { name: "version", required: true, support: "exact" },
+            { name: "description", required: true, support: "exact" },
+            { name: "skills", required: false, support: "exact" },
+            { name: "agents", required: false, support: "exact" },
+            { name: "mcpServers", required: false, support: "exact" },
+        ],
+        // OpenCode has no hook system to declare.
+        impliedFields: ["hooks"],
+    },
+    paths: {
+        plugin: {
+            skills: "skills",
+            hooks: "hooks",
+            hooksFile: "hooks/hooks.json",
+            agents: "agent",
+            assets: "assets",
+            mcp: ".mcp.json",
+        },
+        project: {
+            // The host accepts both spellings; the plural is the one its own
+            // `skills.paths` example uses.
+            skills: ".opencode/skills",
+            // Singular, which is the spelling its documentation lists first.
+            agents: ".opencode/agent",
+            rules: "AGENTS.md",
+            // No policy is written; see the note below.
+            policies: null,
+            mcp: "opencode.json",
+            assets: "assets",
+        },
+        namespacePluginSkills: false,
+    },
+    placeholders: {
+        bundleRoot: { plugin: ".", project: "." },
+        // `$ARGUMENTS`, `$1` and `$2` are documented for *commands*; nothing states
+        // that a skill substitutes them. Advisory is correct under either reading.
+        arguments: "advisory",
+        rootVariables: [],
+    },
+    hooks: {
+        // OpenCode 1.18.23 has no lifecycle hook file at all: the plugin API is
+        // TypeScript callbacks in `.opencode/plugin/*.ts`, which a portable JSON
+        // hook declaration cannot express. Every event is inexpressible, so hook
+        // emission is skipped entirely rather than writing an inert document.
+        events: {
+            "session-start": null,
+            "pre-tool-use": null,
+            "post-tool-use": null,
+            stop: null,
+        },
+        envelope: "hooks",
+        handlerShape: "flat",
+        matcherEvents: [],
+        supportedProtocols: [],
+    },
+    models: {
+        // Every model id is `provider/model-id`, so mapping a semantic class would
+        // hardcode one vendor into a neutral profile.
+        support: "unsupported",
+        classes: { fast: null, balanced: null, capable: null, inherit: null },
+    },
+    tools: {
+        // An exact map is knowable, but OpenCode's `tools` frontmatter is a boolean
+        // map while the renderer produces an array. Declaring a mapping would emit
+        // a correctly-named key of the wrong shape, which is worse than declaring
+        // the restriction inexpressible.
+        support: "approximate",
+        capabilities: null,
+    },
+    rules: {
+        exactActivation: ["always"],
+        // `instructions` accepts globs, but not per-rule activation.
+        approximateActivation: ["files"],
+        form: "aggregated-agents-md",
+    },
+    /**
+     * OpenCode does have a native command policy -- `permission.bash` in
+     * `opencode.json` -- and it is deliberately not written yet.
+     *
+     * `paths.project.mcp` is already `opencode.json`, and both the MCP writer and
+     * `renderPolicies` serialize a whole document. Two writers to one path is a
+     * duplicate-path diagnostic and a clobber, and shipping a permission file
+     * that silently erases the user's MCP block is worse than shipping none.
+     * `PolicyForm` reserves `opencode-permission` so that adding it later, once
+     * the two share a merge-aware writer, is a data edit.
+     */
+    policies: { form: null },
+    // The skill frontmatter keys are enumerated -- name, description, license,
+    // compatibility, metadata -- and none controls implicit activation.
+    skills: { invocationPolicy: "advisory" },
+    outputs: {
+        plugin: [
+            { feature: "manifest", pattern: ".opencode-plugin/plugin.json" },
+            { feature: "skills", pattern: "skills/{name}/**" },
+            { feature: "agents", pattern: "agent/{name}.md" },
+            { feature: "mcp", pattern: ".mcp.json" },
+            { feature: "assets", pattern: "assets/**" },
+        ],
+        project: [
+            { feature: "skills", pattern: ".opencode/skills/{name}/**" },
+            { feature: "agents", pattern: ".opencode/agent/{name}.md" },
+            { feature: "rules", pattern: "AGENTS.md" },
+            { feature: "mcp", pattern: "opencode.json" },
+            { feature: "assets", pattern: "assets/**" },
+        ],
+    },
+    features: {
+        skills: {
+            support: "exact",
+            profiles: ["plugin", "project"],
+            summary: "exact",
+            surface: ".opencode/skills/<name>/SKILL.md",
+            diagnostics: ["AB310"],
+        },
+        agents: {
+            support: "approximate",
+            profiles: ["plugin", "project"],
+            summary: "markdown with frontmatter; tool restrictions are not expressible",
+            surface: ".opencode/agent/<name>.md",
+            diagnostics: ["AB330", "AB332"],
+        },
+        rules: {
+            support: "approximate",
+            profiles: ["project"],
+            summary: "AGENTS.md project layer",
+            surface: "AGENTS.md",
+            diagnostics: ["AB350", "AB351"],
+        },
+        hooks: {
+            support: "unsupported",
+            profiles: [],
+            summary: "no lifecycle hook file; plugins are TypeScript callbacks",
+            surface: null,
+            diagnostics: ["AB320"],
+        },
+        policies: {
+            support: "unsupported",
+            profiles: ["project"],
+            summary: "native permissions share opencode.json with MCP and are not written",
+            surface: null,
+            diagnostics: ["AB360", "AB361"],
+        },
+        mcp: {
+            support: "approximate",
+            profiles: ["plugin", "project"],
+            summary: "exact in plugins; a project document must already be opencode config shape",
+            surface: "opencode.json",
+            diagnostics: [],
+        },
+        assets: {
+            support: "exact",
+            profiles: ["plugin", "project"],
+            summary: "pass-through",
+            surface: "assets/",
+            diagnostics: [],
+        },
+        placeholders: {
+            support: "approximate",
+            profiles: ["plugin", "project"],
+            summary: "argument substitution is documented for commands, not skills",
+            surface: null,
+            diagnostics: [],
+        },
+        native: {
+            support: "native",
+            profiles: ["plugin", "project"],
+            summary: "overlay pass-through",
+            surface: "native/opencode/",
+            diagnostics: ["AB181", "AB182", "AB187"],
+        },
+    },
+    // No marketplace concept: `opencode plugin <module>` installs an npm package.
+    install: {
+        // Global scope drops the `.opencode/` prefix -- skills live at
+        // `~/.config/opencode/skills/`, not `~/.config/opencode/.opencode/skills/`.
+        // `InstallLocation` cannot rewrite a path, so declaring a merge here would
+        // install to a directory OpenCode never scans. Same reasoning as Codex.
+        user: null,
+        project: { root: ".", layout: "merge", profile: "project", activation: null },
+    },
+};
+//# sourceMappingURL=opencode.js.map

package/dist/agent/targets/opencode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opencode.js","sourceRoot":"","sources":["../../../src/agent/targets/opencode.ts"],"names":[],"mappings":"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"}

package/dist/agent/targets/schema.d.ts

@@ -0,0 +1,315 @@
+import type { AgentProfile, AgentTarget, BundleRule, MappingQuality } from "../types.js";
+/**
+ * Version of the target-profile shape itself. Hand-owned; unrelated to the
+ * semantic-release-managed package version. Bump only when the profile
+ * structure changes in a way consumers must react to.
+ */
+export declare const PROFILE_SCHEMA_VERSION = "2";
+export declare const PORTABLE_HOOK_EVENTS: readonly ["session-start", "pre-tool-use", "post-tool-use", "stop"];
+export type PortableHookEvent = (typeof PORTABLE_HOOK_EVENTS)[number];
+export type ModelClass = "fast" | "balanced" | "capable" | "inherit";
+export type ToolCapability = "read" | "write" | "shell" | "web";
+export type RuleActivation = BundleRule["activation"];
+/** MappingQuality plus the target-native pass-through case profiles need. */
+export type FeatureSupport = MappingQuality | "native";
+export declare const FEATURE_KEYS: readonly ["skills", "agents", "rules", "hooks", "policies", "mcp", "assets", "placeholders", "native"];
+export type FeatureKey = (typeof FEATURE_KEYS)[number];
+export interface FeatureProfile {
+    /**
+     * The best mapping quality this feature achieves on this target. Individual
+     * occurrences may be worse — a malformed input or an unsupported output
+     * profile is reported per-diagnostic — but never better, which is what the
+     * conformance suite asserts.
+     */
+    support: FeatureSupport;
+    /** Output profiles in which this feature is emitted at all. Read by the renderer. */
+    profiles: AgentProfile[];
+    /** One line; the machine-generated replacement for a free-text compatibility cell. */
+    summary: string;
+    /** Native surface, e.g. ".claude/rules/<name>.md". Documentation only. */
+    surface: string | null;
+    /** Diagnostic codes this target may emit for this feature. */
+    diagnostics: string[];
+}
+/**
+ * A POSIX path relative to `<output>/<target>/<profile>`.
+ *
+ * Grammar: `{name}` matches exactly one path segment, `*` matches part of one
+ * segment, and `**` matches any remaining suffix including nothing.
+ */
+export interface OutputPattern {
+    feature: FeatureKey | "manifest";
+    pattern: string;
+}
+export interface NativeValidatorSpec {
+    /** `{dir}` is substituted with the generated `<target>/<profile>` directory. */
+    command: string[];
+    readOnly: true;
+    appliesTo: AgentProfile[];
+}
+export interface HostProfile {
+    displayName: string;
+    /** ISO date of the target documentation this profile was written against. */
+    documentationRevision: string;
+    /** Below this version the profile is known to be wrong. `null` when not recorded. */
+    minimumVersion: string | null;
+    /** Highest host version this profile was verified against. `null` when not recorded. */
+    verifiedThrough: string | null;
+    /** Declared for callers to run themselves. This CLI never executes it. */
+    versionCommand: string[] | null;
+    /** Declared for callers to run themselves. This CLI never executes it. */
+    nativeValidator: NativeValidatorSpec | null;
+}
+export interface ManifestFieldProfile {
+    name: string;
+    required: boolean;
+    support: FeatureSupport;
+}
+export interface ManifestProfile {
+    /** Plugin manifest directory, or `null` when the target has no plugin manifest. */
+    directory: string | null;
+    file: string;
+    fields: ManifestFieldProfile[];
+    /**
+     * Manifest keys the host derives from the plugin layout on its own, so the
+     * renderer must leave them out. Declaring one is not merely redundant, it is
+     * an error, and neither kind is caught by `claude plugin validate`:
+     *
+     * - `agents` accepts a list of files and rejects the component directory the
+     *   renderer would name, which fails the whole manifest.
+     * - `hooks` is for *additional* hook files; naming the standard
+     *   `hooks/hooks.json` that the host already loaded is a duplicate, and the
+     *   plugin's hooks are dropped.
+     *
+     * Omitting them is what makes `agents/` and `hooks/hooks.json` load.
+     */
+    impliedFields?: string[];
+}
+export interface PluginRoots {
+    skills: string;
+    /** Directory for hook *scripts*. */
+    hooks: string;
+    /** The hook *declaration* document, relative to the plugin root. */
+    hooksFile: string;
+    agents: string | null;
+    assets: string;
+    mcp: string | null;
+}
+export interface ProjectRoots {
+    skills: string;
+    agents: string | null;
+    rules: string | null;
+    policies: string | null;
+    mcp: string | null;
+    assets: string;
+}
+export interface PathProfile {
+    plugin: PluginRoots;
+    project: ProjectRoots;
+    /** True when plugin skill directories are namespaced as `${bundle}-${skill}`. */
+    namespacePluginSkills: boolean;
+}
+export interface PlaceholderProfile {
+    /** `${BUNDLE_ROOT}` substitution per output profile. */
+    bundleRoot: Record<AgentProfile, string>;
+    /**
+     * How `$ARGUMENTS` survives: `native` means the host substitutes it,
+     * `advisory` appends a prose hint beside it, `prose` replaces it outright.
+     */
+    arguments: "native" | "advisory" | "prose";
+    /** Root variables the target understands, for documentation and `agent specs`. */
+    rootVariables: string[];
+}
+export interface HookProfile {
+    /** Portable event to native name; `null` means the target cannot express it. */
+    events: Record<PortableHookEvent, string | null>;
+    /**
+     * `versioned` wraps handlers in `{ version: 1, hooks }`, `hooks` emits
+     * `{ hooks }`, and `named` keys the whole document by the bundle's name.
+     */
+    envelope: "hooks" | "versioned" | "named";
+    /**
+     * `claude-nested` wraps handlers in `{ matcher, hooks: [...] }` and `flat`
+     * does not. `nested-for-matcher-events` wraps only the events listed in
+     * {@link matcherEvents}, which is a host that accepts a tool-name matcher on
+     * its tool events and nothing on the rest.
+     */
+    handlerShape: "claude-nested" | "flat" | "nested-for-matcher-events";
+    /** Events that take a matcher. Empty unless `handlerShape` names it. */
+    matcherEvents: PortableHookEvent[];
+    supportedProtocols: string[];
+}
+export interface ModelProfile {
+    support: FeatureSupport;
+    /** Semantic class to native model id; `null` means the target has no model field. */
+    classes: Record<ModelClass, string | null>;
+}
+export interface ToolProfile {
+    support: FeatureSupport;
+    /** `null` means capability restriction is not expressible natively. */
+    capabilities: Record<ToolCapability, string[]> | null;
+}
+export interface RuleProfile {
+    exactActivation: RuleActivation[];
+    /** Activations that render, but not faithfully. Everything else is unsupported. */
+    approximateActivation: RuleActivation[];
+    form: "mdc" | "markdown" | "aggregated-agents-md" | "trigger-frontmatter" | null;
+}
+/**
+ * How a target expresses a command policy.
+ *
+ * This exists because the renderer used to pick the form by target name, with
+ * an unguarded `else` that emitted Codex's `prefix_rule` DSL to a Codex path
+ * for every target that was not Claude Code or Cursor. Naming the form here
+ * makes a host with no policy surface declare `null` and get a diagnostic,
+ * rather than silently inheriting someone else's format.
+ */
+export type PolicyForm = "claude-permissions" | "codex-prefix-rules" | "cursor-hooks"
+/** Reserved: a `permission` block inside a config file the MCP writer also owns. */
+ | "opencode-permission";
+export interface PolicyProfile {
+    /** `null` when the host has no native command-policy format. */
+    form: PolicyForm | null;
+}
+/**
+ * How a target expresses "do not invoke this skill implicitly".
+ *
+ * `frontmatter-flag` sets a key on the skill document, `openai-yaml` writes a
+ * sidecar policy file, and `advisory` can only say so in prose.
+ */
+export type SkillInvocationForm = "frontmatter-flag" | "openai-yaml" | "advisory";
+export interface SkillProfile {
+    /** `null` when the host offers no way to say it at all. */
+    invocationPolicy: SkillInvocationForm | null;
+}
+/** Where a catalog entry's value comes from. */
+export type MarketplaceFieldSource = {
+    from: "manifest";
+    field: string;
+} | {
+    from: "marketplace";
+    field: string;
+} | {
+    from: "computed";
+    value: "source";
+};
+/**
+ * How a resolved value is reshaped before it lands in the catalog.
+ *
+ * Targets disagree on the shape of the same underlying datum — Claude Code
+ * wants `author` as an object and `category` as one string, Cursor wants
+ * `author` as a bare name and `categories` as the whole list. Naming the
+ * reshape here keeps that disagreement in the profile instead of as a
+ * field-name check inside the packager.
+ */
+export type MarketplaceFieldTransform = "identity" | "name" | "first";
+export interface MarketplaceEntryField {
+    name: string;
+    required: boolean;
+    source: MarketplaceFieldSource;
+    /** Defaults to `identity`. */
+    transform?: MarketplaceFieldTransform;
+}
+export interface MarketplaceAssetRule {
+    role: "icon" | "screenshot";
+    required: boolean;
+    extensions: string[];
+    maxBytes: number | null;
+}
+/**
+ * How a target's marketplace catalog is shaped.
+ *
+ * Catalog structure is tabular target behavior, so it belongs here rather than
+ * in the packager — the same rule that keeps paths and hook events out of the
+ * renderer. Optional on {@link TargetProfile} so adding it stays additive:
+ * every shipped profile defines it, but a consumer that has not been updated
+ * simply sees a new key rather than a changed shape.
+ */
+export interface MarketplaceProfile {
+    /** Catalog location per distribution mode; `null` when the mode is unsupported. */
+    catalog: Record<"repo" | "local", {
+        directory: string;
+        file: string;
+    } | null>;
+    /** Top-level array key inside the catalog document. */
+    entriesKey: string;
+    /**
+     * Fields written at the catalog document's top level, beside `entriesKey` —
+     * the marketplace's own identity as opposed to a plugin entry's. Optional so
+     * the addition stays additive for a target that names none.
+     */
+    documentFields?: MarketplaceEntryField[];
+    entryFields: MarketplaceEntryField[];
+    assets: MarketplaceAssetRule[];
+    /** `{name}`, `{version}`, `{target}`, and `{profile}` are substituted. */
+    archiveName: string;
+}
+export interface TargetProfile {
+    schemaVersion: string;
+    id: AgentTarget;
+    host: HostProfile;
+    /** Output profiles this target supports at all. */
+    profiles: AgentProfile[];
+    manifest: ManifestProfile;
+    paths: PathProfile;
+    placeholders: PlaceholderProfile;
+    hooks: HookProfile;
+    models: ModelProfile;
+    tools: ToolProfile;
+    rules: RuleProfile;
+    policies: PolicyProfile;
+    skills: SkillProfile;
+    outputs: Record<AgentProfile, OutputPattern[]>;
+    features: Record<FeatureKey, FeatureProfile>;
+    /** Catalog shape for `agent package`. Optional so adding it stayed additive. */
+    marketplace?: MarketplaceProfile;
+    /**
+     * Where `agent install` places a rendered tree. Optional so adding it stays
+     * additive, the same way `marketplace` was: a consumer that has not been
+     * updated sees a new key rather than a changed shape.
+     */
+    install?: InstallProfile;
+}
+/** How a host discovers an installed tree. */
+export type InstallLayout = "plugin-dir" | "merge" | "marketplace";
+/**
+ * A host file that activates a marketplace install. `null` when the root is
+ * auto-scanned and needs no edit.
+ */
+export type InstallActivation = {
+    file: string;
+    form: "claude-enabled-plugins";
+} | null;
+export interface InstallLocation {
+    /** `~`-prefixed for user scope; relative for project scope. */
+    root: string;
+    layout: InstallLayout;
+    profile: AgentProfile;
+    /** Host file that activates the install, or null when the root is auto-scanned. */
+    activation: InstallActivation;
+}
+export interface InstallProfile {
+    user: InstallLocation | null;
+    project: InstallLocation | null;
+}
+/**
+ * Compiles an {@link OutputPattern} into an anchored regular expression.
+ * `**` is only meaningful as a whole trailing segment.
+ */
+export declare function outputPatternToRegExp(pattern: string): RegExp;
+/** True when `candidate` is described by one of the target's declared output patterns. */
+export declare function describesPath(profile: TargetProfile, outputProfile: AgentProfile, candidate: string): boolean;
+export interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease: string | null;
+}
+export declare function parseSemver(value: string): ParsedVersion | null;
+/**
+ * Compares two plain versions. Deliberately not a range grammar — profiles
+ * record single bounds, so ordering is all that is needed.
+ */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** Returns the reasons a profile is internally inconsistent; empty when valid. */
+export declare function validateProfile(profile: TargetProfile): string[];