@rbbtsn0w/adg 0.1.0-alpha.1

package/src/commands/select-components.ts

@@ -0,0 +1,66 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import type { SelectComponentsRequest } from "./install.ts";
+import type { ComponentType, PluginSelection } from "../types.ts";
+import { multiselectSkills } from "./multiselect-skills.ts";
+
+function cancelled<T>(value: T | symbol): value is symbol {
+  if (p.isCancel(value)) {
+    p.cancel("Installation cancelled");
+    process.exit(0);
+  }
+  return false;
+}
+
+/**
+ * The "install everything?" gate. Returns true to install each selected plugin
+ * in full, false to drop into per-plugin component selection. Used by `add` in
+ * an interactive terminal when no --only/--skill flags were given.
+ */
+export async function confirmFullInstall(plugins: string[]): Promise<boolean> {
+  const list = plugins.length === 1 ? plugins[0] : `${plugins.length} plugins`;
+  const choice = await p.select({
+    message: `Install everything in ${pc.cyan(list)}?`,
+    options: [
+      { value: true, label: "Yes, install all", hint: "every skill, command, agent, mcp…" },
+      { value: false, label: "No, let me choose", hint: "pick components per plugin" },
+    ],
+    initialValue: true,
+  });
+  if (cancelled(choice)) return true;
+  return choice as boolean;
+}
+
+/**
+ * Per-plugin component picker (①). Choose which categories to expose; if skills
+ * is kept and the plugin has several, drill in to pick individual skills. Files
+ * are still installed in full — this only narrows what the runtime sees.
+ */
+export async function selectComponentsInteractive(req: SelectComponentsRequest): Promise<PluginSelection> {
+  const components = await p.multiselect({
+    message: `${pc.bold(req.name)} — what to install? ${pc.dim("(space to toggle)")}`,
+    options: req.present.map((c) => ({ value: c, label: `${c} (${req.contents[c].length})` })),
+    initialValues: [...req.present],
+    required: true,
+  });
+  if (cancelled(components)) return { components: [...req.present] };
+  const chosen = components as ComponentType[];
+
+  const selection: PluginSelection = { components: chosen };
+
+  // Drill into individual skills only when skills is kept and there's a choice.
+  if (chosen.includes("skills") && req.contents.skills.length > 1) {
+    const message = `${pc.bold(req.name)} — which skills? ${pc.dim("(space to toggle)")}`;
+    const options = req.contents.skills.map((s) => ({ value: s, label: s }));
+    const initialValues = [...req.contents.skills];
+    const skills = req.skillDescription
+      ? await multiselectSkills({ message, options, initialValues, loadDescription: req.skillDescription })
+      : await p.multiselect({ message, options, initialValues, required: true });
+    if (!cancelled(skills)) {
+      const picked = skills as string[];
+      if (picked.length !== req.contents.skills.length) selection.skills = picked;
+    }
+  }
+
+  return selection;
+}

package/src/commands/select-plugins.ts

