harnessbrew 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.6.0 - 2026-08-13
+
+### Added
+
+- add a versioned JSON CLI envelope with command-level results and structured errors
+- add transactional `--dry-run` previews that report path fingerprints and roll back all managed changes
+- add Target Adapter API v1 with validated registration, Cellar-bounded symlink plans, transaction-managed execution, and lockfile version fingerprints
+- add explicit CLI management for trusted Adapter modules with persisted identity verification and transactional previews
+
+### Security
+
+- validate complete Receipt structures, canonical Cellar locations, operation metadata, owned keys, and all destructive paths before use
+- detect added, removed, modified, unsupported, and permission-changed Cellar files through exact inventory comparison
+- prevent forced cleanup from recursively deleting a real directory that replaced a managed directory symlink
+- serialize CLI mutations per HarnessBrew home and protect shared Target configuration updates across processes
+- recover interrupted mutations from durable write-ahead journals, including abandoned process locks and external Target files
+- add Harnessfile and lockfile v2 with structured scopes, portable paths, content digests, explicit lock refresh, and Target convergence
+- require explicit Tap trust before Target activation, enforce fast-forward updates by default, and roll back invalid Tap candidates
+
 ## 0.5.2 - 2026-08-13
 
 ### Fixed

package/README.md

@@ -41,7 +41,7 @@ HarnessBrew 默认将受管状态保存到 `~/.harnessbrew`。测试或隔离环
 注册自己的资产 Tap：
 
 ```bash
-harnessbrew tap add xiejinheng/agents git@github.com:xiejinheng/agent-assets.git
+harnessbrew tap add xiejinheng/agents git@github.com:xiejinheng/agent-assets.git --trust
 ```
 
 搜索并查看 Formula：
@@ -64,7 +64,7 @@ harnessbrew install xiejinheng/agents/code-review \
 更新和升级：
 
 ```bash
-harnessbrew update
+harnessbrew update [--allow-rewind]
 harnessbrew outdated
 harnessbrew upgrade code-review
 ```
@@ -140,7 +140,8 @@ Git commit 是安装版本的唯一事实来源；Formula 不维护 `.snapshots`
 
 MCP Formula 的入口是统一 JSON。stdio 配置使用 `command`、可选 `args` 和只包含环境变量名称的 `envVars`；HTTP 配置使用 `transport: "http"`、`url`、可选 `bearerTokenEnvVar` 与 `headersFromEnv`。HarnessBrew 不接受入口中的明文 `env` 密钥值。
 
-`adapter` Formula 当前是可由 Git/Cellar 管理的扩展包，但内置 Target 不执行它。请使用不带 `--target` 的 `install` 保存；`link` 或 `install --target` 会明确拒绝，直到插件运行时接口开放。
+`adapter` Formula 是可由 Git/Cellar 管理的扩展资产，但不会作为代码自动执行。Target Adapter 运行时使用单独的可信模块机制：先审查并安装 npm 包，
+再通过 `harnessbrew adapter add <module>` 显式授权。这样 Tap 仍保持声明式、不执行任意代码，而第三方 Target 可以接入版本化 Adapter SDK。
 
 ## Target
 
@@ -187,26 +188,41 @@ harnessbrew unlink code-review --target openai-codex
 `Harnessfile` 适合提交到个人 dotfiles 或项目仓库：
 
 ```yaml
-schemaVersion: 1
+schemaVersion: 2
 taps:
   - name: xiejinheng/agents
     git: git@github.com:xiejinheng/agent-assets.git
     ref: main
+    trust: true
 
 assets:
   - formula: xiejinheng/agents/code-review
-    targets: [openai-codex]
+    targets:
+      - target: openai-codex
+        scope: user
+      - target: claude-code
+        scope: project
+        project: .
 ```
 
+v2 的 Target placement 可以声明 `user` 或 `project` scope，并可使用相对于 `Harnessfile` 的 `project` 和 `root` 路径。
+schema v1 的 `targets: [openai-codex]` 仍然兼容，并按 user scope 解释。
+
 安装并生成 `Harnessfile.lock`：
 
 ```bash
 harnessbrew bundle install
 ```
 
