@fased/fased 0.1.36 → 0.1.37

package/dist/capabilities/catalog.js

@@ -0,0 +1,228 @@
+import { resolveFasedAgentPackageRootSync } from "../infra/fased-root.js";
+import { loadConfig } from "../config/io.js";
+import "../config/config.js";
+import { buildPluginMarketplaceReport } from "../plugins/marketplace.js";
+import fs from "node:fs";
+import path from "node:path";
+
+//#region src/capabilities/catalog.ts
+const CAPABILITY_STATES = [
+	"included",
+	"external-required",
+	"not-installed",
+	"installed",
+	"configured",
+	"ready",
+	"error"
+];
+const CATALOG_RELATIVE_PATH = path.join("config", "capability-catalog.json");
+const DELIVERY_VALUES = new Set([
+	"core",
+	"npm-addon",
+	"external-runtime"
+]);
+const CATEGORY_VALUES = new Set([
+	"core",
+	"crypto",
+	"channel",
+	"provider",
+	"runtime"
+]);
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(record, key, index) {
+	const value = record[key];
+	if (typeof value !== "string" || !value.trim()) {
+		throw new Error(`capability catalog entry ${index} requires ${key}`);
+	}
+	return value.trim();
+}
+function optionalString(record, key) {
+	const value = record[key];
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function parseCatalogEntry(value, index) {
+	if (!isRecord(value)) {
+		throw new Error(`capability catalog entry ${index} must be an object`);
+	}
+	const delivery = requiredString(value, "delivery", index);
+	if (!DELIVERY_VALUES.has(delivery)) {
+		throw new Error(`capability catalog entry ${index} has invalid delivery ${delivery}`);
+	}
+	const category = requiredString(value, "category", index);
+	if (!CATEGORY_VALUES.has(category)) {
+		throw new Error(`capability catalog entry ${index} has invalid category ${category}`);
+	}
+	const externalKind = optionalString(value, "externalKind");
+	if (externalKind && externalKind !== "browser" && externalKind !== "model-server" && externalKind !== "local-embeddings") {
+		throw new Error(`capability catalog entry ${index} has invalid externalKind ${externalKind}`);
+	}
+	return {
+		id: requiredString(value, "id", index),
+		label: requiredString(value, "label", index),
+		category,
+		delivery,
+		description: requiredString(value, "description", index),
+		docsPath: requiredString(value, "docsPath", index),
+		surface: requiredString(value, "surface", index),
+		...optionalString(value, "packageName") ? { packageName: optionalString(value, "packageName") } : {},
+		...optionalString(value, "pluginId") ? { pluginId: optionalString(value, "pluginId") } : {},
+		...optionalString(value, "channelId") ? { channelId: optionalString(value, "channelId") } : {},
+		...optionalString(value, "providerId") ? { providerId: optionalString(value, "providerId") } : {},
+		...externalKind ? { externalKind } : {},
+		...value.restartRequired === true ? { restartRequired: true } : {}
+	};
+}
+function resolveCatalogPath() {
+	const roots = [
+		resolveFasedAgentPackageRootSync({ moduleUrl: import.meta.url }),
+		resolveFasedAgentPackageRootSync({ cwd: process.cwd() }),
+		process.cwd()
+	].filter((entry, index, all) => Boolean(entry) && all.indexOf(entry) === index);
+	for (const root of roots) {
+		const candidate = path.join(root, CATALOG_RELATIVE_PATH);
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	throw new Error(`Fased capability catalog not found (${CATALOG_RELATIVE_PATH})`);
+}
+function loadCapabilityCatalog() {
+	const payload = JSON.parse(fs.readFileSync(resolveCatalogPath(), "utf8"));
+	if (!isRecord(payload) || !Array.isArray(payload.entries)) {
+		throw new Error("capability catalog must contain an entries array");
+	}
+	const entries = payload.entries.map(parseCatalogEntry);
+	const ids = new Set();
+	for (const entry of entries) {
+		if (ids.has(entry.id)) {
+			throw new Error(`duplicate capability catalog id: ${entry.id}`);
+		}
+		ids.add(entry.id);
+	}
+	return entries;
+}
+function configRecord(value) {
+	return isRecord(value) ? value : {};
+}
+function channelConfigured(config, channelId) {
+	const channel = configRecord(configRecord(config.channels)[channelId]);
+	return Object.keys(channel).length > 0;
+}
+function providerConfigured(config, providerId) {
+	return Boolean(config.models?.providers?.[providerId]);
+}
+function browserConfigured(config) {
+	const browser = configRecord(config.browser);
+	return browser.enabled === true || typeof browser.executablePath === "string" || typeof browser.cdpUrl === "string" || Object.keys(configRecord(browser.profiles)).length > 0;
+}
+function localMemoryConfigured(config) {
+	return config.agents?.defaults?.memorySearch?.provider === "local";
+}
+function actionForState(state) {
+	switch (state) {
+		case "not-installed": return "install";
+		case "external-required": return "connect";
+		case "installed":
+		case "included": return "configure";
+		case "configured": return "test";
+		case "error": return "repair";
+		case "ready": return "none";
+	}
+}
+function resolveCoreCapability(entry, plugins) {
+	if (entry.pluginId) {
+		const plugin = plugins.plugins.find((candidate) => candidate.id === entry.pluginId);
+		if (plugin?.status === "error") {
+			return {
+				state: "error",
+				detail: plugin.error ?? `${entry.label} failed to load.`
+			};
+		}
+	}
+	return {
+		state: "included",
+		detail: "Included in the Fased core runtime."
+	};
+}
+function resolveAddonCapability(entry, config, plugins) {
+	const plugin = plugins.plugins.find((candidate) => candidate.id === entry.pluginId || candidate.name === entry.packageName || candidate.channels.includes(entry.channelId ?? entry.id));
+	const installRecord = entry.pluginId ? config.plugins?.installs?.[entry.pluginId] : undefined;
+	const installed = Boolean(installRecord || plugin?.hasInstallRecord || plugin?.managed || plugin?.loaded && plugin.origin !== "bundled");
+	if (!installed) {
+		return {
+			state: "not-installed",
+			detail: `${entry.packageName ?? entry.label} is available as an optional npm add-on.`
+		};
+	}
+	if (plugin?.status === "error") {
+		return {
+			state: "error",
+			detail: plugin.error ?? `${entry.label} failed to load.`
+		};
+	}
+	const configured = entry.channelId ? channelConfigured(config, entry.channelId) : false;
+	if (configured && plugin?.loaded && plugin.enabled) {
+		return {
+			state: "configured",
+			detail: "Add-on is installed and configured. Run its live channel check for readiness."
+		};
+	}
+	return {
+		state: "installed",
+		detail: plugin?.loaded ? "Add-on is installed. Complete its configuration." : "Add-on is installed and requires a Gateway restart or enable step."
+	};
+}
+function resolveExternalCapability(entry, config) {
+	const configured = entry.providerId ? providerConfigured(config, entry.providerId) : entry.externalKind === "browser" ? browserConfigured(config) : entry.externalKind === "local-embeddings" ? localMemoryConfigured(config) : false;
+	if (configured) {
+		return {
+			state: "configured",
+			detail: "Fased is configured to use this external runtime. Test the connection for readiness."
+		};
+	}
+	return {
+		state: "external-required",
+		detail: "Install or run this runtime outside Fased, then connect it from the listed surface."
+	};
+}
+function summarize(entries) {
+	return {
+		total: entries.length,
+		coreIncluded: entries.filter((entry) => entry.delivery === "core" && entry.state === "included").length,
+		optionalInstalled: entries.filter((entry) => entry.delivery === "npm-addon" && (entry.state === "installed" || entry.state === "configured" || entry.state === "ready")).length,
+		optionalConfigured: entries.filter((entry) => entry.state === "configured").length,
+		externalRequired: entries.filter((entry) => entry.state === "external-required").length,
+		errors: entries.filter((entry) => entry.state === "error").length
+	};
+}
+function buildCapabilityReadinessReport(params) {
+	const config = params?.config ?? loadConfig();
+	const pluginReport = params?.pluginReport ?? buildPluginMarketplaceReport({ config });
+	const entries = loadCapabilityCatalog().map((entry) => {
+		const resolved = entry.delivery === "core" ? resolveCoreCapability(entry, pluginReport) : entry.delivery === "npm-addon" ? resolveAddonCapability(entry, config, pluginReport) : resolveExternalCapability(entry, config);
+		return {
+			...entry,
+			...resolved,
+			action: actionForState(resolved.state)
+		};
+	});
+	return {
+		entries,
+		summary: summarize(entries)
+	};
+}
+function formatCapabilityReadinessSummary(report) {
+	const { summary } = report;
+	return [
+		`Core included: ${summary.coreIncluded}`,
+		`Add-ons installed: ${summary.optionalInstalled}`,
+		`Configured: ${summary.optionalConfigured}`,
+		`External required: ${summary.externalRequired}`,
+		`Errors: ${summary.errors}`
+	].join(" · ");
+}
+
+//#endregion
+export { buildCapabilityReadinessReport, formatCapabilityReadinessSummary, loadCapabilityCatalog };

package/dist/cli/components-cli.js

@@ -0,0 +1,105 @@
+import { theme } from "../terminal/theme.js";
+import { defaultRuntime } from "../runtime.js";
+import { installPluginFromNpmSpec } from "../plugins/install.js";
+import { loadConfig, writeConfigFile } from "../config/io.js";
+import "../config/config.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { buildNpmResolutionInstallFields } from "../plugins/installs.js";
+import { finalizeInstalledPluginConfig } from "../plugins/lifecycle.js";
+import { buildCapabilityReadinessReport, formatCapabilityReadinessSummary, loadCapabilityCatalog } from "../capabilities/catalog.js";
+import { renderTable } from "../terminal/table.js";
+
+//#region src/cli/components-cli.ts
+function registerComponentsCli(program) {
+	const components = program.command("components").description("Show core, add-on, and external component readiness").option("--json", "Output JSON", false).addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/install/components", "docs.fased.ai/install/components")}\n`).action((options) => {
+		renderComponentReport(options);
+	});
+	components.command("list").description("Show core, add-on, and external component readiness").option("--json", "Output JSON", false).action((options) => {
+		renderComponentReport(options);
+	});
+	components.command("install").description("Install a cataloged optional component").argument("<id>", "Component id from `fased components`").action(async (id) => {
+		const entry = loadCapabilityCatalog().find((candidate) => candidate.id === id);
+		if (!entry) {
+			throw new Error(`Unknown component: ${id}. Run \`fased components\` to list choices.`);
+		}
+		if (entry.delivery !== "npm-addon" || !entry.packageName || !entry.pluginId) {
+			throw new Error(`${entry.label} is delivered as ${entry.delivery} and cannot be installed as an add-on. See ${entry.docsPath}.`);
+		}
+		const result = await installPluginFromNpmSpec({ spec: entry.packageName });
+		if (!result.ok) {
+			throw new Error(result.error);
+		}
+		const config = loadConfig();
+		const finalized = finalizeInstalledPluginConfig({
+			config,
+			pluginId: result.pluginId,
+			refreshManifestRegistry: true,
+			installRecord: {
+				source: "npm",
+				spec: entry.packageName,
+				installPath: result.targetDir,
+				version: result.version,
+				...buildNpmResolutionInstallFields(result.npmResolution)
+			}
+		});
+		await writeConfigFile(finalized.config);
+		for (const warning of finalized.slotWarnings) {
+			defaultRuntime.log(theme.warn(warning));
+		}
+		defaultRuntime.log(`Installed component: ${entry.label} (${entry.packageName})`);
+		if (entry.restartRequired !== false) {
+			defaultRuntime.log("Restart the gateway to apply the component.");
+		}
+	});
+}
+function renderComponentReport(options) {
+	const report = buildCapabilityReadinessReport();
+	if (options.json) {
+		defaultRuntime.log(JSON.stringify(report, null, 2));
+		return;
+	}
+	const width = Math.max(80, (process.stdout.columns ?? 120) - 1);
+	defaultRuntime.log(theme.heading("Fased components"));
+	defaultRuntime.log(theme.muted(formatCapabilityReadinessSummary(report)));
+	defaultRuntime.log(renderTable({
+		width,
+		columns: [
+			{
+				key: "Component",
+				header: "Component",
+				minWidth: 18,
+				flex: true
+			},
+			{
+				key: "Category",
+				header: "Category",
+				minWidth: 10
+			},
+			{
+				key: "Delivery",
+				header: "Delivery",
+				minWidth: 16
+			},
+			{
+				key: "State",
+				header: "State",
+				minWidth: 18
+			},
+			{
+				key: "Next",
+				header: "Next",
+				minWidth: 10
+			}
+		],
+		rows: report.entries.map((entry) => ({
+			Component: entry.label,
+			Category: entry.category,
+			Delivery: entry.delivery,
+			State: entry.state,
+			Next: entry.action
+		}))
+	}).trimEnd());
+}
+
+//#endregion
+export { registerComponentsCli };