@@ -0,0 +1,28 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import type { PluginChoice } from "./install.ts";
+
+/**
+ * Interactive multiselect for choosing which plugins to install from a source
+ * that holds several. Mirrors the skills install flow. Native (reverse-adapted)
+ * plugins are flagged so the user knows they came from a Claude/Codex manifest.
+ */
+export async function selectPluginsInteractive(choices: PluginChoice[]): Promise<string[]> {
+  const selected = await p.multiselect({
+    message: `Select plugins to install ${pc.dim("(space to toggle)")}`,
+    options: choices.map((c) => ({
+      value: c.name,
+      label: c.native ? `${c.name} ${pc.dim("(native)")}` : c.name,
+      ...(c.description
+        ? { hint: c.description.length > 60 ? c.description.slice(0, 57) + "..." : c.description }
+        : {}),
+    })),
+    required: true,
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel("Installation cancelled");
+    process.exit(0);
+  }
+  return selected as string[];
+}

package/src/commands/select-scope.ts

@@ -0,0 +1,21 @@
+import * as p from "@clack/prompts";
+
+/**
+ * Ask whether to install into the project (.agents/plugins) or globally
+ * (~/.agents/plugins). Returns true for global. Used by `add` when no scope
+ * flag (--global/--project/--dir) was given in an interactive terminal.
+ */
+export async function selectScopeInteractive(): Promise<boolean> {
+  const scope = await p.select({
+    message: "Installation scope",
+    options: [
+      { value: false, label: "Project", hint: ".agents/plugins (committed with your project)" },
+      { value: true, label: "Global", hint: "~/.agents/plugins (available across all projects)" },
+    ],
+  });
+  if (p.isCancel(scope)) {
+    p.cancel("Installation cancelled");
+    process.exit(0);
+  }
+  return scope as boolean;
+}

package/src/commands/update.ts

@@ -0,0 +1,85 @@
+import { existsSync } from "node:fs";
+import { folderHash } from "../hash.ts";
+import { packageFilter } from "../package.ts";
+import { lockPath, installedPluginDir } from "../paths.ts";
+import { readLock, writeLock } from "../lock.ts";
+import { readManifest } from "../manifest.ts";
+import { adaptPlugin } from "./adapt.ts";
+import { resolveAgents, type Agent, type AgentScope, type AgentSyncResult } from "../agents/index.ts";
+
+export interface UpdateResult {
+  name: string;
+  changed: boolean;
+  version: string;
+  folderHash: string;
+}
+
+export interface UpdateOptions {
+  /**
+   * After refreshing the store, re-sync the agents so they pick up the updated
+   * content rather than serving a stale cached copy. Off by default so the
+   * library function stays side-effect-free.
+   */
+  resync?: boolean;
+  /** Install scope for re-sync; "user" (global) or "project". */
+  scope?: AgentScope;
+  /** Injection seam for tests; defaults to every registered agent. */
+  agents?: Agent[];
+}
+
+export interface UpdateLockResult {
+  results: UpdateResult[];
+  missing: string[];
+  /** Per-agent re-sync outcome (when `resync` was set). */
+  agents?: AgentSyncResult[];
+}
+
+/**
+ * Re-scan installed plugins in a plugins directory, refreshing each lock
+ * entry's version and folderHash from disk. Entries whose content or version
+ * changed are reported as `changed`. A missing plugin directory is reported as
+ * an issue rather than silently dropped.
+ *
+ * With `resync`, changed plugins are re-adapted (honoring their selection) and
+ * re-installed into the agents so Claude/Codex reflect the new content.
+ */
+export function updateLock(
+  pluginsDir: string,
+  now: string = new Date().toISOString(),
+  opts: UpdateOptions = {},
+): UpdateLockResult {
+  const lockFile = lockPath(pluginsDir);
+  const lock = readLock(lockFile);
+  const results: UpdateResult[] = [];
+  const missing: string[] = [];
+  const changedNames: string[] = [];
+
+  for (const [name, entry] of Object.entries(lock.plugins)) {
+    const dir = installedPluginDir(pluginsDir, name, entry.origin);
+    if (!existsSync(dir)) {
+      missing.push(name);
+      continue;
+    }
+    const manifest = readManifest(dir);
+    const hash = folderHash(dir, [".claude-plugin", ".codex-plugin"], packageFilter(manifest, { includeProjections: false }));
+    const changed = hash !== entry.folderHash || manifest.version !== entry.version;
+    if (changed) {
+      entry.folderHash = hash;
+      entry.version = manifest.version;
+      entry.updatedAt = now;
+      // Regenerate runtime manifests from the updated source, honoring selection.
+      adaptPlugin(dir, ["claude", "codex"], entry.selection);
+      changedNames.push(name);
+    }
+    results.push({ name, changed, version: manifest.version, folderHash: hash });
+  }
+
+  writeLock(lockFile, lock);
+
+  const out: UpdateLockResult = { results, missing };
+  if (opts.resync && changedNames.length > 0) {
+    const ctx = { pluginsDir, plugins: changedNames, scope: opts.scope ?? "project" };
+    out.agents = (opts.agents ?? resolveAgents()).map((a) => a.refresh(ctx));
+  }
+  return out;
+}

package/src/commands/validate.ts

@@ -0,0 +1,57 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ADG_MANIFEST_PATH, collectIssues } from "../manifest.ts";
+import { readFileSync } from "node:fs";
+
+export interface ValidateResult {
+  ok: boolean;
+  issues: string[];
+}
+
+/**
+ * Validate a plugin's manifest against the ADG schema and check that the
+ * directories/files it references actually exist.
+ */
+export function validatePlugin(pluginDir: string): ValidateResult {
+  const manifestFile = join(pluginDir, ADG_MANIFEST_PATH);
+  if (!existsSync(manifestFile)) {
+    return { ok: false, issues: [`${ADG_MANIFEST_PATH} not found in ${pluginDir}`] };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestFile, "utf8"));
+  } catch (err) {
+    return { ok: false, issues: [`${manifestFile} is not valid JSON: ${(err as Error).message}`] };
+  }
+
+  const issues = collectIssues(raw);
+  if (issues.length > 0) return { ok: false, issues };
+
+  // Reference checks (only when structural validation passed).
+  const m = raw as Record<string, unknown>;
+  const pathFields: Array<[string, unknown]> = [
+    ["agents", m.agents],
+    ["commands", m.commands],
+    ["apps", m.apps],
+    ["hooks", m.hooks],
+    ["mcp", m.mcp],
+  ];
+  for (const [field, value] of pathFields) {
+    if (typeof value === "string" && !existsSync(join(pluginDir, value))) {
+      issues.push(`${field} points to "${value}" which does not exist`);
+    }
+  }
+
+  if (typeof m.skills === "string") {
+    if (!existsSync(join(pluginDir, m.skills))) {
+      issues.push(`skills root "${m.skills}" does not exist`);
+    }
+  } else if (Array.isArray(m.skills)) {
+    for (const s of m.skills as string[]) {
+      if (!existsSync(join(pluginDir, s))) issues.push(`skill path "${s}" does not exist`);
+    }
+  }
+
+  return { ok: issues.length === 0, issues };
+}