-lockfile 会记录每个 Tap 的准确 commit、依赖闭包和 target，应与 `Harnessfile` 一起提交到 Git。
+v2 lockfile 会记录 Manifest 摘要、HarnessBrew Adapter 版本、每个 Tap 的准确 commit、Formula 内容摘要、依赖闭包和完整 Target placement，
+应与 `Harnessfile` 一起提交到 Git。
 
 在其他设备运行同一命令时，HarnessBrew 会检出 lockfile 固定的 commit，而不是未经确认地使用 Tap 最新版本。
+修改 v2 Harnessfile 后需要显式更新 lockfile：
+
+```bash
+harnessbrew bundle install --update-lock
+```
 
 清理清单之外的受管资产：
 
@@ -223,9 +239,11 @@ harnessbrew bundle install --file ./config/Harnessfile
 ## CLI
 
 ```text
-harnessbrew tap add <owner/name> <git-url> [--ref <ref>]
+harnessbrew tap add <owner/name> <git-url> [--ref <ref>] [--trust]
 harnessbrew tap list
-harnessbrew tap update [owner/name]
+harnessbrew tap update [owner/name] [--allow-rewind]
+harnessbrew tap trust <owner/name>
+harnessbrew tap untrust <owner/name>
 harnessbrew tap remove <owner/name>
 harnessbrew untap <owner/name>
 harnessbrew search [query] [--kind <kind>] [--target <target>]
@@ -240,10 +258,20 @@ harnessbrew update
 harnessbrew outdated
 harnessbrew upgrade [formula]
 harnessbrew uninstall <formula> [--force]
-harnessbrew bundle install [--file <path>]
+harnessbrew bundle install [--file <path>] [--update-lock]
 harnessbrew bundle cleanup [--file <path>]
 ```
 