package/dist/cli/hooks-cli.js

@@ -7,8 +7,8 @@ import { resolveArchiveKind } from "../infra/archive.js";
 import { loadConfig, writeConfigFile } from "../config/io.js";
 import { promptYesNo } from "./prompt.js";
 import { formatDocsLink } from "../terminal/links.js";
-import { renderTable } from "../terminal/table.js";
 import { buildPluginStatusReport } from "../plugins/status.js";
+import { renderTable } from "../terminal/table.js";
 import { loadWorkspaceHookEntries } from "../hooks/workspace.js";
 import { buildWorkspaceHookStatus } from "../hooks/hooks-status.js";
 import { installHooksFromNpmSpec, installHooksFromPath, resolveHookInstallDir } from "../hooks/install.js";

package/dist/cli/plugins-cli.js

@@ -8,14 +8,14 @@ import { loadConfig, writeConfigFile } from "../config/io.js";
 import "../config/config.js";
 import { promptYesNo } from "./prompt.js";
 import { formatDocsLink } from "../terminal/links.js";
-import { renderTable } from "../terminal/table.js";
+import { findBundledPluginByNpmSpec } from "../plugins/bundled-sources.js";
 import { setPluginEnabledInConfig } from "../plugins/toggle-config.js";
 import { enablePluginInConfig } from "../plugins/enable.js";
 import { buildPluginStatusReport } from "../plugins/status.js";