package/src/components.ts

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { resolveSkills } from "./skills.ts";
+import { COMPONENT_TYPES, type AdgManifest, type ComponentType, type PluginSelection } from "./types.ts";
+
+export { COMPONENT_TYPES };
+
+/** Member names per component type a plugin declares (empty when absent). */
+export type PluginContents = Record<ComponentType, string[]>;
+
+/** Recursively collect regular (non-dotfile) file basenames, without extension. */
+function collectFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".")) continue;
+    if (e.isDirectory()) out.push(...collectFiles(join(dir, e.name)));
+    else out.push(e.name.replace(/\.[^.]+$/, ""));
+  }
+  return out.sort();
+}
+
+/**
+ * A single file's member name: its basename without extension. `base` is
+ * injectable so the OS-separator handling can be exercised deterministically in
+ * tests (path.win32.basename vs path.posix.basename) regardless of host platform.
+ */
+export function fileMemberName(absPath: string, base: typeof basename = basename): string {
+  return base(absPath).replace(/\.[^.]+$/, "");
+}
+
+/** Members of a declared path: a directory yields its files, a file yields its own name. */
+function membersOf(dir: string, rel: string | undefined): string[] {
+  if (!rel) return [];
+  const abs = join(dir, rel);
+  if (!existsSync(abs)) return [];
+  const files = collectFiles(abs);
+  if (files.length > 0) return files;
+  return [fileMemberName(abs)]; // a single file
+}
+
+/** Server names declared in an MCP config file (mcpServers/servers map). */
+function mcpServers(file: string): string[] {
+  if (!existsSync(file)) return [];
+  try {
+    const json = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+    const servers = (json.mcpServers ?? json.servers) as Record<string, unknown> | undefined;
+    return servers && typeof servers === "object" ? Object.keys(servers).sort() : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Enumerate what a plugin contains, by reading its manifest's component paths. */
+export function pluginContents(dir: string, manifest: AdgManifest): PluginContents {
+  return {
+    skills: resolveSkills(dir, manifest),
+    agents: membersOf(dir, manifest.agents),
+    commands: membersOf(dir, manifest.commands),
+    apps: membersOf(dir, manifest.apps),
+    hooks: membersOf(dir, manifest.hooks),
+    mcp: manifest.mcp ? mcpServers(join(dir, manifest.mcp)) : [],
+  };
+}
+
+/** Component types this plugin actually has (non-empty). */
+export function presentComponents(contents: PluginContents): ComponentType[] {
+  return COMPONENT_TYPES.filter((c) => contents[c].length > 0);
+}
+
+/** Whether a category is exposed under a selection (no selection = everything). */
+export function isExposed(selection: PluginSelection | undefined, category: ComponentType): boolean {
+  return !selection || selection.components.includes(category);
+}
+
+/** Apply a selection to a contents map, returning only the exposed members. */
+export function exposedContents(contents: PluginContents, selection: PluginSelection | undefined): PluginContents {
+  if (!selection) return contents;
+  const out = {} as PluginContents;
+  for (const c of COMPONENT_TYPES) {
+    if (!isExposed(selection, c)) {
+      out[c] = [];
+    } else if (c === "skills" && selection.skills) {
+      out[c] = contents.skills.filter((s) => selection.skills!.includes(s));
+    } else {
+      out[c] = contents[c];
+    }
+  }
+  return out;
+}

package/src/deps.ts

@@ -0,0 +1,64 @@
+import { satisfies } from "./semver.ts";
+import type { AdgManifest } from "./types.ts";
+
+export interface PluginCandidate {
+  dir: string;
+  manifest: AdgManifest;
+}
+
+export class DependencyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DependencyError";
+  }
+}
+
+/**
+ * Compute a topological install order for `rootName` and its transitive
+ * dependencies, using `candidates` (name -> plugin) as the resolution universe.
+ *
+ * Dependencies are emitted before the plugins that depend on them, with
+ * `rootName` last. Missing dependencies, version-constraint violations, and
+ * dependency cycles are reported as DependencyError.
+ */
+export function resolveInstallOrder(
+  rootName: string,
+  candidates: Map<string, PluginCandidate>,
+): string[] {
+  if (!candidates.has(rootName)) {
+    throw new DependencyError(`plugin "${rootName}" not found among candidates`);
+  }
+
+  const order: string[] = [];
+  const visited = new Set<string>(); // fully processed
+  const onStack = new Set<string>(); // current DFS path (cycle detection)
+
+  const visit = (name: string, requiredBy: string | null, constraint: string | null): void => {
+    const candidate = candidates.get(name);
+    if (!candidate) {
+      throw new DependencyError(
+        `missing dependency "${name}"${requiredBy ? ` required by "${requiredBy}"` : ""}`,
+      );
+    }
+    if (constraint && !satisfies(candidate.manifest.version, constraint)) {
+      throw new DependencyError(
+        `version conflict: "${requiredBy}" requires "${name}@${constraint}" but found ${candidate.manifest.version}`,
+      );
+    }
+    if (visited.has(name)) return;
+    if (onStack.has(name)) {
+      throw new DependencyError(`dependency cycle detected at "${name}"`);
+    }
+
+    onStack.add(name);
+    for (const dep of candidate.manifest.dependencies ?? []) {
+      visit(dep.name, name, dep.version);
+    }
+    onStack.delete(name);
+    visited.add(name);
+    order.push(name);
+  };
+
+  visit(rootName, null, null);
+  return order;
+}

