@mertyalti/agentia-change

oclif plugin that adds change commands to the agentia host. Analyzes Salesforce metadata change impact (depth 1 by default, --depth up to 10 for indirect dependents) using @mertyalti/agentia-graph. Does not depend on @mertyalti/agentia-graph-cli.

Independent personal project by mert yaltı. Not developed, endorsed, supported or warranted by Copado. Copado and Agentia are trademarks of Copado.

• @mertyalti/agentia-change
• Usage
• Commands
• License

Usage

$ agentia plugins install @mertyalti/agentia-change
$ agentia change --help

Requires Node.js 18+ and Agentia CLI (@copado/agentia-cli) >= 1.0.0. Proprietary: see LICENSE.md.

Install

$ agentia plugins install @mertyalti/agentia-change
$ agentia change impact --help

Sibling checkout (local development)

$ cd agentia-change
$ npm install
$ npm run build:graph   # only if ../agentia-graph is not built yet
$ npm run build
$ agentia plugins link .
$ agentia change --help

Packing never builds: npm run build compiles this plugin only, and prepack is a guard that fails fast if dist/ or oclif.manifest.json is missing or stale. Build the sibling ../agentia-graph explicitly with npm run build:graph when you need it (the typecheck step and check still do). To pack, run npm run pack:ci: npm run build, then npm run manifest (oclif manifest through scripts/oclif.mjs, which sets OCLIF_SKIP_NEW_VERSION_CHECK=true for every oclif call, including docs:readme, and sends oclif output to stderr), then npm pack --ignore-scripts. Add -- --json for clean JSON on stdout, or -- --dry-run to list files. Run it from a clean clone or a gate pair, never from a primary or a shared worktree. Never run oclif (or these scripts) with DEBUG=* or DEBUG=update-check in CI: the oclif update check's debug output prints the npm auth header. npm run build (so npm test, check and lint too) first runs scripts/ensure-graph.mjs as prebuild, which runs build:graph only when ../agentia-graph/dist is missing; pack:ci builds with --ignore-scripts, so packing never builds the sibling (on a clone whose graph is not built, pack:ci fails instead). Use npm run --silent pack:ci -- --json for JSON on stdout: without --silent, npm prints its > script banners there. pack:ci leaves oclif.manifest.json in the working tree on purpose (it is gitignored, and a later plain npm pack reuses it); the prepack guard rejects it if it is missing, malformed, for another version, or its command IDs differ from dist/commands.

Without linking, the local oclif entry is:

$ node bin/run.js change --help

This package depends on the published @mertyalti/[email protected] from npm. If you are working against a sibling ../agentia-graph checkout, you may temporarily point the dependency at file:../agentia-graph during local unloadable work, but switch it back to 0.1.1 before committing or publishing.

Pre-GO golden check (impact changes)

Before GO on any change that can affect impact output, run every [golden-slow] test (the golden-repo analysisDigest lock, the golden-repo e2e rows and the UC-12 golden-repo MCP row) against a local clone of a private golden repository (for example a fictional acme-orders Salesforce repo with classes such as OrderService):

AGENTIA_GOLDEN_REPO=/path/to/acme-orders npm run test:golden

Each cold pinned impact takes about 34–45 min and the set runs more than one. npm run check never runs these tests, even with AGENTIA_GOLDEN_REPO exported. See scripts/README.md.

Quickstart

From a Salesforce metadata git repo:

$ agentia change impact --base main --head HEAD
$ agentia change impact --working-tree
$ agentia change impact --component ApexClass:AccountService --json
$ agentia change impact --base main --head HEAD --depth 3 --format markup --output impact.md
$ agentia change show IMP-<id>
$ agentia change impact --base main --head HEAD --format markup --output impact.md
$ agentia change impact --base main --head HEAD --format html --output impact.html
$ agentia change explain IMP-<id>
$ agentia change explain IMP-<id> --subject ApexClass:AccountCaller
$ agentia change explain IMP-<id> --ai
$ agentia change explain IMP-<id> --ai-preview