-import { findBundledPluginByNpmSpec } from "../plugins/bundled-sources.js";
 import { applySlotSelectionForPlugin, buildPluginLifecycleReport, buildPluginUninstallPreview, executePluginUninstallLifecycle, executePluginUpdateLifecycle, finalizeInstalledPluginConfig, resolvePluginLifecycleEntry } from "../plugins/lifecycle.js";
-import { buildPluginMarketplaceUpdateReview, formatPluginMarketplaceUpdateReviewWarnings } from "../plugins/marketplace-update-review.js";
 import { buildPluginMarketplaceReport } from "../plugins/marketplace.js";
+import { renderTable } from "../terminal/table.js";
+import { buildPluginMarketplaceUpdateReview, formatPluginMarketplaceUpdateReviewWarnings } from "../plugins/marketplace-update-review.js";
 import { getPluginRuntimeSessionReadGrant, setPluginRuntimeSessionReadGrant } from "../plugins/runtime-helper-grants.js";
 import { resolvePinnedNpmInstallRecordForCli } from "./npm-resolution.js";
 import { formatPluginSourceForTable, resolvePluginSourceRoots } from "../plugins/source-display.js";

package/dist/cli/program/register.subclis.js

@@ -318,6 +318,15 @@ const entries = [
 			mod.registerSkillsCli(program);
 		}
 	},