package/src/fsutil.ts

@@ -0,0 +1,38 @@
+import { cpSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative } from "node:path";
+
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+export function writeJson(file: string, value: unknown): void {
+  ensureDir(dirname(file));
+  writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+
+export function writeText(file: string, value: string): void {
+  ensureDir(dirname(file));
+  writeFileSync(file, value);
+}
+
+/**
+ * Copy a plugin directory, skipping VCS and dependency noise. When `include` is
+ * given (a root-relative path predicate, e.g. from `packageFilter`), only the
+ * declared payload is copied — dev cruft like `src/`/`test/` is left behind.
+ */
+export function copyPluginDir(
+  src: string,
+  dest: string,
+  include?: (relPath: string) => boolean,
+): void {
+  ensureDir(dirname(dest));
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (from) => {
+      const base = from.split(/[/\\]/).pop() ?? "";
+      if (base === ".git" || base === "node_modules" || base === ".DS_Store") return false;
+      if (!include) return true;
+      return include(relative(src, from));
+    },
+  });
+}

package/src/hash.ts

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+/** Directory names that never contribute to a plugin's content hash. */
+const HASH_IGNORE = new Set([".git", "node_modules", ".DS_Store"]);
+
+/**
+ * Compute a deterministic content hash for a plugin directory.
+ *
+ * The hash incorporates each file's POSIX-normalized relative path and its
+ * bytes, sorted by path so the result is stable across filesystems and walk
+ * order. `extraIgnore` drops directory names by segment (e.g. generated adapter
+ * manifests). `include`, when given, restricts the hash to the packaged payload
+ * (root-relative path predicate, e.g. from `packageFilter`) so an in-place
+ * plugin and a copied install hash identically.
+ */
+export function folderHash(
+  dir: string,
+  extraIgnore: Iterable<string> = [],
+  include?: (relPath: string) => boolean,
+): string {
+  const ignore = new Set([...HASH_IGNORE, ...extraIgnore]);
+  const files: string[] = [];
+  collect(dir, dir, ignore, include, files);
+  files.sort();
+
+  const hash = createHash("sha256");
+  for (const rel of files) {
+    hash.update(rel, "utf8");
+    hash.update("\0");
+    hash.update(readFileSync(join(dir, rel)));
+    hash.update("\0");
+  }
+  // Self-describing digest (SRI-style) so the algorithm can evolve later.
+  return `sha256-${hash.digest("hex")}`;
+}
+
+function collect(
+  root: string,
+  current: string,
+  ignore: Set<string>,
+  include: ((relPath: string) => boolean) | undefined,
+  out: string[],
+): void {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    if (ignore.has(entry.name)) continue;
+    const abs = join(current, entry.name);
+    const rel = relative(root, abs);
+    // Match ignore entries against any path segment (e.g. ".claude-plugin").
+    if (rel.split(sep).some((seg) => ignore.has(seg))) continue;
+    const relPosix = rel.split(sep).join("/");
+    // Prune anything outside the packaged payload (directories too, by segment).
+    if (include && !include(relPosix)) continue;
+    if (entry.isDirectory()) {
+      collect(root, abs, ignore, include, out);
+    } else if (entry.isFile()) {
+      out.push(relPosix);
+    }
+  }
+}

