@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-settings/src/deploy/profile.ts

@@ -0,0 +1,296 @@
+/**
+ * The deploy profile: for MCP servers and for agents, the source asset
+ * path AND the per-surface field/byte-shape mapping — target file/folder,
+ * container/table key, JSON array formatting style, and (for the four
+ * Markdown surfaces) the ordered YAML front-matter fields, including which
+ * source key each comes from, constants, presence-gating, and the
+ * comma-list style (packages/agent-settings/deploy-profile.json, shaped by
+ * ./deploy-profile.schema.json — both at the package root, never under
+ * src/, since they are data, not code).
+ *
+ * mcp-render.ts / agent-render.ts render generically from this document:
+ * neither hard-codes a surface name, a target file, a field name, or a
+ * constant value. What stays in code (documented at each site, per Tarun's
+ * review) is only what genuinely cannot be data:
+ *  - the codex-toml-block marker-replace algorithm and its blank-line
+ *    spacing (mcp-merge.ts) — an in-place text edit, not a value;
+ *  - the width-aware vs always-expanded JSON array FORMATTERS themselves
+ *    (json-pretty.ts) — a surface only names which one (`jsonStyle`);
+ *  - the fixed MEANING of the `from` vocabulary (mcp: command/args/
+ *    commandArgs; agents: name/description/model/claude_model/
+ *    cursor_model/tools) and of the `style: csv-list` transform — these are
+ *    a small, closed set of source projections, the same way
+ *    packages/agent-hooks/src/deploy/profile.ts keeps its opencode-plugin
+ *    slot correspondence in code rather than in JSON.
+ *
+ * Validated with ajv against deploy-profile.schema.json — the same
+ * ajv/ajv-formats-free approach packages/agent-skills/src/profile.ts uses
+ * (ajv-formats is not added: this schema uses no `format` keyword).
+ * `validateProfileDocument` also runs a handful of cross-field checks ajv's
+ * schema-shape validation cannot express on its own — see its own comment
+ * for the exact list.
+ */
+import Ajv, { type ErrorObject, type ValidateFunction } from "ajv";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export type McpSurfaceFormat = "json" | "toml-block";
+export type AgentSurfaceFormat = "md" | "toml";
+export type McpJsonStyle = "width-aware" | "expanded";
+export type McpFromToken = "command" | "args" | "commandArgs";
+/** The full set a `from` token may name across BOTH front-matter fields and TOML fields; which subset is valid for which is enforced by the schema's two separate enums (agentFrontMatterField vs agentTomlField). */
+export type AgentFromToken = "name" | "description" | "model" | "claude_model" | "cursor_model" | "tools" | "model_reasoning_effort" | "sandbox_mode";
+export type AgentFieldStyle = "plain" | "csv-list";
+
+export interface McpEntryField {
+  readonly key: string;
+  readonly from?: McpFromToken;
+  readonly const?: string | boolean | number;
+}
+
+/** A static (non-per-server) field in a `topLevel` TOML table — always a constant, since there is no per-server spec to draw `from`. */
+export interface McpTopLevelField {
+  readonly key: string;
+  readonly const: string | boolean | number;
+}
+
+/** A whole top-level TOML table a "toml-block" surface declares inside its managed block, e.g. `[features]\nhooks = true`. Only valid on "toml-block" (mcp-deploy.ts's `hasForeignTopLevelTable` skips declaring it, and reports a conflict instead, when the target file already carries a same-named table OUTSIDE the managed block — TOML forbids duplicate tables). */
+export interface McpTopLevelTable {
+  readonly table: string;
+  readonly fields: readonly McpTopLevelField[];
+}
+
+export interface McpSurface {
+  readonly name: string;
+  readonly format: McpSurfaceFormat;
+  readonly file: string;
+  /** Required for format "json": the top-level key holding the server map (e.g. "mcpServers", "mcp"). */
+  readonly containerKey?: string;
+  /** Required for format "json": which array formatter mcp-merge.ts/json-pretty.ts uses to serialize this file. */
+  readonly jsonStyle?: McpJsonStyle;
+  /** Required for format "toml-block": the TOML table prefix, e.g. "mcp_servers" -> `[mcp_servers.<name>]`. */
+  readonly tableKey?: string;
+  readonly entry: readonly McpEntryField[];
+  /** Only valid for format "toml-block": extra static top-level tables rendered inside the managed block, before the per-server stanzas. See McpTopLevelTable. */
+  readonly topLevel?: readonly McpTopLevelTable[];
+}
+
+export interface AgentFrontMatterField {
+  readonly key: string;
+  readonly from?: AgentFromToken;
+  readonly const?: string | boolean | number;
+  /** If set, this field (and its nested `fields`, if any) is emitted only when the source AgentDef has this key set — e.g. `"tools"` gates Claude's `tools:` line and OpenCode's `permission` block. */
+  readonly presentIf?: AgentFromToken;
+  readonly style?: AgentFieldStyle;
+  /** One level of nested front-matter, e.g. opencode's `permission: {edit: deny}`. */
+  readonly fields?: readonly AgentFrontMatterField[];
+}
+
+export interface AgentTomlField {
+  readonly key: string;
+  readonly from: AgentFromToken;
+}
+
+export interface AgentSurface {
+  readonly name: string;
+  readonly format: AgentSurfaceFormat;
+  readonly folder: string;
+  /** Required for format "md". */
+  readonly frontMatter?: readonly AgentFrontMatterField[];
+  /** Required for format "toml". */
+  readonly fields?: readonly AgentTomlField[];
+  /** Required for format "toml": which source key becomes the file's TOML body (the `developer_instructions = """..."""` field). */
+  readonly bodyField?: "developer_instructions";
+}
+
+export interface McpProfileSection {
+  readonly source: string;
+  readonly marker?: string;
+  readonly surfaces: readonly McpSurface[];
+}
+
+export interface AgentProfileSection {
+  readonly source: string;
+  readonly surfaces: readonly AgentSurface[];
+}
+
+export interface LeanCtxFile {
+  readonly asset: string;
+  readonly target: string;
+}
+
+export interface LeanCtxProfileSection {
+  readonly source: string;
+  readonly files: readonly LeanCtxFile[];
+}
+
+export interface DeployProfile {
+  readonly mcp: McpProfileSection;
+  readonly agents: AgentProfileSection;
+  /** Optional: absent in older/fixture profiles (e.g. tests/fixtures/two-surface-profile.json), which cover only mcp/agents. deployLeanCtx/doctorLeanCtx throw if called against a profile without this section. */
+  readonly leanCtx?: LeanCtxProfileSection;
+  /** Repo-relative path to the pre-agent-settings engine's own install lock, if this repo may still carry one (see deploy-profile.schema.json and legacy-lock.ts). */
+  readonly legacyLock?: string;
+}
+
+export const DEFAULT_PROFILE_PATH = fileURLToPath(new URL("../../deploy-profile.json", import.meta.url));
+export const DEFAULT_PROFILE_SCHEMA_PATH = fileURLToPath(new URL("../../deploy-profile.schema.json", import.meta.url));
+
+export interface ProfileIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+let cachedValidator: { readonly schemaPath: string; readonly validate: ValidateFunction } | undefined;
+
+function compileValidator(schemaPath: string): ValidateFunction {
+  if (cachedValidator?.schemaPath === schemaPath) return cachedValidator.validate;
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  // allowUnionTypes: this schema's `const` fields are typed `["string", "boolean", "number"]`
+  // (a profile constant may be any of those JSON scalar types); every other strict-mode check stays on.
+  const ajv = new Ajv({ allErrors: true, strict: true, allowUnionTypes: true });
+  const validate = ajv.compile(schema);
+  cachedValidator = { schemaPath, validate };
+  return validate;
+}
+
+function formatAjvError(error: ErrorObject): ProfileIssue {
+  const path = error.instancePath.length > 0 ? error.instancePath : "/";
+  return { path, message: `${path} ${error.message ?? "is invalid"}`.trim() };
+}
+
+/** Exactly one of `from` / `const` / `fields` must be set on a field item — the schema allows any combination (each is independently optional) because ajv can't easily express "exactly one of" across three differently-typed optional properties without duplicating every other constraint into each branch. */
+function checkExactlyOneOfFromConstFields(path: string, field: { readonly from?: unknown; readonly const?: unknown; readonly fields?: unknown }, issues: ProfileIssue[]): void {
+  const present = [field.from !== undefined, field.const !== undefined, field.fields !== undefined].filter(Boolean).length;
+  if (present !== 1) issues.push({ path, message: `${path} must set exactly one of "from", "const", "fields" (found ${present})` });
+}
+
+/**
+ * Cross-field checks ajv's schema-shape validation cannot express on its
+ * own:
+ *  - duplicate mcp surface `name` / `file`;
+ *  - duplicate agent surface `name` / `folder`;
+ *  - a "json" mcp surface must carry `containerKey` + `jsonStyle`, and must
+ *    NOT carry `tableKey`; a "toml-block" surface is the reverse — this is
+ *    a conditional-required relationship between `format` and its sibling
+ *    fields, which JSON Schema can only express via `if`/`then`/`else`
+ *    duplicated per branch, so it is checked here instead;
+ *  - an "md" agent surface must carry `frontMatter` and must not carry
+ *    `fields`/`bodyField`; a "toml" surface is the reverse (same reasoning);
+ *  - every front-matter/entry field sets exactly one of `from`/`const`/
+ *    `fields` (see checkExactlyOneOfFromConstFields).
+ */
+function crossFieldChecks(doc: DeployProfile): readonly ProfileIssue[] {
+  const issues: ProfileIssue[] = [];
+
+  const mcpNames = new Set<string>();
+  const mcpFiles = new Set<string>();
+  doc.mcp.surfaces.forEach((surface, index) => {
+    const p = `/mcp/surfaces/${index}`;
+    if (mcpNames.has(surface.name)) issues.push({ path: `${p}/name`, message: `duplicate mcp surface name: ${surface.name}` });
+    mcpNames.add(surface.name);
+    if (mcpFiles.has(surface.file)) issues.push({ path: `${p}/file`, message: `duplicate mcp surface file: ${surface.file}` });
+    mcpFiles.add(surface.file);
+
+    if (surface.format === "json") {
+      if (surface.containerKey === undefined) issues.push({ path: `${p}/containerKey`, message: 'a "json" surface requires containerKey' });
+      if (surface.jsonStyle === undefined) issues.push({ path: `${p}/jsonStyle`, message: 'a "json" surface requires jsonStyle' });
+      if (surface.tableKey !== undefined) issues.push({ path: `${p}/tableKey`, message: 'tableKey is only valid on a "toml-block" surface' });
+    } else {
+      if (surface.tableKey === undefined) issues.push({ path: `${p}/tableKey`, message: 'a "toml-block" surface requires tableKey' });
+      if (surface.containerKey !== undefined || surface.jsonStyle !== undefined) {
+        issues.push({ path: p, message: 'containerKey/jsonStyle are only valid on a "json" surface' });
+      }
+    }
+
+    if (surface.topLevel !== undefined) {
+      if (surface.format !== "toml-block") issues.push({ path: `${p}/topLevel`, message: 'topLevel is only valid on a "toml-block" surface' });
+      const topLevelTableNames = new Set<string>();
+      surface.topLevel.forEach((table, ti) => {
+        const tp = `${p}/topLevel/${ti}`;
+        if (topLevelTableNames.has(table.table)) issues.push({ path: `${tp}/table`, message: `duplicate topLevel table: ${table.table}` });
+        topLevelTableNames.add(table.table);
+      });
+    }
+
+    surface.entry.forEach((field, fi) => checkExactlyOneOfFromConstFields(`${p}/entry/${fi}`, field, issues));
+  });
+
+  const agentNames = new Set<string>();
+  const agentFolders = new Set<string>();
+  doc.agents.surfaces.forEach((surface, index) => {
+    const p = `/agents/surfaces/${index}`;
+    if (agentNames.has(surface.name)) issues.push({ path: `${p}/name`, message: `duplicate agent surface name: ${surface.name}` });
+    agentNames.add(surface.name);
+    if (agentFolders.has(surface.folder)) issues.push({ path: `${p}/folder`, message: `duplicate agent surface folder: ${surface.folder}` });
+    agentFolders.add(surface.folder);
+
+    function checkFrontMatterList(fields: readonly AgentFrontMatterField[], base: string): void {
+      fields.forEach((field, fi) => {
+        const fp = `${base}/${fi}`;
+        checkExactlyOneOfFromConstFields(fp, field, issues);
+        if (field.fields !== undefined) checkFrontMatterList(field.fields, `${fp}/fields`);
+      });
+    }
+
+    if (surface.format === "md") {
+      if (surface.frontMatter === undefined) issues.push({ path: `${p}/frontMatter`, message: 'an "md" surface requires frontMatter' });
+      else checkFrontMatterList(surface.frontMatter, `${p}/frontMatter`);
+      if (surface.fields !== undefined || surface.bodyField !== undefined) {
+        issues.push({ path: p, message: 'fields/bodyField are only valid on a "toml" surface' });
+      }
+    } else {
+      if (surface.fields === undefined) issues.push({ path: `${p}/fields`, message: 'a "toml" surface requires fields' });
+      if (surface.bodyField === undefined) issues.push({ path: `${p}/bodyField`, message: 'a "toml" surface requires bodyField' });
+      if (surface.frontMatter !== undefined) issues.push({ path: `${p}/frontMatter`, message: 'frontMatter is only valid on an "md" surface' });
+    }
+  });
+
+  if (doc.leanCtx !== undefined) {
+    const leanCtxTargets = new Set<string>();
+    const leanCtxAssets = new Set<string>();
+    doc.leanCtx.files.forEach((file, index) => {
+      const p = `/leanCtx/files/${index}`;
+      if (leanCtxTargets.has(file.target)) issues.push({ path: `${p}/target`, message: `duplicate leanCtx target: ${file.target}` });
+      leanCtxTargets.add(file.target);
+      if (leanCtxAssets.has(file.asset)) issues.push({ path: `${p}/asset`, message: `duplicate leanCtx asset: ${file.asset}` });
+      leanCtxAssets.add(file.asset);
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Validates a parsed deploy-profile document: ajv against
+ * deploy-profile.schema.json, plus `crossFieldChecks` (see its own
+ * comment). Pure: never throws for a structurally-wrong `doc` (returns
+ * issues instead); only a missing/malformed `schemaPath` throws.
+ */
+export function validateProfileDocument(doc: unknown, schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH): readonly ProfileIssue[] {
+  const validate = compileValidator(schemaPath);
+  if (!validate(doc)) {
+    return (validate.errors ?? []).map(formatAjvError);
+  }
+  if (!isRecord(doc)) return [{ path: "/", message: "profile must be a JSON object" }];
+  return crossFieldChecks(doc as unknown as DeployProfile);
+}
+
+/** Reads and validates a deploy profile from disk. Throws (fails loud) when the JSON is malformed or the document is invalid. */
+export function loadProfile(path: string = DEFAULT_PROFILE_PATH, schemaPath: string = DEFAULT_PROFILE_SCHEMA_PATH): DeployProfile {
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    throw new Error(`deploy profile is not valid JSON: ${path} (${(cause as Error).message})`);
+  }
+  const issues = validateProfileDocument(doc, schemaPath);
+  if (issues.length > 0) {
+    throw new Error(`deploy profile is invalid: ${path}\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`);
+  }
+  return doc as DeployProfile;
+}

package/packages/agent-settings/src/deploy/settings.ts

@@ -0,0 +1,65 @@
+/**
+ * The single entry points `adl settings deploy` / `adl settings doctor`
+ * call: MCP servers + agents + lean-ctx config, deployed/checked together
+ * against one target repo. Each part keeps its own conflict/issue
+ * reporting (deployMcp/deployAgents/deployLeanCtx, doctorMcp/doctorAgents/
+ * doctorLeanCtx); this module only aggregates them so the CLI has one
+ * function to call for each verb, and fails (deploySettings.ok === false,
+ * or doctorSettings.ok === false) if any one part fails.
+ */
+import { join } from "node:path";
+import { deployAgents, type DeployAgentsResult } from "./agents-deploy.js";
+import { loadAgentSources, type AgentDef } from "./agent-toml.js";
+import { doctorAgents, doctorLeanCtx, doctorMcp, mergeDoctorResults, type DoctorResult } from "./doctor.js";
+import { deployLeanCtx, type DeployLeanCtxResult } from "./lean-ctx-deploy.js";
+import { deployMcp, type DeployMcpResult } from "./mcp-deploy.js";
+import { loadMcpSource, type McpServerSpec } from "./mcp-source.js";
+import { type DeployProfile, loadProfile } from "./profile.js";
+
+export interface SettingsTargetOptions {
+  readonly assetsRoot: string; // packages/agent-settings package root (holds assets/mcp.json, assets/agents/, assets/lean-ctx/)
+  readonly targetRepo: string;
+  readonly profile?: DeployProfile;
+  readonly servers?: readonly McpServerSpec[];
+  readonly agents?: readonly AgentDef[];
+}
+
+export interface DeploySettingsResult {
+  readonly mcp: DeployMcpResult;
+  readonly agents: DeployAgentsResult;
+  readonly leanCtx: DeployLeanCtxResult;
+  readonly ok: boolean;
+}
+
+function resolveDirs(options: SettingsTargetOptions, profile: DeployProfile): { readonly agentsAssetsDir: string; readonly leanCtxAssetsDir: string } {
+  const agentsAssetsDir = join(options.assetsRoot, profile.agents.source);
+  const leanCtxAssetsDir = join(options.assetsRoot, profile.leanCtx?.source ?? "assets/lean-ctx");
+  return { agentsAssetsDir, leanCtxAssetsDir };
+}
+
+export function deploySettings(options: SettingsTargetOptions): DeploySettingsResult {
+  const profile = options.profile ?? loadProfile();
+  const servers = options.servers ?? loadMcpSource();
+  const { agentsAssetsDir, leanCtxAssetsDir } = resolveDirs(options, profile);
+  const agents = options.agents ?? loadAgentSources(agentsAssetsDir);
+
+  const mcp = deployMcp({ targetRepo: options.targetRepo, profile, servers });
+  const agentsResult = deployAgents({ assetsDir: agentsAssetsDir, targetRepo: options.targetRepo, profile, agents });
+  const leanCtx = deployLeanCtx({ assetsDir: leanCtxAssetsDir, targetRepo: options.targetRepo, profile });
+
+  const ok = mcp.conflicts.length === 0 && agentsResult.conflicts.length === 0 && leanCtx.conflicts.length === 0;
+  return { mcp, agents: agentsResult, leanCtx, ok };
+}
+
+export function doctorSettings(options: SettingsTargetOptions): DoctorResult {
+  const profile = options.profile ?? loadProfile();
+  const servers = options.servers ?? loadMcpSource();
+  const { agentsAssetsDir, leanCtxAssetsDir } = resolveDirs(options, profile);
+  const agents = options.agents ?? loadAgentSources(agentsAssetsDir);
+
+  return mergeDoctorResults([
+    doctorMcp({ targetRepo: options.targetRepo, profile, servers }),
+    doctorAgents({ assetsDir: agentsAssetsDir, targetRepo: options.targetRepo, profile, agents }),
+    doctorLeanCtx({ assetsDir: leanCtxAssetsDir, targetRepo: options.targetRepo, profile }),
+  ]);
+}

package/packages/agent-settings/src/global-agents.ts

@@ -0,0 +1,230 @@
+/**
+ * Deploy the canonical `packages/agent-settings/assets/GLOBAL-AGENTS.md` out
+ * to every AI-agent host's own global instruction file, so each host reads
+ * the same content: `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`,
+ * `~/.cursor/AGENTS.md`, `~/.kimi-code/AGENTS.md`,
+ * `~/.config/opencode/AGENTS.md`.
+ *
+ * The canonical source is committed in this repo (`../assets/GLOBAL-AGENTS.md`
+ * relative to this file), not read from any other repo's checkout at
+ * runtime — two different repos fighting over the same global target file is
+ * exactly the collision this replaces.
+ *
+ * Ownership model: GLOBAL-AGENTS.md is the single source of truth for every
+ * target. Deploy is always forced — there is no opt-out flag:
+ *   - missing target        -> created from the source.
+ *   - content === source    -> untouched (true no-op).
+ *   - content !== source    -> overwritten from the source (hand-edited or
+ *                              stale, both are drift). These exact files are
+ *                              authoritative adl roots: replacement does
+ *                              not retain a displaced copy.
+ * Any change to a host's global instructions must go through GLOBAL-AGENTS.md.
+ * Uninstall removes those same owned files regardless of their current bytes.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export interface AgentTarget {
+  readonly relativeDir: string
+  readonly file: string
+}
+
+export const AGENT_TARGETS: readonly AgentTarget[] = [
+  { relativeDir: '.claude', file: 'CLAUDE.md' },
+  { relativeDir: '.codex', file: 'AGENTS.md' },
+  { relativeDir: '.cursor', file: 'AGENTS.md' },
+  { relativeDir: '.kimi-code', file: 'AGENTS.md' },
+  { relativeDir: '.config/opencode', file: 'AGENTS.md' },
+]
+
+export const DEFAULT_SOURCE_PATH = fileURLToPath(new URL('../assets/GLOBAL-AGENTS.md', import.meta.url))
+
+export type TargetState = 'missing' | 'matches' | 'drifted'
+
+export interface TargetStatus {
+  readonly relativeDir: string
+  readonly file: string
+  readonly path: string
+  readonly state: TargetState
+}
+
+export interface StatusNote {
+  readonly level: 'ok' | 'warn'
+  readonly text: string
+}
+
+export interface DeployResult {
+  readonly written: readonly string[]
+  readonly overwritten: readonly string[]
+  readonly alreadyMatching: readonly string[]
+  readonly notes: readonly StatusNote[]
+}
+
+export interface UninstallResult {
+  readonly removed: readonly string[]
+  readonly notes: readonly StatusNote[]
+}
+
+/**
+ * Pure classification of one target's ownership state. No I/O: callers read
+ * the target's content (or `null` when missing) and pass it in.
+ */
+export function classifyTarget(existingContent: string | null, sourceContent: string): TargetState {
+  if (existingContent === null) return 'missing'
+  return existingContent === sourceContent ? 'matches' : 'drifted'
+}
+
+function targetPath(home: string, target: AgentTarget): string {
+  return join(home, target.relativeDir, target.file)
+}
+
+function readTargetContent(path: string): string | null {
+  if (!existsSync(path)) return null
+  if (!lstatSync(path).isFile()) return null
+  return readFileSync(path, 'utf8')
+}
+
+function messageOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+/**
+ * Read-only status of every target against `sourceContent`. Used by both the
+ * `status` CLI mode and internally by deploy/uninstall.
+ */
+export function inspectGlobalAgents(home: string, sourceContent: string): readonly TargetStatus[] {
+  if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`)
+  const resolvedHome = resolve(home)
+  return AGENT_TARGETS.map((target) => {
+    const path = targetPath(resolvedHome, target)
+    const state = classifyTarget(readTargetContent(path), sourceContent)
+    return { relativeDir: target.relativeDir, file: target.file, path, state }
+  })
+}
+
+function atomicWriteFile(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = join(dirname(path), `.global-agents.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(temporary, content, { mode: 0o644 })
+    renameSync(temporary, path)
+  } catch (cause) {
+    rmSync(temporary, { force: true })
+    throw cause
+  }
+}
+
+/**
+ * Forced deploy of `sourceContent` to every target: missing targets are
+ * created, matching targets are left alone, and drifted targets are replaced.
+ */
+export function deployGlobalAgents(home: string, sourceContent: string): DeployResult {
+  const statuses = inspectGlobalAgents(home, sourceContent)
+  const written: string[] = []
+  const overwritten: string[] = []
+  const alreadyMatching: string[] = []
+  const notes: StatusNote[] = []
+
+  for (const status of statuses) {
+    if (status.state === 'matches') {
+      alreadyMatching.push(status.path)
+      notes.push({ level: 'ok', text: `already deployed at ${status.path}` })
+      continue
+    }
+    if (status.state === 'drifted') {
+      atomicWriteFile(status.path, sourceContent)
+      overwritten.push(status.path)
+      notes.push({ level: 'ok', text: `replaced drifted ${status.path}` })
+      continue
+    }
+    atomicWriteFile(status.path, sourceContent)
+    written.push(status.path)
+    notes.push({ level: 'ok', text: `deployed to ${status.path}` })
+  }
+
+  return { written, overwritten, alreadyMatching, notes }
+}
+
+/**
+ * Remove every adl-owned target. Its current bytes never alter ownership.
+ */
+export function uninstallGlobalAgents(home: string, sourceContent: string): UninstallResult {
+  const statuses = inspectGlobalAgents(home, sourceContent)
+  const removed: string[] = []
+  const notes: StatusNote[] = []
+
+  for (const status of statuses) {
+    if (status.state === 'missing') continue
+    rmSync(status.path, { force: true })
+    removed.push(status.path)
+    notes.push({ level: 'ok', text: `removed ${status.path}` })
+  }
+
+  return { removed, notes }
+}
+
+function readSource(sourcePath: string): string {
+  if (!existsSync(sourcePath)) {
+    throw new Error(`canonical source is missing: ${sourcePath}`)
+  }
+  return readFileSync(sourcePath, 'utf8')
+}
+
+function usage(): never {
+  throw new Error('usage: global-agents --home ABSOLUTE_PATH --mode deploy|status|uninstall')
+}
+
+export function main(argv: readonly string[]): void {
+  let home = ''
+  let mode = 'status'
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (argument === '--home') home = argv[++index] ?? ''
+    else if (argument === '--mode') mode = argv[++index] ?? ''
+    else usage()
+  }
+  if (home.length === 0 || !['deploy', 'status', 'uninstall'].includes(mode)) usage()
+
+  const sourceContent = readSource(DEFAULT_SOURCE_PATH)
+
+  if (mode === 'status') {
+    const statuses = inspectGlobalAgents(home, sourceContent)
+    for (const status of statuses) console.log(`${status.state}: ${status.path}`)
+    const clean = statuses.every((status) => status.state === 'matches')
+    console.log(`global-agents: ${statuses.length} target(s); ${clean ? 'all match the source' : 'drift or missing targets present'}`)
+    return
+  }
+
+  if (mode === 'deploy') {
+    const result = deployGlobalAgents(home, sourceContent)
+    for (const note of result.notes) console.log(`${note.level}: ${note.text}`)
+    console.log(
+      `global-agents: deployed ${result.written.length}, overwritten ${result.overwritten.length}, already matching ${result.alreadyMatching.length}`,
+    )
+    return
+  }
+
+  const result = uninstallGlobalAgents(home, sourceContent)
+  for (const note of result.notes) console.log(`${note.level}: ${note.text}`)
+  console.log(`global-agents: removed ${result.removed.length}`)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (cause) {
+    console.error(`global-agents: ${messageOf(cause)}`)
+    process.exitCode = 1
+  }
+}