@iowarp/clio-coder 0.4.6 → 0.4.7

package/src/domains/plugins/types.ts

@@ -0,0 +1,217 @@
+export type PluginScope = "user" | "project";
+export type PluginResourceKind = "skills" | "prompts" | "agents" | "fleets" | "themes";
+export type PluginComponentKind = "prompt" | "agent" | "skill" | "fleet" | "script" | "resource" | "tool";
+export type PluginResources = Partial<Record<PluginResourceKind, string>>;
+
+export interface PluginDiagnostic {
+	type: "warning" | "error";
+	message: string;
+	path?: string;
+	/** Machine-readable reason for writer refusals; message text is unchanged. */
+	code?: PluginDiagnosticCode;
+	/** The reviewed fact that changed, for `stale_plan`. */
+	changed?: { scope: PluginScope; id: string; fact: keyof PluginExpectedCopy; expected: unknown; observed: unknown };
+}
+export type PluginDiagnosticCode = "stale_plan" | "locked" | "dependents";
+
+/**
+ * One reviewed copy fact. Every field present is rechecked inside the writer's
+ * lock before any write; a mismatch refuses with `stale_plan`.
+ */
+export interface PluginExpectedCopy {
+	scope: PluginScope;
+	id: string;
+	/**
+	 * A full snapshot (default) also fails when a fact appears or disappears.
+	 * `partial` checks only the facts listed; reserved for the legacy
+	 * digest-only update path that never reviewed the other facts.
+	 */
+	partial?: boolean;
+	/** Install record present in that scope's state.json. */
+	recorded: boolean;
+	/** Observed full-tree digest, or absent. */
+	tree: "absent" | string;
+	enabled?: boolean;
+	recordedDigest?: string;
+	kind?: LibraryEntryKind;
+	trust?: PackageTrust;
+	/** Compared JSON-equal, so identical bytes with a different origin still stale a plan. */
+	origin?: PluginOrigin;
+}
+export interface PluginExpectedState {
+	copies: PluginExpectedCopy[];
+}
+
+export interface PluginComponent {
+	kind: PluginComponentKind;
+	id: string;
+	path: string;
+	requires?: string[];
+}
+
+export interface ClioPluginConfiguration {
+	manifestVersion: 1;
+	/** Absent in portable bundles means plugin. All kinds share the package lifecycle. */
+	kind?: LibraryEntryKind;
+	requires?: LibraryRequirementRef[];
+	/** Contained Suite v2 files, selected explicitly by `clio-coder eval`. */
+	evals?: Record<string, string>;
+	compatibility?: { clio?: string };
+	resources: PluginResources;
+	components: PluginComponent[];
+}
+
+/** Standard identity stays canonical; `clio` is the validated runtime projection. */
+export interface PluginManifest {
+	$schema: string;
+	name: string;
+	version?: string;
+	description?: string;
+	author?: { name?: string; email?: string; url?: string };
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	extensions?: Record<string, Record<string, unknown>>;
+	clio: ClioPluginConfiguration;
+}
+
+export interface PluginCandidate {
+	path: string;
+	manifestPath?: string;
+	manifest?: PluginManifest;
+	valid: boolean;
+	diagnostics: PluginDiagnostic[];
+	contentDigest?: string;
+	manifestDigest?: string;
+}
+
+/** Format of a foreign package as it was found on disk; author labels never set this. */
+export type ForeignPackageFormat = "portable" | "claude-code" | "codex";
+/**
+ * `interop` is a package imported from an installed local agent; `import` is an
+ * explicit source path or GitHub tree. Both always carry foreign trust.
+ */
+export type PluginOrigin =
+	| string
+	| { kind: "local" | "catalog" | "github"; source: string }
+	| { kind: "interop"; host: string; source: string; format?: ForeignPackageFormat; marketplace?: string }
+	| {
+			kind: "import";
+			source: string;
+			transport: "local" | "github";
+			format: ForeignPackageFormat;
+			host?: string;
+			marketplace?: string;
+	  };
+export function isForeignPluginOrigin(origin: PluginOrigin | undefined): boolean {
+	return typeof origin === "object" && (origin.kind === "interop" || origin.kind === "import");
+}
+export type PackageTrust = "trusted" | "foreign";
+
+export interface PluginProvenance {
+	id: string;
+	scope: PluginScope;
+	sourcePath?: string;
+	canonicalRoot: string;
+	manifestDigest: string;
+	contentDigest: string;
+}
+
+export interface InstalledPlugin {
+	id: string;
+	kind?: LibraryEntryKind;
+	trust?: PackageTrust;
+	name: string;
+	version: string;
+	description: string;
+	scope: PluginScope;
+	rootPath: string;
+	manifestPath: string;
+	enabled: boolean;
+	valid: boolean;
+	compatible: boolean;
+	effective: boolean;
+	loadable: boolean;
+	resources: PluginResources;
+	manifest?: PluginManifest;
+	provenance?: PluginProvenance;
+	observedContentDigest?: string;
+	overriddenBy?: PluginScope;
+	diagnostics: PluginDiagnostic[];
+}
+
+export interface PluginResourceRoot {
+	id: string;
+	scope: PluginScope;
+	path: string;
+	rootPath: string;
+	source: string;
+	provenance: PluginProvenance;
+	generation: number;
+	trust?: PackageTrust;
+}
+
+export interface PluginListOptions {
+	cwd?: string;
+	scope?: PluginScope;
+	all?: boolean;
+}
+
+export interface PluginMutationOptions extends PluginListOptions {
+	expect?: PluginExpectedState;
+}
+
+export interface PluginInstallOptions extends PluginMutationOptions {
+	force?: boolean;
+	expectedDigest?: string;
+	expectedId?: string;
+	expectedVersion?: string;
+	origin?: PluginOrigin;
+	trust?: PackageTrust;
+	expectedKind?: LibraryEntryKind;
+}
+
+/** One kind-aware publication seam for library and interop adapters. */
+export interface LibraryPackageInstallInput extends Omit<PluginInstallOptions, "expectedKind"> {
+	kind: LibraryEntryKind;
+	sourcePath: string;
+	scope: PluginScope;
+	origin: PluginOrigin;
+	trust: PackageTrust;
+}
+
+export interface PluginMutationResult {
+	plugin?: InstalledPlugin;
+	removed?: { id: string; scope: PluginScope; path: string };
+	recovery?: { stateBackup?: string; packageBackup?: string };
+	diagnostics: PluginDiagnostic[];
+}
+
+export type PluginInstallResult = PluginMutationResult;
+
+export interface PluginInstallRecord {
+	kind?: LibraryEntryKind;
+	installedAt: string;
+	source: string;
+	origin?: PluginOrigin;
+	contentDigest: string;
+	trust?: PackageTrust;
+}
+
+export interface PluginState {
+	version: 1;
+	disabled: string[];
+	installed: Record<string, PluginInstallRecord>;
+}
+
+export interface PluginSnapshot {
+	version: 1;
+	generation: number;
+	cwd: string;
+	digest: string;
+	packages: ReadonlyArray<InstalledPlugin>;
+	resourceRoots: Readonly<Record<PluginResourceKind, ReadonlyArray<PluginResourceRoot>>>;
+}
+
+import type { LibraryEntryKind, LibraryRequirementRef } from "../resources/library-types.js";