package/src/lock.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { LOCK_VERSION, type LockEntry, type PluginLock } from "./types.ts";
+
+export function emptyLock(): PluginLock {
+  return { version: LOCK_VERSION, plugins: {} };
+}
+
+export function readLock(file: string): PluginLock {
+  if (!existsSync(file)) return emptyLock();
+  const raw = JSON.parse(readFileSync(file, "utf8")) as PluginLock;
+  if (typeof raw.version !== "number" || typeof raw.plugins !== "object" || raw.plugins === null) {
+    throw new Error(`${file} is not a valid .plugin-lock.json`);
+  }
+  // Pre-release policy: a lock from an older format version is fully
+  // regenerable from the plugin directories, so rebuild rather than merge
+  // incompatible entry shapes.
+  if (raw.version !== LOCK_VERSION) return emptyLock();
+  return raw;
+}
+
+export function writeLock(file: string, lock: PluginLock): void {
+  writeFileSync(file, JSON.stringify(lock, null, 2) + "\n");
+}
+
+/**
+ * Remove a plugin entry from the lock. Drops it from `lastSelected` too.
+ * Returns true if an entry was actually removed.
+ */
+export function removeEntry(lock: PluginLock, name: string): boolean {
+  if (!(name in lock.plugins)) return false;
+  delete lock.plugins[name];
+  if (lock.lastSelected) {
+    lock.lastSelected = lock.lastSelected.filter((n) => n !== name);
+    if (lock.lastSelected.length === 0) delete lock.lastSelected;
+  }
+  return true;
+}
+
+/**
+ * Insert or update a plugin entry. Preserves the original installedAt on update
+ * and always refreshes updatedAt. `lastSelected` is set to the touched plugin.
+ */
+export function upsertEntry(
+  lock: PluginLock,
+  name: string,
+  entry: Omit<LockEntry, "installedAt" | "updatedAt">,
+  now: string = new Date().toISOString(),
+): PluginLock {
+  const prev = lock.plugins[name];
+  lock.plugins[name] = {
+    ...entry,
+    installedAt: prev?.installedAt ?? now,
+    updatedAt: now,
+  };
+  lock.lastSelected = [name];
+  return lock;
+}

