@pellux/goodvibes-tui 1.13.0 → 1.14.0

package/src/cli/hooks-report.ts

@@ -0,0 +1,167 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createHookDispatcher, createHookWorkbench, getHookPointContract } from '@pellux/goodvibes-sdk/platform/hooks';
+import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
+import type { HookDefinition, HookEventPath, HookPointContract, HookType } from '@pellux/goodvibes-sdk/platform/hooks';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+// ---------------------------------------------------------------------------
+// Shared hooks validation core. The single source of truth for both
+// `goodvibes hooks validate` (src/cli/hooks-command.ts) and `goodvibes doctor
+// hooks` (src/cli/doctor.ts). There is NO second validator: field-level
+// acceptance comes from running the SDK's own HookDispatcher.loadFromFile (the
+// same loader the app uses at startup), and the "is this a real hook event
+// point" verdict comes from the SDK's getHookPointContract. This module only
+// reads and reports — it changes no config and fires no hooks.
+// ---------------------------------------------------------------------------
+
+/** Per-hook acceptance verdict, keyed to the on-disk position it was declared at. */
+export interface HookCheck {
+  readonly pattern: string;
+  readonly index: number;
+  readonly name: string;
+  /** The declared hook type, when present and readable (command/prompt/agent/http/ts). */
+  readonly type: string;
+  readonly ok: boolean;
+  readonly reason?: string;
+  readonly contract?: HookPointContract | null;
+}
+
+/** The full validation result for one hooks file. */
+export interface HooksValidation {
+  /** Absolute path the app resolves `tools.hooksFile` to — the "from where" of every hook. */
+  readonly path: string;
+  readonly present: boolean;
+  readonly valid: boolean;
+  /** A whole-file parse failure (invalid JSON / not an object). Present ⇒ no per-hook checks. */
+  readonly reason?: string;
+  readonly topLevelIssues: readonly string[];
+  readonly checks: readonly HookCheck[];
+  readonly chains: { readonly declared: number; readonly accepted: number };
+  readonly passCount: number;
+  readonly failCount: number;
+}
+
+export const LOADER_FIELD_REASON =
+  "the hooks loader skipped this entry — a hook needs a string \"match\" and a \"type\" of command, prompt, agent, http, or ts";
+
+/** Build a consumable multiset of the loader-accepted definitions, keyed by pattern. */
+function acceptedMultiset(accepted: Map<string, HookDefinition[]>): Map<string, Map<string, number>> {
+  const byPattern = new Map<string, Map<string, number>>();
+  for (const [pattern, defs] of accepted.entries()) {
+    const counts = new Map<string, number>();
+    for (const def of defs) {
+      const key = JSON.stringify(def);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    byPattern.set(pattern, counts);
+  }
+  return byPattern;
+}
+
+/** True when this exact definition was accepted by the loader (consumes one match). */
+function consumeAccepted(counts: Map<string, number> | undefined, def: unknown): boolean {
+  if (!counts) return false;
+  const key = JSON.stringify(def);
+  const remaining = counts.get(key);
+  if (remaining === undefined || remaining <= 0) return false;
+  counts.set(key, remaining - 1);
+  return true;
+}
+
+function readHookType(def: unknown): string {
+  if (def && typeof def === 'object' && typeof (def as { type?: unknown }).type === 'string') {
+    return (def as { type: string }).type;
+  }
+  return '(none)';
+}
+
+function readHookName(def: unknown): string {
+  if (def && typeof def === 'object' && typeof (def as { name?: unknown }).name === 'string') {
+    return (def as { name: string }).name;
+  }
+  return '(unnamed)';
+}
+
+/**
+ * Resolve the hooks file the same way the running app does (tools.hooksFile),
+ * load it through the real dispatcher, and report per-hook acceptance plus each
+ * hook's event-point contract. Empty/absent file ⇒ present=false, valid=true.
+ */
+export function buildHooksValidation(configManager: Pick<ConfigManager, 'get' | 'getWorkingDirectory'>): HooksValidation {
+  const dispatcher = createHookDispatcher();
+  const workbench = createHookWorkbench({ hookDispatcher: dispatcher, configManager });
+  const path = workbench.getHooksFilePath();
+
+  if (!existsSync(path)) {
+    return { path, present: false, valid: true, topLevelIssues: [], checks: [], chains: { declared: 0, accepted: 0 }, passCount: 0, failCount: 0 };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (error) {
+    return { path, present: true, valid: false, reason: `hooks.json is not valid JSON — ${summarizeError(error)}`, topLevelIssues: [], checks: [], chains: { declared: 0, accepted: 0 }, passCount: 0, failCount: 1 };
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { path, present: true, valid: false, reason: 'hooks.json must be a JSON object with "hooks" and/or "chains".', topLevelIssues: [], checks: [], chains: { declared: 0, accepted: 0 }, passCount: 0, failCount: 1 };
+  }
+
+  const record = parsed as { hooks?: unknown; chains?: unknown };
+  const topLevelIssues: string[] = [];
+
+  // Run the real loader once so field-level acceptance mirrors runtime behavior.
+  dispatcher.loadFromFile(path);
+  const accepted = acceptedMultiset(dispatcher.getHooks());
+
+  const checks: HookCheck[] = [];
+  if (record.hooks !== undefined) {
+    if (typeof record.hooks !== 'object' || record.hooks === null || Array.isArray(record.hooks)) {
+      topLevelIssues.push('the "hooks" field must be an object keyed by event-path pattern.');
+    } else {
+      for (const [pattern, defs] of Object.entries(record.hooks as Record<string, unknown>)) {
+        const contract = getHookPointContract(pattern as HookEventPath);
+        if (!Array.isArray(defs)) {
+          checks.push({ pattern, index: 0, name: '(all)', type: '(none)', ok: false, contract, reason: `the value for "${pattern}" must be an array of hook definitions.` });
+          continue;
+        }
+        const counts = accepted.get(pattern);
+        defs.forEach((def, index) => {
+          const loaderAccepted = consumeAccepted(counts, def);
+          let ok = true;
+          let reason: string | undefined;
+          if (!loaderAccepted) {
+            ok = false;
+            reason = LOADER_FIELD_REASON;
+          } else if (contract === null) {
+            ok = false;
+            reason = `"${pattern}" is not a recognized hook event point (no matching hook contract).`;
+          }
+          checks.push({ pattern, index, name: readHookName(def), type: readHookType(def), ok, contract, ...(reason ? { reason } : {}) });
+        });
+      }
+    }
+  }
+
+  const declaredChains = Array.isArray(record.chains) ? record.chains.length : 0;
+  if (record.chains !== undefined && !Array.isArray(record.chains)) {
+    topLevelIssues.push('the "chains" field must be an array.');
+  }
+  const acceptedChains = dispatcher.getChains().length;
+
+  const failCount = checks.filter((c) => !c.ok).length + topLevelIssues.length;
+  const passCount = checks.filter((c) => c.ok).length;
+
+  return {
+    path,
+    present: true,
+    valid: failCount === 0,
+    topLevelIssues,
+    checks,
+    chains: { declared: declaredChains, accepted: acceptedChains },
+    passCount,
+    failCount,
+  };
+}
+
+export type { HookType };

package/src/cli/index.ts

@@ -8,4 +8,7 @@ export * from './endpoints.ts';
 export * from './surface-command.ts';
 export * from './service-command.ts';
 export * from './bundle-command.ts';
+export * from './hooks-command.ts';
+export * from './doctor.ts';
+export * from './plugin-command.ts';
 export * from './management.ts';

package/src/cli/management.ts

@@ -21,6 +21,8 @@ import { applyRuntimeEndpointFlagOverrides } from './config-overrides.ts';
 import type { RuntimeEndpointId } from './endpoints.ts';
 import { handleServiceCommand } from './service-command.ts';
 import { handleBundleCommand } from './bundle-command.ts';
+import { handleHooksCommand } from './hooks-command.ts';
+import { handlePluginCommand } from './plugin-command.ts';
 import { buildListenerTestResult, formatListenerTestResult, handleSurfacesCommand } from './surface-command.ts';
 import { buildControlPlaneStatusResult, formatControlPlaneStatus, handleSecrets, handleSessions, handleTasks, renderPairing, renderRemote, renderSubscriptions, renderWeb } from './management-commands.ts';
 import {
@@ -487,11 +489,21 @@ export async function handleGoodVibesCliCommand(runtime: CliCommandRuntime): Pro
       case 'pair':
         console.log(await renderPairing(runtime));
         return { handled: true, exitCode: 0 };
-      case 'bundle': {
+      case 'support-bundle': {
         const result = await handleBundleCommand(runtime);
         console.log(result.output);
         return { handled: true, exitCode: result.exitCode };
       }
+      case 'hooks': {
+        const result = await handleHooksCommand(runtime);
+        console.log(result.output);
+        return { handled: true, exitCode: result.exitCode };
+      }
+      case 'plugin': {
+        const result = await handlePluginCommand(runtime);
+        console.log(result.output);
+        return { handled: true, exitCode: result.exitCode };
+      }
       case 'remote':
         console.log(await renderRemote(runtime, 'remote'));
         return { handled: true, exitCode: 0 };

package/src/cli/parser.ts

@@ -45,10 +45,18 @@ const COMMAND_ALIASES: Readonly<Record<string, GoodVibesCliCommand>> = {
   'control-plane': 'control-plane',
   controlplane: 'control-plane',
   cp: 'control-plane',
-  bundle: 'bundle',
-  bundles: 'bundle',
+  'support-bundle': 'support-bundle',
+  // `bundle`/`bundles` are retained as backward-compat aliases for the shipped
+  // command word; the primary, unambiguous name is `support-bundle` (distinct
+  // from the `plugin bundles` capability-bundle surface).
+  bundle: 'support-bundle',
+  bundles: 'support-bundle',
   remote: 'remote',
   bridge: 'bridge',
+  hooks: 'hooks',
+  hook: 'hooks',
+  plugin: 'plugin',
+  plugins: 'plugin',
   completion: 'completion',
   completions: 'completion',
   help: 'help',

package/src/cli/plugin-bundles-command.ts

@@ -0,0 +1,228 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  parseMarketplaceIndex,
+  fetchAndVerifyBundle,
+  validateCapabilityBundleManifest,
+  planBundleActivation,
+  BundlePinRefusal,
+  type PinnedMarketplaceIndexEntry,
+  type CapabilityBundleManifest,
+  type BundleActivationPlan,
+} from '@pellux/goodvibes-sdk/platform/runtime/ecosystem';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { CliCommandOutput, CliCommandRuntime } from './types.ts';
+
+// ---------------------------------------------------------------------------
+// `goodvibes plugin bundles browse|install|list` — the capability-bundle
+// marketplace surface. Extends the existing plugin-command.ts family with the
+// SDK's SHA-256-pinned bundle distribution (platform/runtime/ecosystem):
+// parseMarketplaceIndex, fetchAndVerifyBundle, planBundleActivation. There is
+// deliberately NO flag that bypasses a pin mismatch — `install` either
+// verifies or refuses; `--yes` only confirms an ALREADY-verified activation
+// plan, it never substitutes for the pin.
+// ---------------------------------------------------------------------------
+
+interface InstalledBundleRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly kind: CapabilityBundleManifest['kind'];
+  readonly source: { readonly kind: 'file' | 'url'; readonly location: string; readonly sha256: string };
+  readonly capabilities: BundleActivationPlan['capabilityManifest'];
+  readonly quarantine: BundleActivationPlan['quarantine'];
+  readonly installedAt: number;
+}
+
+function installedBundlesPath(runtime: CliCommandRuntime): string {
+  return join(runtime.homeDirectory, '.goodvibes', 'bundles', 'installed.json');
+}
+
+function readInstalledBundles(runtime: CliCommandRuntime): InstalledBundleRecord[] {
+  const path = installedBundlesPath(runtime);
+  if (!existsSync(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    return Array.isArray(parsed) ? (parsed as InstalledBundleRecord[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeInstalledBundles(runtime: CliCommandRuntime, records: readonly InstalledBundleRecord[]): void {
+  const path = installedBundlesPath(runtime);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(records, null, 2)}\n`, 'utf-8');
+}
+
+function formatJsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+/** file:// / bare-path vs http(s):// — the only two source kinds this CLI surface accepts (no git ref flag exists yet). */
+function inferSourceKind(ref: string): 'file' | 'url' {
+  return ref.startsWith('http://') || ref.startsWith('https://') ? 'url' : 'file';
+}
+
+async function readIndexBytes(ref: string): Promise<string> {
+  if (inferSourceKind(ref) === 'url') {
+    const res = await fetch(ref);
+    if (!res.ok) throw new Error(`URL '${ref}' returned HTTP ${res.status}`);
+    return res.text();
+  }
+  return readFileSync(ref, 'utf-8');
+}
+
+function summarizeCapabilities(summary: PinnedMarketplaceIndexEntry['capabilities']): string {
+  const parts = [`tools:${summary.toolCount}`, `hooks:${summary.hookCount}`, `configDomains:${summary.configDomainCount}`, `channels:${summary.channelCount}`];
+  if (summary.runtime.length > 0) parts.push(`runtime:${summary.runtime.join('+')}`);
+  if (summary.highRisk) parts.push('HIGH-RISK');
+  return parts.join(' ');
+}
+
+async function handleBrowse(runtime: CliCommandRuntime, ref: string | undefined): Promise<CliCommandOutput> {
+  if (!ref) return { output: 'Usage: goodvibes plugin bundles browse <index-url-or-file>', exitCode: 2 };
+  let raw: string;
+  try {
+    raw = await readIndexBytes(ref);
+  } catch (error) {
+    return { output: `Could not read marketplace index '${ref}': ${summarizeError(error)}`, exitCode: 1 };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    return { output: `Marketplace index at '${ref}' is not valid JSON: ${summarizeError(error)}`, exitCode: 1 };
+  }
+  const result = parseMarketplaceIndex(value);
+  if (!result.ok) {
+    return {
+      output: formatJsonOrText(runtime, result, [
+        `Marketplace index at '${ref}' was refused (a governed index requires a SHA-256 pin + capability summary on every entry):`,
+        ...result.errors.map((e) => `  - ${e}`),
+      ].join('\n')),
+      exitCode: 1,
+    };
+  }
+  const { bundles } = result.index;
+  if (bundles.length === 0) {
+    return { output: formatJsonOrText(runtime, result.index, `Marketplace index at '${ref}': no bundles listed.`), exitCode: 0 };
+  }
+  const lines = [`Marketplace index at '${ref}' (${bundles.length} bundle${bundles.length === 1 ? '' : 's'}):`];
+  for (const entry of bundles) {
+    lines.push(
+      `  ${entry.id} — ${entry.name} v${entry.version} (${entry.kind})`,
+      `    ${entry.summary}`,
+      `    capabilities: ${summarizeCapabilities(entry.capabilities)}`,
+      `    pin: sha256:${entry.source.sha256} (${entry.source.kind}: ${entry.source.location})`,
+    );
+  }
+  return { output: formatJsonOrText(runtime, result.index, lines.join('\n')), exitCode: 0 };
+}
+
+/** Render an activation plan (granted capabilities, withheld/quarantined ones) for confirmation. */
+function renderPlan(plan: BundleActivationPlan, committed: boolean): string {
+  const lines = [
+    `${committed ? 'Installed' : 'Activation plan (preview — re-run with --yes to install)'}: ${plan.manifest.id} v${plan.manifest.version} (${plan.manifest.kind})`,
+    `  trust tier: ${plan.trustTier}`,
+    `  declared runtime capabilities: ${plan.manifest.capabilities.runtime.join(', ') || 'none'}`,
+    `  declared tools: ${plan.manifest.capabilities.tools.join(', ') || 'none'}`,
+    `  declared hooks: ${plan.manifest.capabilities.hooks.join(', ') || 'none'}`,
+    `  declared configDomains: ${plan.manifest.capabilities.configDomains.join(', ') || 'none'}`,
+    `  declared channels: ${plan.manifest.capabilities.channels.join(', ') || 'none'}`,
+    `  granted capabilities: ${plan.capabilityManifest.granted.join(', ') || 'none'}`,
+  ];
+  if (plan.quarantine.required) {
+    lines.push(
+      `  QUARANTINED: yes — ${plan.quarantine.reason ?? 'over-reached its trust tier'}`,
+      `  withheld capabilities: ${plan.quarantine.revokedCapabilities.join(', ')}`,
+    );
+  } else {
+    lines.push('  quarantined: no — every declared capability fit the trust tier');
+  }
+  return lines.join('\n');
+}
+
+async function handleInstall(runtime: CliCommandRuntime, ref: string | undefined, sha256: string | undefined): Promise<CliCommandOutput> {
+  if (!ref || !sha256) {
+    return { output: 'Usage: goodvibes plugin bundles install <ref> --sha256 <pin>  (the pin is required — there is no unpinned install path)', exitCode: 2 };
+  }
+  const kind = inferSourceKind(ref);
+  const source = { kind, location: ref, sha256 } as const;
+  let bytes: Uint8Array;
+  try {
+    const fetched = await fetchAndVerifyBundle(source);
+    bytes = fetched.bytes;
+  } catch (error) {
+    if (error instanceof BundlePinRefusal) {
+      return {
+        output: formatJsonOrText(runtime, { ok: false, source, verification: error.verification }, `Refused: ${error.message}`),
+        exitCode: 1,
+      };
+    }
+    return { output: `Could not fetch bundle from '${ref}': ${summarizeError(error)}`, exitCode: 1 };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes));
+  } catch (error) {
+    return { output: `Bundle at '${ref}' is not valid JSON: ${summarizeError(error)}`, exitCode: 1 };
+  }
+  const validation = validateCapabilityBundleManifest(parsed);
+  if (!validation.ok) {
+    return {
+      output: formatJsonOrText(runtime, validation, [
+        `Bundle manifest at '${ref}' was refused:`,
+        ...validation.errors.map((e) => `  - ${e}`),
+      ].join('\n')),
+      exitCode: 1,
+    };
+  }
+  const plan = planBundleActivation(validation.manifest);
+  const committed = runtime.cli.flags.yes;
+  if (committed) {
+    const records = readInstalledBundles(runtime).filter((r) => r.id !== plan.manifest.id);
+    records.push({
+      id: plan.manifest.id,
+      name: plan.manifest.name,
+      version: plan.manifest.version,
+      kind: plan.manifest.kind,
+      source,
+      capabilities: plan.capabilityManifest,
+      quarantine: plan.quarantine,
+      installedAt: Date.now(),
+    });
+    writeInstalledBundles(runtime, records);
+  }
+  return { output: formatJsonOrText(runtime, { ok: true, committed, plan }, renderPlan(plan, committed)), exitCode: 0 };
+}
+
+function handleList(runtime: CliCommandRuntime): CliCommandOutput {
+  const records = readInstalledBundles(runtime);
+  if (records.length === 0) {
+    return { output: formatJsonOrText(runtime, records, 'No capability bundles installed.'), exitCode: 0 };
+  }
+  const lines = [`Installed capability bundles (${records.length}):`];
+  for (const record of records) {
+    lines.push(
+      `  ${record.id} — ${record.name} v${record.version} (${record.kind})`,
+      `    installedAt: ${new Date(record.installedAt).toISOString()}`,
+      `    source: ${record.source.kind}:${record.source.location} (sha256:${record.source.sha256})`,
+      `    quarantined: ${record.quarantine.required ? `yes — ${record.quarantine.reason ?? 'over-reached its trust tier'}` : 'no'}`,
+    );
+  }
+  return { output: formatJsonOrText(runtime, records, lines.join('\n')), exitCode: 0 };
+}
+
+export async function handlePluginBundlesCommand(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  const [sub, ...rest] = args;
+  if (sub === 'browse') return handleBrowse(runtime, rest[0]);
+  if (sub === 'install') {
+    const sha256Index = rest.indexOf('--sha256');
+    const sha256 = sha256Index >= 0 ? rest[sha256Index + 1] : undefined;
+    const ref = rest.find((token, i) => (sha256Index < 0 || (i !== sha256Index && i !== sha256Index + 1)) && !token.startsWith('-'));
+    return handleInstall(runtime, ref, sha256);
+  }
+  if (sub === 'list') return handleList(runtime);
+  return { output: 'Usage: goodvibes plugin bundles browse <index-url-or-file>|install <ref> --sha256 <pin>|list', exitCode: 2 };
+}

package/src/cli/plugin-command.ts

@@ -0,0 +1,179 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { discoverPlugins } from '../plugins/loader.ts';
+import { validateManifestV2 } from '@/runtime/index.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import type { CliCommandOutput, CliCommandRuntime } from './types.ts';
+import { handlePluginBundlesCommand } from './plugin-bundles-command.ts';
+
+// ---------------------------------------------------------------------------
+// `goodvibes plugin init` / `plugin validate` — scaffold and check plugins
+// against the SAME classic loader the running TUI uses (PluginManager wraps
+// discoverPlugins from @pellux/goodvibes-sdk/platform/plugins). The pass/fail
+// verdict is the real loader's acceptance: we run discoverPlugins against the
+// target directory (isolated from the operator's own plugin folders) and check
+// whether it accepts the directory. Reasons for a rejected manifest are sourced
+// from the SDK's validateManifestV2 (string|null) plus observable file facts —
+// no second manifest schema is defined here.
+// ---------------------------------------------------------------------------
+
+interface PluginValidation {
+  readonly ok: boolean;
+  readonly path: string;
+  readonly reasons: readonly string[];
+  readonly manifestName?: string;
+  readonly manifestVersion?: string;
+}
+
+/** A base directory whose standard plugin folders do not exist, so discoverPlugins
+ * only considers the target's parent (passed via additionalDirectories). */
+function isolatedBase(): string {
+  return join(tmpdir(), '__goodvibes_plugin_validate_isolate__');
+}
+
+function validatePluginDirectory(dirPath: string): PluginValidation {
+  const resolved = resolve(dirPath);
+  if (!existsSync(resolved)) {
+    return { ok: false, path: resolved, reasons: ['directory not found.'] };
+  }
+  const manifestPath = join(resolved, 'manifest.json');
+
+  // Authoritative verdict: the real classic loader's discovery scan.
+  const base = isolatedBase();
+  const discovered = discoverPlugins({
+    cwd: base,
+    homeDir: base,
+    additionalDirectories: [dirname(resolved)],
+  });
+  const match = discovered.find((plugin) => resolve(plugin.pluginDir) === resolved);
+  if (match) {
+    return {
+      ok: true,
+      path: resolved,
+      reasons: [],
+      manifestName: match.manifest.name,
+      manifestVersion: match.manifest.version,
+    };
+  }
+
+  // Rejected — explain why, delegating field checks to the SDK validator.
+  const reasons: string[] = [];
+  if (!existsSync(manifestPath)) {
+    reasons.push('manifest.json not found in the plugin directory.');
+    return { ok: false, path: resolved, reasons };
+  }
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch (error) {
+    reasons.push(`manifest.json is not valid JSON — ${summarizeError(error)}`);
+    return { ok: false, path: resolved, reasons };
+  }
+  const fieldReason = validateManifestV2(manifest);
+  if (fieldReason) {
+    reasons.push(fieldReason);
+  } else {
+    reasons.push('the plugin loader did not accept this directory — if "main" is set it must be a relative path.');
+  }
+  return { ok: false, path: resolved, reasons };
+}
+
+function renderValidation(result: PluginValidation, json: boolean): CliCommandOutput {
+  if (json) {
+    return { output: JSON.stringify(result, null, 2), exitCode: result.ok ? 0 : 1 };
+  }
+  const lines = ['GoodVibes plugin validation', `  path: ${result.path}`];
+  if (result.ok) {
+    lines.push(`  PASS  ${result.manifestName} v${result.manifestVersion} — the plugin loader accepts this directory.`);
+  } else {
+    lines.push('  FAIL  the plugin loader rejects this directory:');
+    for (const reason of result.reasons) lines.push(`    - ${reason}`);
+  }
+  return { output: lines.join('\n'), exitCode: result.ok ? 0 : 1 };
+}
+
+const ENTRY_FILE_CONTENTS = `// Minimal GoodVibes plugin entry point.
+// The loader calls init(api) once after the plugin is loaded.
+export function init(api) {
+  // Register commands, tools, or hooks through the sandboxed api here.
+  void api;
+}
+`;
+
+function handlePluginInit(runtime: CliCommandRuntime): CliCommandOutput {
+  const json = runtime.cli.flags.outputFormat === 'json';
+  const name = runtime.cli.commandArgs[1];
+  if (!name) {
+    return { output: 'Usage: goodvibes plugin init <name> [directory]', exitCode: 2 };
+  }
+  const dirArg = runtime.cli.commandArgs[2];
+  const targetDir = dirArg
+    ? resolve(dirArg)
+    : join(runtime.workingDirectory, '.goodvibes', 'plugins', name);
+  const manifestPath = join(targetDir, 'manifest.json');
+  if (existsSync(manifestPath)) {
+    return {
+      output: json
+        ? JSON.stringify({ ok: false, path: targetDir, reason: 'a plugin already exists here' }, null, 2)
+        : `A plugin already exists at ${targetDir} (manifest.json present). Choose another name or directory.`,
+      exitCode: 1,
+    };
+  }
+
+  const manifest = {
+    name,
+    version: '0.1.0',
+    description: `${name} plugin`,
+    main: 'index.js',
+  };
+  try {
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    writeFileSync(join(targetDir, 'index.js'), ENTRY_FILE_CONTENTS, 'utf-8');
+  } catch (error) {
+    return {
+      output: json
+        ? JSON.stringify({ ok: false, path: targetDir, reason: summarizeError(error) }, null, 2)
+        : `Failed to scaffold plugin at ${targetDir} — ${summarizeError(error)}`,
+      exitCode: 1,
+    };
+  }
+
+  // Prove the freshly scaffolded plugin passes our own validation path.
+  const validation = validatePluginDirectory(targetDir);
+  if (json) {
+    return {
+      output: JSON.stringify({ ok: validation.ok, path: targetDir, created: ['manifest.json', 'index.js'], validation }, null, 2),
+      exitCode: validation.ok ? 0 : 1,
+    };
+  }
+  const lines = [
+    `Scaffolded plugin "${name}" at ${targetDir}`,
+    '  created: manifest.json, index.js',
+    validation.ok
+      ? '  validation: PASS — the plugin loader accepts this directory.'
+      : `  validation: FAIL — ${validation.reasons.join('; ')}`,
+    `  next: run "goodvibes plugin validate ${targetDir}" or restart the TUI to load it.`,
+  ];
+  return { output: lines.join('\n'), exitCode: validation.ok ? 0 : 1 };
+}
+
+export async function handlePluginCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const json = runtime.cli.flags.outputFormat === 'json';
+  const [sub] = runtime.cli.commandArgs;
+  if (sub === 'init') {
+    return handlePluginInit(runtime);
+  }
+  if (sub === 'validate') {
+    const target = runtime.cli.commandArgs[1];
+    if (!target) {
+      return { output: 'Usage: goodvibes plugin validate <path>', exitCode: 2 };
+    }
+    return renderValidation(validatePluginDirectory(target), json);
+  }
+  if (sub === 'bundles') {
+    return handlePluginBundlesCommand(runtime, runtime.cli.commandArgs.slice(1));
+  }
+  return { output: 'Usage: goodvibes plugin [init <name> [directory]|validate <path>|bundles browse|install|list]', exitCode: 2 };
+}

package/src/cli/service-posture.ts

@@ -62,6 +62,16 @@ const ENDPOINTS: readonly { readonly id: RuntimeEndpointId; readonly label: stri
 
 const SOURCE_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 
+/**
+ * The packaged root of this install (the directory that owns `vendor/`,
+ * `dist/`, and `bin/`), resolved the same way the daemon executable search
+ * resolves its package paths. Exposed so the install self-check can look for
+ * the vendored release binaries without re-deriving this path.
+ */
+export function getGoodVibesPackageRoot(): string {
+  return SOURCE_PACKAGE_ROOT;
+}
+
 export interface DaemonExecutableResolutionOptions {
   readonly env?: NodeJS.ProcessEnv;
   readonly argv?: readonly string[];