+所有命令都可追加 `--json`，stdout 将只包含一个 schema v1 JSON envelope：`result` 是命令级结构化结果，`output` 保留人类文本，
+失败时包含 `error.code`、`error.message`、`diagnostics` 和非零 `exitCode`。
+
+变更命令可追加 `--dry-run`。HarnessBrew 会在同一 Home 写锁下完整执行校验和安装事务，收集每个路径的 before/after 类型与摘要，
+随后回滚 Cellar、Receipt、Tap checkout 和 Agent Target；与 `--json` 组合时，预览位于 `changes` 数组。dry-run 可能执行 Git fetch/clone 等只读网络操作。
+
+```bash
+harnessbrew install code-review --target openai-codex --dry-run --json
+```
+
 ## 本地目录
 
 ```text
@@ -259,6 +287,8 @@ Tap 工作树和 Cellar 内容都由 HarnessBrew 管理，不应直接编辑。
 ## 安全边界
 
 - Formula 是声明式 JSON；HarnessBrew 不执行 Tap 中的任意脚本。
+- 新注册的 Tap 默认不受信任：可以搜索和安装到 Cellar，但必须通过 `tap trust`、`tap add --trust` 或 Harnessfile v2 的 `trust: true` 才能链接或渲染到 Agent Target。旧状态记录按兼容策略视为已信任。
+- Tap 更新默认只接受 Git fast-forward；仓库历史被重写时必须人工检查后使用 `--allow-rewind`。候选 commit 校验失败会恢复原 checkout 和状态。
 - Formula 入口不能逃逸所属目录。
 - 安装前会检查依赖、冲突和 target 兼容性。
 - HarnessBrew 不覆盖未由 Receipt 管理的目标文件。
@@ -278,6 +308,55 @@ npm run check
 
 `npm run check` 会执行 TypeScript 编译、全部 Node.js 测试、安装包冒烟测试和 `npm pack --dry-run`。
 
+## Target Adapter SDK
+
+Node.js/TypeScript 宿主可以通过公开 API 注册第三方 Agent Target。Adapter API v1 只接收 Receipt 与 Target Context，并返回一条声明式安装计划；
+实际写入、冲突检测、Receipt、doctor、relink、upgrade、dry-run 和回滚仍由 HarnessBrew transaction layer 负责。
+
+```ts
+import { registerTargetAdapter, type TargetAdapter } from "harnessbrew";
+
+const adapter: TargetAdapter = {
+  apiVersion: 1,
+  name: "cursor",
+  version: "1.0.0",
+  capabilities: {
+    skill: "symlink-directory",
+    agent: "symlink-file",
+    workflow: "symlink-file",
+    instruction: "symlink-file",
+    prompt: "symlink-file",
+    mcp: "unsupported",
+    adapter: "unsupported"
+  },
+  plan(receipt, context = {}) {
+    // Return one absolute destination and a source inside receipt.cellarPath.
+    return { target: "cursor", coordinate: receipt.coordinate, operations: [/* ... */] };
+  }
+};
+
+const unregister = registerTargetAdapter(adapter);
+```
+
+SDK 会校验 API 版本、名称、版本、完整能力矩阵、计划身份、绝对目标路径和 Cellar source 边界。v1 的第三方 Adapter 计划只允许
+`symlink-file`、`symlink-directory` 和 `unsupported`，不提供直接写文件或生成共享配置的操作。注册是显式、进程内操作；HarnessBrew 不会从 Tap
+自动执行 Adapter Formula。第三方 Adapter 本身是具有宿主进程权限的可信代码，只应加载经过审查的 npm 包。
+
+独立 CLI 可以持久化管理可信 Adapter 模块。模块需已通过 npm 安装并可被 `harnessbrew` 解析，也可以使用绝对路径或 `file://` URL；它必须默认导出
+一个 Adapter，或提供名为 `adapter` 的导出：
+
+```bash
+harnessbrew adapter add @harnessbrew/adapter-cursor
+harnessbrew adapter list
+harnessbrew install review --target cursor
+harnessbrew adapter remove cursor
+```
+
+`adapter add` 是一次显式的代码执行授权。HarnessBrew 将模块标识及审核时的 name、version、API version 写入
+`~/.harnessbrew/adapters.json`；后续只在 install/link/unlink/relink/upgrade/bundle 需要 Target 时加载，并在每次加载时核对身份。
+如果包升级改变身份，命令会关闭失败，要求先 remove、审查后再 add。`adapter list/remove` 本身不执行插件，HarnessBrew 也不会自动运行 `npm install`。
+CLI 加载的 Target 同样进入 Harnessfile v2 lock 的 Adapter 签名。
+
 ## 架构
 
 完整设计见 [docs/architecture.md](docs/architecture.md)。

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import { type TransactionChange } from "./core/journal.js";
 export interface CliIO {
     stdout: (message: string) => void;
     stderr: (message: string) => void;
@@ -5,5 +6,21 @@ export interface CliIO {
 export interface CliOptions {
     home?: string;
 }
+export interface CliJsonError {
+    code: "COMMAND_FAILED" | "HARNESSBREW_ERROR";
+    message: string;
+}
+export interface CliJsonEnvelope {
+    schemaVersion: 1;
+    ok: boolean;
+    command: string;
+    exitCode: number;
+    dryRun: boolean;
+    result: unknown;
+    output: string[];
+    diagnostics: string[];
+    error?: CliJsonError;
+    changes?: TransactionChange[];
+}
 export declare function runCli(args: readonly string[], io?: CliIO, options?: CliOptions): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA4SD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAAiB,EACrB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CAUjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAyBA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,GAAG,mBAAmB,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AA4XD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAAiB,EACrB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CA6FjB"}

package/dist/cli.js

@@ -2,13 +2,20 @@ import path from "node:path";
 import { HarnessBrewError } from "./core/errors.js";
 import { formulaKinds, getFormula, searchFormulas } from "./core/formulas.js";
 import { installFormula, listInstalled, uninstallFormula } from "./core/installations.js";
-import { builtinTargets, installForTarget, linkFormula, unlinkFormula } from "./core/targets.js";
+import { installForTarget, linkFormula, unlinkFormula } from "./core/targets.js";
+import { hasTargetAdapter } from "./core/targets/registry.js";
 import { findOutdated, upgradeFormulas } from "./core/upgrades.js";
 import { bundleCleanup, bundleInstall } from "./core/bundle.js";
 import { resolveHarnessHome } from "./core/paths.js";
-import { addTap, listTaps, removeTap, updateTaps } from "./core/taps.js";
+import { addTap, listTaps, removeTap, setTapTrust, updateTaps } from "./core/taps.js";
 import { VERSION } from "./version.js";
 import { doctor, relinkFormula } from "./core/doctor.js";
+import { addAdapterPlugin, listAdapterPlugins, loadAdapterPlugins, removeAdapterPlugin } from "./core/adapter-plugins.js";
+import { withHomeLock } from "./core/locks.js";
+import { withJournalPreview, withJournalTransaction } from "./core/journal.js";
+function setResult(io, result) {
+    io.setResult?.(result);
+}
 const defaultIO = {
     stdout: (message) => console.log(message),
     stderr: (message) => console.error(message)
@@ -18,12 +25,12 @@ const helpText = `HarnessBrew ${VERSION}
 A Git-native package manager for AI Agent assets.
 
 Usage:
-  harnessbrew <command> [options]
+  harnessbrew <command> [options] [--json] [--dry-run]
 
 Commands:
   help       Show this help
   version    Show the installed version
-  tap        Add, list, update, or remove Git taps
+  tap        Add, trust, list, update, or remove Git taps
   untap      Remove a Git tap
   search     Search formulas across registered taps
   info       Show formula metadata
@@ -38,11 +45,16 @@ Commands:
   outdated   List installed formulas with available changes
   upgrade    Upgrade formulas while preserving target links
   bundle     Rebuild or clean an environment from Harnessfile
+  adapter    Add, list, or remove trusted Target Adapter modules
 
 Target placement options:
   --scope <user|project>  Select user or project installation scope
   --project <path>        Project root (implies --scope project)
   --target-root <path>    Override the target's native root
+
+Automation options:
+  --json                  Emit one versioned JSON result envelope
+  --dry-run               Execute a mutation transaction, report changes, then roll it back
 `;
 function optionValue(args, name) {
     const index = args.indexOf(name);
@@ -77,65 +89,118 @@ async function runTapCommand(args, home, io) {
     const [action = "list", ...rest] = args;
     if (action === "list") {
         const taps = await listTaps(home);
-        taps.forEach((tap) => io.stdout(`${tap.name}\t${tap.commit.slice(0, 12)}\t${tap.url}`));
+        taps.forEach((tap) => io.stdout(`${tap.name}\t${tap.trusted ? "trusted" : "untrusted"}\t${tap.commit.slice(0, 12)}\t${tap.url}`));
+        setResult(io, taps);
         return 0;
     }
     if (action === "add") {
         const [name, url] = rest;
         if (name === undefined || url === undefined) {
-            throw new HarnessBrewError("Usage: harnessbrew tap add <owner/name> <git-url> [--ref <ref>]");
+            throw new HarnessBrewError("Usage: harnessbrew tap add <owner/name> <git-url> [--ref <ref>] [--trust]");
         }
         const ref = optionValue(rest, "--ref");
-        const record = await addTap(home, name, url, ref === undefined ? {} : { ref });
+        const record = await addTap(home, name, url, {
+            ...(ref === undefined ? {} : { ref }),
+            trust: rest.includes("--trust")
+        });
         io.stdout(`Tapped ${record.name} at ${record.commit.slice(0, 12)}.`);
+        setResult(io, record);
         return 0;
     }
     if (action === "update") {
-        const updates = await updateTaps(home, rest[0]);
+        const requested = rest.find((value) => !value.startsWith("--"));
+        const updates = await updateTaps(home, requested, { allowRewind: rest.includes("--allow-rewind") });
         updates.forEach((update) => {
             io.stdout(update.changed
                 ? `Updated ${update.name}: ${update.before.slice(0, 12)} -> ${update.after.slice(0, 12)}.`
                 : `${update.name} is already up-to-date.`);
         });
+        setResult(io, updates);
         return 0;
     }
     if (action === "remove") {
         const [name] = rest;
         if (name === undefined)
             throw new HarnessBrewError("Usage: harnessbrew tap remove <owner/name>");
-        await removeTap(home, name);
+        const record = await removeTap(home, name);
         io.stdout(`Untapped ${name}.`);
+        setResult(io, record);
+        return 0;
+    }
+    if (action === "trust" || action === "untrust") {
+        const [name] = rest;
+        if (name === undefined)
+            throw new HarnessBrewError(`Usage: harnessbrew tap ${action} <owner/name>`);
+        const record = await setTapTrust(home, name, action === "trust");
+        io.stdout(`${record.name} is now ${record.trusted ? "trusted" : "untrusted"}.`);
+        setResult(io, record);
         return 0;
     }
     throw new HarnessBrewError(`Unknown tap action: ${action}`);
 }
+async function runAdapterCommand(args, home, io) {
+    const [action = "list", ...rest] = args;
+    if (action === "list") {
+        const records = await listAdapterPlugins(home);
+        records.forEach((record) => io.stdout(`${record.name}\t${record.version}\t${record.module}`));
+        setResult(io, records);
+        return 0;
+    }
+    if (action === "add") {
+        const [moduleSpecifier] = rest;
+        if (moduleSpecifier === undefined) {
+            throw new HarnessBrewError("Usage: harnessbrew adapter add <npm-package|absolute-path|file-url>");
+        }
+        const record = await addAdapterPlugin(home, moduleSpecifier);
+        io.stdout(`Added trusted Adapter ${record.name}@${record.version} from ${record.module}.`);
+        setResult(io, record);
+        return 0;
+    }
+    if (action === "remove") {
+        const [name] = rest;
+        if (name === undefined)
+            throw new HarnessBrewError("Usage: harnessbrew adapter remove <target>");
+        const record = await removeAdapterPlugin(home, name);
+        io.stdout(`Removed Adapter ${record.name}@${record.version}.`);
+        setResult(io, record);
+        return 0;
+    }
+    throw new HarnessBrewError(`Unknown adapter action: ${action}`);
+}
 async function execute(args, io, options) {
     const [command] = args;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
         io.stdout(helpText.trimEnd());
+        setResult(io, { help: helpText.trimEnd() });
         return 0;
     }
     if (command === "version" || command === "--version" || command === "-v") {
         io.stdout(VERSION);
+        setResult(io, { version: VERSION });
         return 0;
     }
     const home = resolveHarnessHome(options.home);
+    if (command === "adapter") {
+        return runAdapterCommand(args.slice(1), home, io);
+    }
     if (command === "tap") {
         return runTapCommand(args.slice(1), home, io);
     }
     if (command === "update") {
-        const updates = await updateTaps(home);
+        const updates = await updateTaps(home, undefined, { allowRewind: args.includes("--allow-rewind") });
         updates.forEach((update) => io.stdout(update.changed
             ? `Updated ${update.name}: ${update.before.slice(0, 12)} -> ${update.after.slice(0, 12)}.`
             : `${update.name} is already up-to-date.`));
+        setResult(io, updates);
         return 0;
     }
     if (command === "untap") {
         const name = args[1];
         if (name === undefined)
             throw new HarnessBrewError("Usage: harnessbrew untap <owner/name>");
-        await removeTap(home, name);
+        const record = await removeTap(home, name);
         io.stdout(`Untapped ${name}.`);
+        setResult(io, record);
         return 0;
     }
     if (command === "search") {
@@ -154,6 +219,7 @@ async function execute(args, io, options) {
             ...(target === undefined ? {} : { target })
         });
         formulas.forEach((formula) => io.stdout(`${formula.coordinate}\t${formula.kind}\t${formula.description}`));
+        setResult(io, formulas);
         return 0;
     }
     if (command === "info") {
@@ -161,7 +227,7 @@ async function execute(args, io, options) {
         if (name === undefined)
             throw new HarnessBrewError("Usage: harnessbrew info <formula>");
         const formula = await getFormula(home, name);
-        io.stdout(JSON.stringify({
+        const result = {
             coordinate: formula.coordinate,
             kind: formula.kind,
             description: formula.description,
@@ -169,7 +235,9 @@ async function execute(args, io, options) {
             dependencies: formula.dependencies,
             commit: formula.commit,
             ...(formula.deprecated === undefined ? {} : { deprecated: formula.deprecated })
-        }, null, 2));
+        };
+        io.stdout(JSON.stringify(result, null, 2));
+        setResult(io, result);
         return 0;
     }
     if (command === "install") {
@@ -177,18 +245,20 @@ async function execute(args, io, options) {
         if (name === undefined)
             throw new HarnessBrewError("Usage: harnessbrew install <formula>");
         const targetValue = optionValue(args, "--target");
-        if (targetValue !== undefined && !builtinTargets.includes(targetValue)) {
-            throw new HarnessBrewError(`Unsupported built-in target: ${targetValue}`);
+        if (targetValue !== undefined && !hasTargetAdapter(targetValue)) {
+            throw new HarnessBrewError(`Target adapter is not registered: ${targetValue}`);
         }
         const receipts = targetValue === undefined
             ? await installFormula(home, name)
             : await installForTarget(home, name, targetValue, targetOptions(args));
         receipts.forEach((receipt) => io.stdout(`Installed ${receipt.coordinate} at ${receipt.commit.slice(0, 12)}.`));
+        setResult(io, receipts);
         return 0;
     }
     if (command === "list") {
         const receipts = await listInstalled(home);
         receipts.forEach((receipt) => io.stdout(`${receipt.coordinate}\t${receipt.commit.slice(0, 12)}`));
+        setResult(io, receipts);
         return 0;
     }
     if (command === "uninstall") {
@@ -197,6 +267,7 @@ async function execute(args, io, options) {
             throw new HarnessBrewError("Usage: harnessbrew uninstall <formula> [--force]");
         const receipt = await uninstallFormula(home, name, { force: args.includes("--force") });
         io.stdout(`Uninstalled ${receipt.coordinate}.`);
+        setResult(io, receipt);
         return 0;
     }
     if (command === "link" || command === "unlink") {
@@ -205,25 +276,28 @@ async function execute(args, io, options) {
         if (name === undefined || targetValue === undefined) {
             throw new HarnessBrewError(`Usage: harnessbrew ${command} <formula> --target <target> [--scope <user|project>] [--project <path>]`);
         }
-        if (!builtinTargets.includes(targetValue)) {
-            throw new HarnessBrewError(`Unsupported built-in target: ${targetValue}`);
+        if (!hasTargetAdapter(targetValue)) {
+            throw new HarnessBrewError(`Target adapter is not registered: ${targetValue}`);
         }
         if (command === "link") {
-            await linkFormula(home, name, targetValue, targetOptions(args));
+            const receipt = await linkFormula(home, name, targetValue, targetOptions(args));
             io.stdout(`Linked ${name} to ${targetValue}.`);
+            setResult(io, receipt);
         }
         else {
-            await unlinkFormula(home, name, targetValue, {
+            const receipt = await unlinkFormula(home, name, targetValue, {
                 ...(hasTargetPlacementOptions(args) ? targetOptions(args) : {}),
                 force: args.includes("--force")
             });
             io.stdout(`Unlinked ${name} from ${targetValue}.`);
+            setResult(io, receipt);
         }
         return 0;
     }
     if (command === "doctor") {
         const name = args[1]?.startsWith("--") === true ? undefined : args[1];
         const report = await doctor(home, name);
+        setResult(io, report);
         if (report.healthy) {
             io.stdout(`Doctor found no issues across ${report.checked} formula(s).`);
             return 0;
@@ -241,14 +315,15 @@ async function execute(args, io, options) {
         if (name === undefined)
             throw new HarnessBrewError("Usage: harnessbrew relink <formula> [--target <target>]");
         const targetValue = optionValue(args, "--target");
-        if (targetValue !== undefined && !builtinTargets.includes(targetValue)) {
-            throw new HarnessBrewError(`Unsupported built-in target: ${targetValue}`);
+        if (targetValue !== undefined && !hasTargetAdapter(targetValue)) {
+            throw new HarnessBrewError(`Target adapter is not registered: ${targetValue}`);
         }
-        await relinkFormula(home, name, {
+        const receipt = await relinkFormula(home, name, {
             ...(hasTargetPlacementOptions(args) ? targetOptions(args) : {}),
             ...(targetValue === undefined ? {} : { target: targetValue })
         });
         io.stdout(`Relinked ${name}${targetValue === undefined ? "" : ` to ${targetValue}`}.`);
+        setResult(io, receipt);
         return 0;
     }
     if (command === "outdated") {
@@ -256,6 +331,7 @@ async function execute(args, io, options) {
         outdated.forEach((item) => io.stdout(item.available
             ? `${item.coordinate}\t${item.installedCommit.slice(0, 12)} -> ${item.availableCommit?.slice(0, 12)}`
             : `${item.coordinate}\t${item.installedCommit.slice(0, 12)} -> unavailable`));
+        setResult(io, outdated);
         return 0;
     }
     if (command === "upgrade") {
@@ -264,34 +340,116 @@ async function execute(args, io, options) {
         if (results.length === 0)
             io.stdout("All installed formulas are up-to-date.");
         results.forEach((result) => io.stdout(`Upgraded ${result.coordinate}: ${result.before.slice(0, 12)} -> ${result.after.slice(0, 12)}.`));
+        setResult(io, results);
         return 0;
     }
     if (command === "bundle") {
         const action = args[1];
         const filePath = optionValue(args, "--file") ?? path.resolve("Harnessfile");
         if (action === "install") {
-            const lock = await bundleInstall(home, filePath);
+            const lock = await bundleInstall(home, filePath, { updateLock: args.includes("--update-lock") });
             io.stdout(`Bundle installed ${lock.assets.length} formulas from ${lock.taps.length} taps.`);
+            setResult(io, lock);
             return 0;
         }
         if (action === "cleanup") {
             const result = await bundleCleanup(home, filePath);
             result.removed.forEach((coordinate) => io.stdout(`Removed ${coordinate}.`));
+            setResult(io, result);
             return 0;
         }
-        throw new HarnessBrewError("Usage: harnessbrew bundle <install|cleanup> [--file <Harnessfile>]");
+        throw new HarnessBrewError("Usage: harnessbrew bundle <install|cleanup> [--file <Harnessfile>] [--update-lock]");
     }
     io.stderr(`Unknown command: ${command}`);
     io.stderr("Run 'harnessbrew help' for usage.");
     return 1;
 }
 export async function runCli(args, io = defaultIO, options = {}) {
+    const json = args.includes("--json");
+    const dryRun = args.includes("--dry-run");
+    const commandArgs = args.filter((argument) => argument !== "--json" && argument !== "--dry-run");
+    const output = [];
+    const diagnostics = [];
+    let result = null;
+    const commandIO = json || dryRun
+        ? {
+            stdout: (message) => output.push(message),
+            stderr: (message) => diagnostics.push(message),
+            setResult: (value) => { result = value; }
+        }
+        : io;
+    const command = commandArgs[0];
+    const tapAction = command === "tap" ? (commandArgs[1] ?? "list") : undefined;
+    const adapterAction = command === "adapter" ? (commandArgs[1] ?? "list") : undefined;
+    const mutates = command === "update" || command === "untap" || command === "install"
+        || command === "uninstall" || command === "link" || command === "unlink" || command === "relink"
+        || command === "upgrade" || command === "bundle"
+        || (command === "tap" && tapAction !== "list")
+        || (command === "adapter" && adapterAction !== "list");
+    const emitJson = (exitCode, changes = [], errorCode) => {
+        const envelope = {
+            schemaVersion: 1,
+            ok: exitCode === 0,
+            command: command ?? "help",
+            exitCode,
+            dryRun,
+            result,
+            output,
+            diagnostics,
+            ...(exitCode === 0 ? {} : {
+                error: {
+                    code: errorCode ?? "COMMAND_FAILED",
+                    message: diagnostics[0] ?? "Command failed."
+                }
+            }),
+            ...(dryRun ? { changes } : {})
+        };
+        io.stdout(JSON.stringify(envelope));
+    };
     try {
-        return await execute(args, io, options);
+        const home = resolveHarnessHome(options.home);
+        if (dryRun && !mutates)
+            throw new HarnessBrewError("--dry-run requires a mutating command.");
+        const invoke = async () => {
+            const unload = command !== undefined
+                && ["install", "link", "unlink", "relink", "upgrade", "bundle"].includes(command)
+                ? await loadAdapterPlugins(home)
+                : () => { };
+            try {
+                return await execute(commandArgs, commandIO, options);
+            }
+            finally {
+                unload();
+            }
+        };
+        let exitCode;
+        let changes = [];
+        if (dryRun) {
+            const preview = await withHomeLock(home, () => withJournalPreview(home, `preview:${command ?? "unknown"}`, invoke));
+            exitCode = preview.result;
+            changes = preview.changes;
+            if (!json) {
+                io.stdout(`Dry run completed: ${changes.length} path change(s) would be made.`);
+                changes.forEach((change) => io.stdout(`${change.before.kind === "missing" ? "create" : change.after.kind === "missing" ? "remove" : "modify"}\t${change.path}`));
+            }
+        }
+        else {
+            exitCode = mutates
+                ? await withHomeLock(home, () => withJournalTransaction(home, `cli:${command ?? "unknown"}`, invoke))
+                : await invoke();
+        }
+        if (json)
+            emitJson(exitCode, changes);
+        return exitCode;
     }
     catch (error) {
         if (error instanceof HarnessBrewError) {
-            io.stderr(error.message);
+            if (json) {
+                diagnostics.push(error.message);
+                emitJson(1, [], "HARNESSBREW_ERROR");
+            }
+            else
+                io.stderr(error.message);
             return 1;
         }
         throw error;