+	{
+		name: "components",
+		description: "Show core, add-on, and external component readiness",
+		hasSubcommands: false,
+		register: async (program) => {
+			const mod = await import("../components-cli.js");
+			mod.registerComponentsCli(program);
+		}
+	},
 	{
 		name: "update",
 		description: "Update FasedAgent and inspect update channel status",

package/dist/cli/update-cli/update-command.js

@@ -14,10 +14,10 @@ import { renderRestartDiagnostics, terminateStaleGatewayPids, waitForGatewayHeal
 import { runDaemonRestart } from "../daemon-cli/lifecycle.js";
 import "../../daemon-cli.js";
 import { installCompletion } from "../completion-cli.js";
+import { syncPluginsForUpdateChannel, updateNpmInstalledPlugins } from "../../plugins/update.js";
 import { DEFAULT_GIT_CHANNEL, DEFAULT_PACKAGE_CHANNEL, channelToNpmTag, normalizeUpdateChannel } from "../../infra/update-channels.js";
 import { cleanupGlobalRenameDirs, globalInstallArgs, resolveGlobalPackageRoot, resolveNodeModulesRootForPackageRoot } from "../../infra/update-global.js";
 import { checkUpdateStatus, compareSemverStrings, resolveNpmChannelTag } from "../../infra/update-check.js";
-import { syncPluginsForUpdateChannel, updateNpmInstalledPlugins } from "../../plugins/update.js";
 import { readPackageName, readPackageVersion } from "../../infra/package-json.js";
 import { runGatewayUpdate } from "../../infra/update-runner.js";
 import { checkShellCompletionStatus, ensureCompletionCacheExists } from "../../commands/doctor-completion.js";

package/dist/commands/doctor-capabilities.js

@@ -0,0 +1,26 @@
+import { buildCapabilityReadinessReport } from "../capabilities/catalog.js";
+import { note } from "../terminal/note.js";
+
+//#region src/commands/doctor-capabilities.ts
+function buildDoctorCapabilityLines(report) {
+	const optionalAvailable = report.entries.filter((entry) => entry.delivery === "npm-addon" && entry.state === "not-installed").length;
+	const lines = [
+		`Core included: ${report.summary.coreIncluded}`,
+		`Add-ons installed: ${report.summary.optionalInstalled}`,
+		`External runtimes configured: ${report.entries.filter((entry) => entry.delivery === "external-runtime" && entry.state === "configured").length}`
+	];
+	if (optionalAvailable > 0) {
+		lines.push(`Optional add-ons available: ${optionalAvailable} (not an error)`);
+	}
+	for (const entry of report.entries.filter((candidate) => candidate.state === "error")) {
+		lines.push(`ERROR ${entry.label}: ${entry.detail}`);
+	}
+	return lines;
+}
+function noteCapabilityReadiness(config) {
+	const report = buildCapabilityReadinessReport({ config });
+	note(buildDoctorCapabilityLines(report).join("\n"), "Components");
+}
+
+//#endregion
+export { noteCapabilityReadiness };

package/dist/commands/doctor.js

@@ -21,6 +21,7 @@ import "./doctor-state-migrations.js";
 import { loadAndMaybeMigrateDoctorConfig } from "./doctor-config-flow.js";
 import { ensureSystemdUserLingerInteractive } from "./systemd-linger.js";
 import { maybeRemoveDeprecatedCliAuthProfiles, maybeRepairAnthropicOAuthProfileId, noteAuthProfileHealth } from "./doctor-auth.js";
+import { noteCapabilityReadiness } from "./doctor-capabilities.js";
 import { doctorShellCompletion } from "./doctor-completion.js";
 import { maybeRepairGatewayDaemon } from "./doctor-gateway-daemon-flow.js";
 import { checkGatewayHealth } from "./doctor-gateway-health.js";
@@ -207,6 +208,7 @@ async function doctorCommand(runtime = defaultRuntime, options = {}) {
 	}
 	noteWorkspaceStatus(cfg);
 	await noteMemorySearchHealth(cfg, { quietOptional: options.deep !== true });
+	noteCapabilityReadiness(cfg);
 	await doctorShellCompletion(runtime, prompter, { nonInteractive: options.nonInteractive });
 	const { healthOk } = await checkGatewayHealth({
 		runtime,