@iowarp/clio-coder 0.4.5 → 0.4.7

package/src/domains/extensions/command-schema.ts

@@ -0,0 +1,145 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+import type { ExtensionCapabilities, ExtensionCommandTool } from "./types.js";
+
+const TOOL_KEYS = new Set([
+	"name",
+	"description",
+	"runtime",
+	"entrypoint",
+	"inputSchema",
+	"timeoutMs",
+	"maxOutputBytes",
+]);
+const SCHEMA_KEYS = new Set([
+	"type",
+	"description",
+	"properties",
+	"required",
+	"additionalProperties",
+	"items",
+	"enum",
+	"minimum",
+	"maximum",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems",
+]);
+const TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+
+function record(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function extensionToolName(id: string, name: string): string {
+	return `extension_${id}__${name}`;
+}
+
+function validateSchema(value: unknown, depth = 0): asserts value is Record<string, unknown> {
+	if (depth > 12 || !record(value))
+		throw new Error("inputSchema must be a JSON schema object with at most 12 nesting levels");
+	for (const key of Object.keys(value)) {
+		if (!SCHEMA_KEYS.has(key)) throw new Error(`unsupported inputSchema keyword '${key}'`);
+	}
+	if (typeof value.type !== "string" || !TYPES.has(value.type))
+		throw new Error("inputSchema.type must be a supported JSON type");
+	if (value.description !== undefined && typeof value.description !== "string")
+		throw new Error("inputSchema.description must be a string");
+	if (
+		value.enum !== undefined &&
+		(!Array.isArray(value.enum) ||
+			value.enum.length === 0 ||
+			value.enum.some((item) => item !== null && typeof item === "object"))
+	) {
+		throw new Error("inputSchema.enum must contain JSON scalar values");
+	}
+	for (const key of ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"]) {
+		if (value[key] !== undefined && (typeof value[key] !== "number" || !Number.isFinite(value[key])))
+			throw new Error(`inputSchema.${key} must be finite`);
+	}
+	if (value.type === "object") {
+		if (!record(value.properties) || value.additionalProperties !== false)
+			throw new Error("object inputSchema requires properties and additionalProperties: false");
+		for (const [key, child] of Object.entries(value.properties)) {
+			if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error("unsafe inputSchema property name");
+			validateSchema(child, depth + 1);
+		}
+		if (
+			value.required !== undefined &&
+			(!Array.isArray(value.required) ||
+				value.required.some((key) => typeof key !== "string" || !Object.hasOwn(value.properties as object, key)))
+		) {
+			throw new Error("inputSchema.required must name declared properties");
+		}
+	} else if (value.type === "array") {
+		validateSchema(value.items, depth + 1);
+	}
+}
+
+export function parseExtensionCapabilities(value: unknown, id: string): ExtensionCapabilities {
+	if (
+		!record(value) ||
+		Object.keys(value).some((key) => key !== "tools") ||
+		!Array.isArray(value.tools) ||
+		value.tools.length === 0 ||
+		value.tools.length > 32
+	) {
+		throw new Error("capabilities must contain tools with between 1 and 32 command declarations");
+	}
+	if (id.includes("__")) throw new Error("v2 extension id cannot contain double underscores");
+	const names = new Set<string>();
+	const tools: ExtensionCommandTool[] = value.tools.map((tool) => {
+		if (!record(tool)) throw new Error("capabilities.tools entries must be objects");
+		for (const key of Object.keys(tool)) if (!TOOL_KEYS.has(key)) throw new Error(`unknown command tool key '${key}'`);
+		if (typeof tool.name !== "string" || !/^[a-z][a-z0-9_]*$/.test(tool.name) || tool.name.includes("__"))
+			throw new Error("command tool name must use lowercase letters, digits, and single underscores");
+		const name = extensionToolName(id, tool.name);
+		if (name.length > 64 || !/^[a-zA-Z0-9_-]+$/.test(name))
+			throw new Error("qualified command tool name must use provider-safe characters and fit 64 characters");
+		if (names.has(name)) throw new Error(`duplicate command tool name '${name}'`);
+		names.add(name);
+		if (typeof tool.description !== "string" || tool.description.trim().length === 0 || tool.description.length > 2000)
+			throw new Error("command tool description must contain 1 to 2000 characters");
+		if (tool.runtime !== "node" && tool.runtime !== "python3")
+			throw new Error("command tool runtime must be node or python3");
+		if (
+			typeof tool.entrypoint !== "string" ||
+			tool.entrypoint.includes("\0") ||
+			tool.entrypoint.includes("\\") ||
+			path.isAbsolute(tool.entrypoint) ||
+			tool.entrypoint.split("/").some((part) => part === ".." || part === "." || part === "")
+		)
+			throw new Error("command tool entrypoint must be a contained relative file path");
+		validateSchema(tool.inputSchema);
+		if (tool.inputSchema.type !== "object") throw new Error("command tool inputSchema root must be object");
+		for (const [key, maximum] of [
+			["timeoutMs", 300000],
+			["maxOutputBytes", 1048576],
+		] as const) {
+			const limit = tool[key];
+			if (limit !== undefined && (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > maximum))
+				throw new Error(`command tool ${key} must be between 1 and ${maximum}`);
+		}
+		return structuredClone(tool) as unknown as ExtensionCommandTool;
+	});
+	return { tools };
+}
+
+/** Entry paths must resolve to ordinary package files, including every parent directory. */
+export function resolveExtensionEntrypoint(root: string, entrypoint: string): string {
+	const canonicalRoot = realpathSync(root);
+	let cursor = canonicalRoot;
+	for (const segment of entrypoint.split("/")) {
+		if (segment === ".." || segment === "." || segment.length === 0)
+			throw new Error("invalid command entrypoint segment");
+		cursor = path.join(cursor, segment);
+		if (lstatSync(cursor).isSymbolicLink()) throw new Error("command entrypoint cannot contain symbolic links");
+	}
+	const stat = lstatSync(cursor);
+	if (!stat.isFile() || stat.nlink !== 1) throw new Error("command entrypoint must be an ordinary file with one link");
+	const relative = path.relative(canonicalRoot, realpathSync(cursor));
+	if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+		throw new Error("command entrypoint escapes extension root");
+	return cursor;
+}

package/src/domains/extensions/command-tools.ts

@@ -0,0 +1,15 @@
+import type { DynamicToolName } from "../../core/tool-names.js";
+import { extensionToolName } from "./command-schema.js";
+import { listInstalledExtensions } from "./state.js";
+import { isLoadableExtension } from "./types.js";
+
+/** Available names for dispatch planning; registry construction re-verifies captured declarations. */
+export function enabledHarnessExtensionToolNames(cwd = process.cwd()): ReadonlySet<DynamicToolName> {
+	return new Set(
+		listInstalledExtensions(cwd)
+			.filter(isLoadableExtension)
+			.flatMap((entry) =>
+				(entry.capabilities?.tools ?? []).map((tool) => extensionToolName(entry.id, tool.name) as DynamicToolName),
+			),
+	);
+}

package/src/domains/extensions/compatibility.ts

@@ -66,6 +66,13 @@ function parseSemVer(value: string): SemVer | null {
 	return { major, minor, patch, prerelease: parsedPrerelease };
 }
 
+/** Exact, bounded manifest version; range conveniences such as a v prefix are excluded. */
+export function isSemanticVersion(value: unknown): value is string {
+	return (
+		typeof value === "string" && value.length <= MAX_RANGE_CHARS && /^[0-9]/.test(value) && parseSemVer(value) !== null
+	);
+}
+
 function parsePart(value: string | undefined): number | null {
 	if (value === undefined || value === "x" || value === "X" || value === "*") return null;
 	const parsed = Number(value);

package/src/domains/extensions/contract.ts

@@ -6,8 +6,6 @@ import type {
 	ExtensionListOptions,
 	ExtensionMutationResult,
 	ExtensionReloadPrepareResult,
-	ExtensionResourceKind,
-	ExtensionResourceRoot,
 	ExtensionSnapshot,
 	InstalledExtension,
 } from "./manager.js";
@@ -19,8 +17,6 @@ export interface ExtensionsContract extends DomainContract {
 	enable(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
 	disable(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
 	remove(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
-	/** Committed projection for the bundle's cwd; ephemeral generation-0 build for any other cwd. */
-	resourceRoots(kind: ExtensionResourceKind, cwd?: string): ExtensionResourceRoot[];
 	snapshot(): ExtensionSnapshot | null;
 	generation(): number;
 	/**

package/src/domains/extensions/discovery.ts

@@ -1,28 +1,20 @@
-import { type Dirent, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { type Dirent, existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parseExtensionCapabilities, resolveExtensionEntrypoint } from "./command-schema.js";
 import { evaluateClioCompatibility } from "./compatibility.js";
-import type {
-	ClioExtensionManifest,
-	ExtensionCandidate,
-	ExtensionDiagnostic,
-	ExtensionManifestResources,
-} from "./types.js";
+import { parseExtensionRuntime } from "./runtime-schema.js";
+import type { ClioExtensionManifest, ExtensionCandidate, ExtensionDiagnostic } from "./types.js";
 
 const MANIFEST_NAMES = ["clio-coder-extension.yaml", "clio-coder-extension.yml", "clio-coder-extension.json"] as const;
-const MANIFEST_KEYS = new Set([
-	"manifestVersion",
-	"id",
-	"name",
-	"version",
-	"description",
-	"resources",
-	"tools",
-	"settings",
-	"compatibility",
-]);
-const RESOURCE_KEYS = new Set(["skills", "prompts", "agents", "fleets", "themes"]);
+const MANIFEST_KEYS = new Set(["id", "name", "version", "description", "compatibility", "capabilities", "runtime"]);
 const COMPATIBILITY_KEYS = new Set(["clio"]);
+/**
+ * Keys a domain package used to declare here. They are named so the refusal
+ * points at the plugin installer instead of reading as a typo.
+ */
+const PLUGIN_OWNED_KEYS = new Set(["resources", "skills", "prompts", "agents", "fleets", "themes"]);
+const PLUGIN_GUIDANCE = "domain resources belong in a plugin: clio-coder library install <path>";
 
 function compareNames(a: { name: string }, b: { name: string }): number {
 	return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
@@ -66,183 +58,23 @@ function rejectUnknownKeys(
 	}
 }
 
-function normalizeResources(
-	value: unknown,
+function rejectManifestKeys(
+	value: Record<string, unknown>,
 	manifestPath: string,
 	diagnostics: ExtensionDiagnostic[],
-): ExtensionManifestResources {
-	if (value === undefined) return {};
-	if (!isRecord(value)) {
-		diagnostics.push({ type: "error", message: "resources must be an object", path: manifestPath });
-		return {};
-	}
-	rejectUnknownKeys(value, RESOURCE_KEYS, "resources", manifestPath, diagnostics);
-	const out: ExtensionManifestResources = {};
-	for (const kind of RESOURCE_KEYS) {
-		if (value[kind] === undefined) continue;
-		const resourcePath = trimString(value[kind]);
-		if (!resourcePath) {
-			diagnostics.push({
-				type: "error",
-				message: `resources.${kind} must be a non-empty string`,
-				path: manifestPath,
-			});
-			continue;
-		}
-		out[kind as keyof ExtensionManifestResources] = resourcePath;
-	}
-	return out;
-}
-
-function contained(root: string, candidate: string): boolean {
-	const relative = path.relative(root, candidate);
-	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
-}
-
-function validateResourceTree(
-	root: string,
-	resourcePath: string,
-	kind: string,
-	diagnostics: ExtensionDiagnostic[],
 ): void {
-	if (path.isAbsolute(resourcePath)) {
-		diagnostics.push({ type: "error", message: `resources.${kind} must be relative`, path: resourcePath });
-		return;
-	}
-	const resolvedRoot = path.resolve(root);
-	const resolved = path.resolve(resolvedRoot, resourcePath);
-	if (!contained(resolvedRoot, resolved) || resolved === resolvedRoot) {
-		diagnostics.push({ type: "error", message: `resources.${kind} escapes the extension root`, path: resourcePath });
-		return;
-	}
-	let canonicalRoot: string;
-	let canonicalResource: string;
-	try {
-		canonicalRoot = realpathSync(resolvedRoot);
-		canonicalResource = realpathSync(resolved);
-		if (!statSync(resolved).isDirectory()) {
-			diagnostics.push({ type: "error", message: `resources.${kind} is not a directory`, path: resolved });
-			return;
-		}
-	} catch (error) {
+	for (const key of Object.keys(value).sort()) {
+		if (MANIFEST_KEYS.has(key)) continue;
 		diagnostics.push({
 			type: "error",
-			message: `resources.${kind} cannot be resolved: ${error instanceof Error ? error.message : String(error)}`,
-			path: resolved,
+			message: PLUGIN_OWNED_KEYS.has(key)
+				? `harness extensions cannot declare '${key}'; ${PLUGIN_GUIDANCE}`
+				: `unknown manifest key '${key}'`,
+			path: manifestPath,
 		});
-		return;
-	}
-	if (!contained(canonicalRoot, canonicalResource)) {
-		diagnostics.push({ type: "error", message: `resources.${kind} escapes through a symbolic link`, path: resolved });
-		return;
-	}
-
-	const pending = [resolved];
-	while (pending.length > 0) {
-		const directory = pending.pop();
-		if (!directory) continue;
-		for (const entry of readdirSync(directory, { withFileTypes: true }).sort(compareNames)) {
-			const candidate = path.join(directory, entry.name);
-			if (entry.isSymbolicLink()) {
-				try {
-					const canonicalTarget = realpathSync(candidate);
-					if (!contained(canonicalRoot, canonicalTarget)) {
-						diagnostics.push({
-							type: "error",
-							message: `resources.${kind} contains an escaping symbolic link`,
-							path: candidate,
-						});
-						continue;
-					}
-					const targetStat = statSync(candidate);
-					if (!targetStat.isDirectory() && !targetStat.isFile()) {
-						diagnostics.push({
-							type: "error",
-							message: `resources.${kind} contains a symbolic link to an unsupported filesystem entry`,
-							path: candidate,
-						});
-					} else if (targetStat.isFile() && targetStat.nlink !== 1) {
-						diagnostics.push({
-							type: "error",
-							message: `resources.${kind} contains a symbolic link to a hard-linked file`,
-							path: candidate,
-						});
-					}
-				} catch (error) {
-					diagnostics.push({
-						type: "error",
-						message: `resources.${kind} contains an unresolved symbolic link: ${error instanceof Error ? error.message : String(error)}`,
-						path: candidate,
-					});
-				}
-			} else if (entry.isDirectory()) {
-				pending.push(candidate);
-			} else if (entry.isFile()) {
-				try {
-					if (lstatSync(candidate).nlink !== 1) {
-						diagnostics.push({
-							type: "error",
-							message: `resources.${kind} contains a hard-linked file`,
-							path: candidate,
-						});
-					}
-				} catch (error) {
-					diagnostics.push({
-						type: "error",
-						message: `resources.${kind} entry could not be inspected: ${error instanceof Error ? error.message : String(error)}`,
-						path: candidate,
-					});
-				}
-			} else {
-				diagnostics.push({
-					type: "error",
-					message: `resources.${kind} contains an unsupported filesystem entry`,
-					path: candidate,
-				});
-			}
-		}
 	}
 }
 
-function validateResourceRoots(
-	root: string,
-	resources: ExtensionManifestResources,
-	diagnostics: ExtensionDiagnostic[],
-): void {
-	for (const [kind, resourcePath] of Object.entries(resources)) {
-		if (resourcePath) validateResourceTree(root, resourcePath, kind, diagnostics);
-	}
-}
-
-function stringArray(
-	value: unknown,
-	field: "tools" | "settings",
-	manifestPath: string,
-	diagnostics: ExtensionDiagnostic[],
-): string[] | undefined {
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value)) {
-		diagnostics.push({ type: "error", message: `${field} must be an array of non-empty strings`, path: manifestPath });
-		return undefined;
-	}
-	const out: string[] = [];
-	const seen = new Set<string>();
-	for (const entry of value) {
-		const parsed = trimString(entry);
-		if (!parsed) {
-			diagnostics.push({ type: "error", message: `${field} must contain only non-empty strings`, path: manifestPath });
-			continue;
-		}
-		if (seen.has(parsed)) {
-			diagnostics.push({ type: "error", message: `${field} contains duplicate entry '${parsed}'`, path: manifestPath });
-			continue;
-		}
-		seen.add(parsed);
-		out.push(parsed);
-	}
-	return out.length > 0 ? out : undefined;
-}
-
 export function parseExtensionManifest(
 	value: unknown,
 	manifestPath: string,
@@ -254,10 +86,7 @@ export function parseExtensionManifest(
 	if (!isRecord(value)) {
 		return { diagnostics: [{ type: "error", message: "extension manifest must be an object", path: manifestPath }] };
 	}
-	rejectUnknownKeys(value, MANIFEST_KEYS, "manifest", manifestPath, diagnostics);
-	if (value.manifestVersion !== 1) {
-		diagnostics.push({ type: "error", message: "manifestVersion must be 1", path: manifestPath });
-	}
+	rejectManifestKeys(value, manifestPath, diagnostics);
 	const id = trimString(value.id);
 	const name = trimString(value.name) ?? id;
 	const version = trimString(value.version);
@@ -269,9 +98,30 @@ export function parseExtensionManifest(
 	}
 	if (!version) diagnostics.push({ type: "error", message: "version is required", path: manifestPath });
 	if (!description) diagnostics.push({ type: "error", message: "description is required", path: manifestPath });
-	const resources = normalizeResources(value.resources, manifestPath, diagnostics);
-	const tools = stringArray(value.tools, "tools", manifestPath, diagnostics);
-	const settings = stringArray(value.settings, "settings", manifestPath, diagnostics);
+	let capabilities: ClioExtensionManifest["capabilities"];
+	let runtime: ClioExtensionManifest["runtime"];
+	if (value.runtime !== undefined) {
+		try {
+			runtime = parseExtensionRuntime(value.runtime);
+		} catch (error) {
+			diagnostics.push({
+				type: "error",
+				message: error instanceof Error ? error.message : String(error),
+				path: manifestPath,
+			});
+		}
+	}
+	if (value.capabilities !== undefined) {
+		try {
+			capabilities = parseExtensionCapabilities(value.capabilities, id ?? "");
+		} catch (error) {
+			diagnostics.push({
+				type: "error",
+				message: error instanceof Error ? error.message : String(error),
+				path: manifestPath,
+			});
+		}
+	}
 	let compatibility: ClioExtensionManifest["compatibility"];
 	if (value.compatibility !== undefined) {
 		if (!isRecord(value.compatibility)) {
@@ -306,16 +156,9 @@ export function parseExtensionManifest(
 	if (!id || !name || !version || !description || diagnostics.some((diag) => diag.type === "error")) {
 		return { diagnostics };
 	}
-	const manifest: ClioExtensionManifest = {
-		manifestVersion: 1,
-		id,
-		name,
-		version,
-		description,
-		resources,
-	};
-	if (tools) manifest.tools = tools;
-	if (settings) manifest.settings = settings;
+	const manifest: ClioExtensionManifest = { id, name, version, description };
+	if (runtime) manifest.runtime = runtime;
+	if (capabilities) manifest.capabilities = capabilities;
 	if (compatibility && Object.keys(compatibility).length > 0) manifest.compatibility = compatibility;
 	const clioRange = manifest.compatibility?.clio;
 	if (clioRange !== undefined) {
@@ -354,7 +197,28 @@ export function loadManifestFromRoot(root: string): ExtensionCandidate {
 	}
 	try {
 		const parsed = parseExtensionManifest(readJsonOrYaml(manifestPath), manifestPath);
-		if (parsed.manifest) validateResourceRoots(root, parsed.manifest.resources, parsed.diagnostics);
+		if (parsed.manifest?.runtime) {
+			try {
+				resolveExtensionEntrypoint(root, parsed.manifest.runtime.entrypoint);
+			} catch (error) {
+				parsed.diagnostics.push({
+					type: "error",
+					message: `runtime: ${error instanceof Error ? error.message : String(error)}`,
+					path: manifestPath,
+				});
+			}
+		}
+		for (const tool of parsed.manifest?.capabilities?.tools ?? []) {
+			try {
+				resolveExtensionEntrypoint(root, tool.entrypoint);
+			} catch (error) {
+				parsed.diagnostics.push({
+					type: "error",
+					message: `command tool ${tool.name}: ${error instanceof Error ? error.message : String(error)}`,
+					path: manifestPath,
+				});
+			}
+		}
 		return {
 			path: root,
 			manifestPath,

package/src/domains/extensions/extension.ts

@@ -3,7 +3,6 @@ import type { ExtensionsContract } from "./contract.js";
 import {
 	disableExtension,
 	discoverExtensionPackages,
-	enabledExtensionResourceRoots,
 	enableExtension,
 	installExtension,
 	listInstalledExtensions,
@@ -100,9 +99,6 @@ export function createExtensionsBundle(
 		remove(id, options = {}) {
 			return removeExtension(id, options);
 		},
-		resourceRoots(kind, requestedCwd) {
-			return enabledExtensionResourceRoots(kind, requestedCwd ?? cwd());
-		},
 		snapshot() {
 			return store.current();
 		},

package/src/domains/extensions/index.ts

@@ -27,13 +27,9 @@ export {
 	type ExtensionReloadRejection,
 	type ExtensionReloadRejectionReason,
 	type ExtensionReloadResult,
-	type ExtensionResourceKind,
-	type ExtensionResourceRoot,
 	type ExtensionScope,
 	type ExtensionSnapshot,
 	type ExtensionSnapshotDiagnostics,
-	type ExtensionStateUpgradeReport,
-	enabledExtensionResourceRoots,
 	enableExtension,
 	extensionManifestYaml,
 	extensionSnapshotFor,
@@ -46,7 +42,6 @@ export {
 	listInstalledExtensions,
 	parseExtensionManifest,
 	removeExtension,
-	upgradeLegacyExtensionInstallState,
 } from "./manager.js";
 export { ExtensionsManifest } from "./manifest.js";
 export {
@@ -56,3 +51,4 @@ export {
 	EXTENSION_SNAPSHOT_DIAGNOSTIC_MESSAGE_CAP,
 	EXTENSION_SNAPSHOT_DIAGNOSTIC_PER_PACKAGE_CAP,
 } from "./snapshot.js";
+export type { ExtensionCapabilities, ExtensionCommandTool } from "./types.js";

package/src/domains/extensions/manager.ts

@@ -4,7 +4,7 @@ export {
 	findExtensionManifestPath,
 	parseExtensionManifest,
 } from "./discovery.js";
-export { enabledExtensionResourceRoots, extensionResourcePath, extensionSnapshotFor } from "./resources.js";
+export { extensionSnapshotFor } from "./snapshot-access.js";
 export type { InstalledExtensionRecord } from "./state.js";
 export {
 	disableExtension,
@@ -14,7 +14,6 @@ export {
 	listInstalledExtensionRecords,
 	listInstalledExtensions,
 	removeExtension,
-	upgradeLegacyExtensionInstallState,
 } from "./state.js";
 export type {
 	ClioExtensionManifest,
@@ -24,7 +23,6 @@ export type {
 	ExtensionInstallOptions,
 	ExtensionInstallResult,
 	ExtensionListOptions,
-	ExtensionManifestResources,
 	ExtensionMutationResult,
 	ExtensionProvenance,
 	ExtensionReloadCandidate,
@@ -33,13 +31,10 @@ export type {
 	ExtensionReloadRejection,
 	ExtensionReloadRejectionReason,
 	ExtensionReloadResult,
-	ExtensionResourceKind,
-	ExtensionResourceRoot,
 	ExtensionScope,
 	ExtensionSnapshot,
 	ExtensionSnapshotDiagnostics,
 	ExtensionState,
-	ExtensionStateUpgradeReport,
 	InstalledExtension,
 	LoadableExtension,
 } from "./types.js";

package/src/domains/extensions/operator-commands.ts

@@ -0,0 +1,29 @@
+export interface ExtensionCommandRow {
+	origin: "extension";
+	invocation: string;
+	extensionId: string;
+	scope: "user" | "project";
+	description: string;
+	generation: number;
+	available: boolean;
+	reason?: string;
+}
+export function extensionInvocation(id: string, command: string): string {
+	return `ext:${id}:${command}`;
+}
+/** Canonical commands, including existing dotted/underscored extension IDs. */
+export function isExtensionCommandToken(token: string): boolean {
+	return /^ext:[^\s/]+$/u.test(token);
+}
+/** Same collision projection is consumed by completion, inspection, and submission. */
+export function resolveExtensionCommands(
+	rows: readonly ExtensionCommandRow[],
+	promptNames: readonly string[],
+): ExtensionCommandRow[] {
+	const prompts = new Set(promptNames.map((name) => name.toLowerCase()));
+	return rows.map((row) =>
+		prompts.has(row.invocation.toLowerCase())
+			? { ...row, available: false, reason: "invocation belongs to an existing prompt template" }
+			: row,
+	);
+}