package/src/manifest.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ADG_SCHEMA_VERSION, type AdgManifest } from "./types.ts";
+
+/** Canonical, vendor-neutral source manifest location (a plugin). */
+export const ADG_MANIFEST_PATH = join(".agents", ".plugin.json");
+/** Canonical, vendor-neutral source catalog location (a marketplace). */
+export const ADG_MARKETPLACE_PATH = join(".agents", ".marketplace.json");
+/** Legacy location, still read (deprecated) so pre-`.agents/` plugins resolve. */
+export const LEGACY_MANIFEST_PATH = join(".adg-plugin", "plugin.json");
+
+/**
+ * Resolve a plugin's manifest file, preferring the canonical `.agents/.plugin.json`
+ * and falling back to the legacy `.adg-plugin/plugin.json`. Returns undefined
+ * when neither exists.
+ */
+export function findManifestFile(pluginDir: string): string | undefined {
+  const primary = join(pluginDir, ADG_MANIFEST_PATH);
+  if (existsSync(primary)) return primary;
+  const legacy = join(pluginDir, LEGACY_MANIFEST_PATH);
+  if (existsSync(legacy)) return legacy;
+  return undefined;
+}
+
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+
+export class ManifestError extends Error {
+  readonly issues: string[];
+  constructor(issues: string[]) {
+    super(`Invalid ADG manifest:\n  - ${issues.join("\n  - ")}`);
+    this.name = "ManifestError";
+    this.issues = issues;
+  }
+}
+
+/** Read and validate a plugin's `.agents/.plugin.json` (or legacy fallback). */
+export function readManifest(pluginDir: string): AdgManifest {
+  const file = findManifestFile(pluginDir);
+  if (!file) {
+    throw new ManifestError([`${ADG_MANIFEST_PATH} not found in ${pluginDir}`]);
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new ManifestError([`${file} is not valid JSON: ${(err as Error).message}`]);
+  }
+  return validateManifest(raw);
+}
+
+/** Validate an already-parsed manifest object, throwing ManifestError on failure. */
+export function validateManifest(raw: unknown): AdgManifest {
+  const issues = collectIssues(raw);
+  if (issues.length > 0) throw new ManifestError(issues);
+  return raw as AdgManifest;
+}
+
+/** Collect validation issues without throwing (used by the `validate` command). */
+export function collectIssues(raw: unknown): string[] {
+  const issues: string[] = [];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return ["manifest must be a JSON object"];
+  }
+  const m = raw as Record<string, unknown>;
+
+  if (m.schemaVersion !== ADG_SCHEMA_VERSION) {
+    issues.push(`schemaVersion must be "${ADG_SCHEMA_VERSION}"`);
+  }
+  if (typeof m.name !== "string" || !NAME_RE.test(m.name)) {
+    issues.push("name is required and must be kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$)");
+  }
+  if (typeof m.version !== "string" || !SEMVER_RE.test(m.version)) {
+    issues.push("version is required and must be semantic (e.g. 0.1.0)");
+  }
+  if (typeof m.description !== "string" || m.description.length === 0) {
+    issues.push("description is required and must be a non-empty string");
+  }
+
+  if (m.skills !== undefined && typeof m.skills !== "string" && !isStringArray(m.skills)) {
+    issues.push("skills must be a string or an array of strings");
+  }
+  for (const key of ["agents", "commands", "apps", "hooks", "mcp", "homepage", "changelog", "license", "category"]) {
+    if (m[key] !== undefined && typeof m[key] !== "string") {
+      issues.push(`${key} must be a string`);
+    }
+  }
+  if (m.strict !== undefined && typeof m.strict !== "boolean") {
+    issues.push("strict must be a boolean");
+  }
+  if (m.dependencies !== undefined) {
+    if (!Array.isArray(m.dependencies)) {
+      issues.push("dependencies must be an array");
+    } else {
+      m.dependencies.forEach((dep, i) => {
+        if (typeof dep !== "object" || dep === null) {
+          issues.push(`dependencies[${i}] must be an object`);
+          return;
+        }
+        const d = dep as Record<string, unknown>;
+        if (typeof d.name !== "string") issues.push(`dependencies[${i}].name must be a string`);
+        if (typeof d.version !== "string") issues.push(`dependencies[${i}].version must be a string`);
+      });
+    }
+  }
+  // `adapters` is no longer part of the DSL. A stray one from an old manifest is
+  // tolerated (ignored) rather than rejected — output paths are ADG-internal.
+  return issues;
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}