package/src/domains/prompts/extension.ts

@@ -229,10 +229,17 @@ export function createPromptsBundle(
 			// Extension prompt and skill roots feed fragments through the
 			// resources domain; a committed generation with new content means
 			// the table must be rebuilt from the new roots.
-			unsubscribeExtensionsReload = context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
+			const onResourceReload = (payload: unknown) => {
 				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
 				reload();
-			});
+			};
+			const unsubscribe = [
+				context.bus.on(BusChannels.ExtensionsReloaded, onResourceReload),
+				context.bus.on(BusChannels.PluginsReloaded, () => reload()),
+			];
+			unsubscribeExtensionsReload = () => {
+				for (const stop of unsubscribe) stop();
+			};
 		},
 		async stop() {
 			unsubscribeContextSources?.();

package/src/domains/prompts/fragments/operating/skills.md

@@ -7,13 +7,13 @@ description: Coordinator skill suggestion discipline; rendered only when context
 # Skills
 
 Skills are operator-activated workflows: git delivery, planning, coding
-practice, context priming and handoff, research, and plan stress-testing.
-context (scope="skills") is the one authoritative listing of installed
-and marketplace skills; never guess the inventory or search the
-repository for one. When a task has one of those shapes, list them,
-suggest the best match as /skill <name> (the sequence in order when
-several compose), and continue the task without it: only the operator
-activates or installs a skill, and a [Marketplace] reminder states its
-own offer options. When the operator names a skill or asks how one
-works, answer from that listing. If nothing fits, proceed normally and
-suggest nothing.
+practice, context priming/handoff, research, plan stress-testing.
+context (scope="skills") lists installed and marketplace skills; never
+guess it or search the repository for one. When a task has one of those
+shapes, list them, suggest the best match as /skill <name> (in order
+when several compose), and continue without it: only the operator
+activates or installs a skill; a [Marketplace] reminder states its
+own offer options. When the operator names a skill or asks how it
+works, answer from it. If nothing fits, suggest none. context
+(scope="library") is the read-only catalog of recipes and installable
+packages; it activates nothing.

package/src/domains/resources/common-loader.ts

@@ -2,13 +2,14 @@ import { type Dirent, existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { clioConfigDir } from "../../core/xdg.js";
-import { type ExtensionResourceKind, enabledExtensionResourceRoots } from "../extensions/index.js";
+import { enabledPluginResourceRoots, type PluginResourceKind } from "../plugins/index.js";
 import type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
 
 export interface ResourceRoot {
 	path: string;
-	/** Package root for safely resolving extension-relative prompt references. */
+	/** Package root for safely resolving package-relative prompt references. */
 	rootPath?: string;
+	plugin?: boolean;
 	scope: ResourceScope;
 	source?: string;
 	/** Collision rank, higher wins. See {@link ResourceSourceInfo.precedence}. */
@@ -23,7 +24,7 @@ export interface ResourceRoot {
  * roots exactly the way a foreign skill root does.
  */
 export const COMPAT_RESOURCE_PRECEDENCE = {
-	extension: 10,
+	package: 10,
 	userCompat: 20,
 	user: 30,
 	projectCompat: 40,
@@ -42,14 +43,16 @@ export type FrontmatterSplitResult =
 			body: string;
 	  };
 
-export function defaultScopedResourceRoots(kind: ExtensionResourceKind, cwd: string): ResourceRoot[] {
+export function defaultScopedResourceRoots(kind: PluginResourceKind, cwd: string): ResourceRoot[] {
 	return [
-		...enabledExtensionResourceRoots(kind, cwd).map((root) => ({
+		...enabledPluginResourceRoots(kind, cwd).map((root) => ({
 			path: root.path,
 			rootPath: root.rootPath,
+			plugin: true,
 			scope: "package" as const,
 			source: root.source,
-			precedence: COMPAT_RESOURCE_PRECEDENCE.extension,
+			precedence: COMPAT_RESOURCE_PRECEDENCE.package,
+			trusted: root.trust !== "foreign",
 		})),
 		{
 			path: path.join(clioConfigDir(), kind),

package/src/domains/resources/index.ts

@@ -20,6 +20,7 @@ export { resolveResourceCollisions } from "./collision.js";
 export type { ResourceList, ResourcesContract } from "./contract.js";
 export {
 	classifyLibraryRequirements,
+	commitLibraryInstallPlan,
 	confirmLibraryRemote,
 	discoverLibrary,
 	installLibraryPlan,
@@ -28,14 +29,79 @@ export {
 	type LibraryEntry,
 	type LibraryInstallPlan,
 	type LibraryRequirementStatus,
+	libraryEntryDrift,
 	libraryEntryInstalled,
 	libraryEntryPin,
 	libraryEntryRef,
 	libraryInstallPath,
+	pinLibraryEntry,
 	planLibraryInstall,
+	planLibraryUpdate,
+	releaseLibraryPlan,
+	removeLibraryEntry,
+	resolveLibraryPackage,
 	resolveLibraryRequirements,
 	syncLibrary,
 } from "./library.js";
+export {
+	applyLibraryLifecycle,
+	type LibraryApplyResult,
+	type LibraryExpectedCopy,
+	type LibraryLifecyclePlan,
+	type LibraryLifecycleRequest,
+	type LibraryOperation,
+	type LibraryPackageIdentity,
+	type LibraryPlanStep,
+	type LibraryRefreshHost,
+	type LibraryRefreshResult,
+	type LibraryStepOutcome,
+	type LibraryStepStatus,
+	type LibraryStepVerification,
+	libraryImportOutcome,
+	libraryLifecyclePlanSummary,
+	planLibraryLifecycle,
+	pluginSnapshotRefreshHost,
+	releaseLibraryLifecycle,
+	retryLibraryRefresh,
+	verifyLibraryStep,
+} from "./library-actions.js";
+export {
+	classifyLibraryOrigin,
+	inspectLibraryCopy,
+	LIBRARY_INVENTORY_LIMITS,
+	type LibraryCopy,
+	type LibraryCopyInspection,
+	type LibraryCopyState,
+	type LibraryInventory,
+	type LibraryInventoryOptions,
+	type LibraryOrigin,
+	type LibraryOriginEvidence,
+	type LibraryPackageFormat,
+	type LibraryPackageRecord,
+	type LibraryResource,
+	type LibraryResourceAvailability,
+	type LibraryResourceKeyParts,
+	type LibraryResourceSourceClass,
+	libraryCopyState,
+	libraryResourceKey,
+	parseLibraryResourceKey,
+	readLibraryInventory,
+} from "./library-inventory.js";
+export {
+	isLibraryResourceKind,
+	LIBRARY_RESOURCE_KINDS,
+	type LibraryProvidedResource,
+	type LibraryResourceKind,
+} from "./library-types.js";
+export {
+	type LibraryPackageValidation,
+	type LibraryPackageValidationResult,
+	type LibraryResourceValidationRecord,
+	type LibraryValidationDiagnostic,
+	type LibraryValidationPrerequisite,
+	type LibraryValidationSeverity,
+	validateLibraryPackage,
+} from "./library-validation.js";
 export { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
 export { ResourcesManifest } from "./manifest.js";
 export {
@@ -45,6 +111,7 @@ export {
 	type PromptTemplateExpansion,
 	type PromptTemplateList,
 	type PromptTemplateRoot,
+	promptTemplateDisplayText,
 } from "./prompts/loader.js";
 export { parseCommandArgs, substituteArgs } from "./prompts/substitute.js";
 export { parseSkillEvals, type SkillEvalParseResult, type SkillEvalScenario } from "./skills/evals.js";