Copado AI summary (C7): explain --ai adds a natural-language summary from Copado AI, obtained only through the running agentia host (agentia ai agent ask, knowledge agent; sign in with agentia auth set --ai …; host >=1.0.0-0, i.e. 1.0.0 or a 1.0.0 prerelease such as 1.0.0-beta.2). The plugin holds no AI keys and calls no AI service itself. Only a minimised projection of the explanation is sent (no source, file contents, absolute paths, commit SHAs or credentials); it is passed to the host on the command line, so other local users can see it in ps. --ai-preview prints exactly what would be sent; it starts no AI host and makes no network call (a report-id lookup may still run git rev-parse locally). AI failures exit 1 (CHANGE_AI_UNAVAILABLE / CHANGE_AI_FAILED) with no partial output; plain explain without --ai keeps working. See docs/commands.md.

MCP and skills

$ agentia change setup mcp
$ agentia change setup skills

Cursor entry name: agentia-change → agentia change mcp start with AGENTIA_PROJECT_ROOT=${workspaceFolder}.

MCP tools: change_impact, change_show, change_explain (prefer MCP; fall back to CLI --json).

Flags and exit codes (C8): --help groups flags as MODE / REPORT / ANALYSIS / OUTPUT / PROJECT (plus AI on explain, C7). Only change check exits 2 (policy fail) or 3 (indeterminate); every other failure, including a mistyped flag or value, exits 1 with CHANGE_CONFIGURATION_INVALID (breaking in 0.x: parse errors used to exit 2). Relative --output paths resolve against the current directory, like agentia graph --out (breaking in 0.x for --project-root / AGENTIA_PROJECT_ROOT users running from another directory). explain --component is deprecated in favour of --subject. See the flag matrix.

Depth (C5)

--depth accepts an integer from 1 to 10 (default 1; the MCP depth field has the same range). Out-of-range integers exit 1 with CHANGE_DEPTH_UNSUPPORTED (--depth must be an integer between 1 and 10 (got N).). Non-integers are flag parse errors and exit 1 with CHANGE_CONFIGURATION_INVALID (C8; previously exit 2). Note that '010' is accepted as 10.

• Depth 1 reports keep the 0.1.0 shape and digest (change-impact-0.1.0, rule [email protected]).
• Depth 2-10 follows indirect references hop by hop: changed component → file that references it → components that file defines → … The depth-1 findings are exactly those of the depth-1 report; findings at depth 2 and deeper are added after them, use rule [email protected] and carry minimumDepth, all root associations and a canonical evidence path (plus 3 alternative paths, up to 4 per side). Before and proposed snapshots are traversed separately, so a path never mixes old and new edges. The producer engine is change-impact-0.2.0 (depth > 1 only).
• Fixed safety budgets apply only at depth > 1: 10,000 distinct finding subjects per report (depth-1 subjects count but are never dropped), 250,000 inspected reference edges per snapshot, 3 alternative paths (up to 4 per side). Hitting a budget adds EDGE_BUDGET_REACHED or FINDINGS_CAP_REACHED to coverage.gaps with the frontier and marks the report partial; change check with analysis_status: complete then fails (exit 2). DEPTH_LIMIT_REACHED (unvisited dependents remain past the requested depth) and PATH_DETAIL_TRUNCATED (more paths exist than are listed) are informational coverage notes and do not make the report partial. A depth ≥ 2 finding may carry coverageLimited: true (with the causing gap id(s) in coverageGapIds) when a capped side never confirmed it. This is deliberately conservative: a side that hit its cap may still reach the subject at a depth between where it stopped and the requested depth, so every depth ≥ 2 finding it never reached is uncertain.
• Hub-flagged files are skipped at every depth, as at depth 1.
• Markup and HTML show the minimum depth, canonical path, alternative-path count and coverage-limited state label for depth ≥ 2 findings. Through the CLI, impact --format text and show default text or --format text (including show --section findings) print the minimum depth, the state label (with the coverage-limited suffix) and the canonical path on each finding line, [<severity>] <subject> — <explanation> (<state>, depth N) · path: <root> → … → <subject>, but not the alternative-path count. --format json and --json carry the raw minimumDepth, paths, coverageLimited and coverageGapIds fields. All ids are escaped (text via sanitizeForTerminal).

Development checks

npm run check is the ship bar: it builds ../agentia-graph and the plugin once, then runs format:check, lint, typecheck, test:unit, test:integration, test:usecases:fixtures and verify:core. It is fixture-only (it removes AGENTIA_GOLDEN_REPO and AGENTIA_HOST_SMOKE), needs no network, and keeps every temp dir inside a work dir that is removed afterwards. See scripts/README.md for each script and the env-gated rows.

Use cases on the test/fixtures/sf-repo fixture:

• UC-06..10 and UC-13 (mode exclusivity) in test/e2e/golden-path.test.ts
• UC-12 (MCP smoke) in test/contract/mcp-smoke.test.ts
• C5 depth > 1 impact in test/integration/depth-impact.test.ts on the test/fixtures/sf-repo-depth fixture

Golden-repo rows run only when AGENTIA_GOLDEN_REPO is set; the UC-06 host agentia row runs only when AGENTIA_HOST_SMOKE is set.

Not the same as graph / docs

| Surface | Package | Role | | -------------------- | ------------------------------ | -------------------------- | | agentia change * | this plugin | Change impact reports | | agentia graph * | @mertyalti/agentia-graph-cli | Working-tree graph inspect | | agentia docs graph | @mertyalti/agentia-docs | Docs-branch graph |

Product docs

Shipped under docs/: overview, commands, architecture, working-tree, security.

Commands

• agentia change impact
• agentia change show
• agentia change explain
• agentia change mcp start
• agentia change setup mcp
• agentia change setup skills

agentia change impact

Analyze Salesforce metadata change impact (mutually exclusive modes).

Each report is saved in the project at <project root>/.agentia/agentia-change/impact-reports/IMP-….json (printed on the Saved line and in --json result.path). The first write creates .agentia/.gitignore ignoring only /agentia-change/ and /.gitignore (committed .agentia config such as impact-policy.yaml stays visible to git), so the store stays out of git and the working tree stays clean; an existing .agentia/.gitignore and your own .gitignore are never edited. --output writes an extra copy where you ask. Graph builds stay in the OS cache.

USAGE
  $ agentia change impact [--base <value>] [--head <value>] [--working-tree]
    [--component <value>] [--at <value>] [--depth <value>] [--format text|json|markup|html]
    [--output <value>] [--project-root <value>] [--json]

agentia change show

Show a saved report by id or --path.

USAGE
  $ agentia change show [REPORTID] [--path <value>] [--project-root <value>]
    [--section summary|changes|findings|tests|docs|coverage|evidence]
    [--format text|json|markup|html|markdown] [--output <value>] [--json]

--format markup|html renders the full report; combining it with --section exits 1. markdown aliases markup. html requires --output. --json is mutually exclusive with --format.

agentia change explain

Holistic structured explanation of a saved report (C6). Default is the whole report; --subject keeps single-subject mode (--component is a deprecated alias, removed next minor).

USAGE
  $ agentia change explain [REPORTID] [--path <value>] [--subject <value>]
    [--component <value>] [--top <value>] [--format text|json|markup|html|markdown]
    [--output <value>] [--json] [--project-root <value>] [--ai] [--ai-preview]
    [--question <value>] [--ai-timeout <value>]

--top defaults to 10 (1–100). html requires --output. --json is mutually exclusive with --format. --ai / --ai-preview / --question / --ai-timeout: Copado AI summary via the host (C7, see above).

agentia change mcp start

Start the plugin-local stdio MCP server.

agentia change setup mcp

Configure Cursor MCP entry agentia-change.

agentia change setup skills

Install the Agentia Change skill into .agents / .cursor / .claude.

License

Proprietary — see LICENSE.md. Copyright (c) mert yaltı.