Skip to content

aitools list: emit JSON via --output json#5233

Merged
jamesbroadhead merged 3 commits into
mainfrom
jb/aitools-list-json
May 20, 2026
Merged

aitools list: emit JSON via --output json#5233
jamesbroadhead merged 3 commits into
mainfrom
jb/aitools-list-json

Conversation

@jamesbroadhead
Copy link
Copy Markdown
Contributor

Summary

databricks aitools list learns --output json, emitting a structured document so coding agents and CI can consume the skill/version/installation matrix without scraping the tabwriter text output. Text rendering is unchanged.

Stacked on #4917 (uses --scope and the moved-to-top-level aitools/ package). Base will rebase to main once #4917 merges.

JSON shape

{
  "release": "0.1.0",
  "skills": [
    {
      "name": "databricks-jobs",
      "latest_version": "1.0.0",
      "experimental": false,
      "installed": { "global": "1.0.0", "project": "0.9.0" }
    }
  ],
  "summary": {
    "global":  { "installed": 5, "total": 10 },
    "project": { "installed": 3, "total": 10 }
  }
}
  • installed is keyed by scope; absent key = not installed in that scope; empty map = not installed anywhere.
  • summary only includes scopes that were queried, so --scope=global narrows it to one key.
  • release is the version string without the v prefix.

This is the documented public contract — field names and types should not change without a major version bump.

Why

aitools list is one of the surfaces an agent reaches for first ("what's installed, what's available, what's stale"). Scraping tabwriter columns from stderr is fragile; a stable JSON contract makes the command declarative for non-human callers. Matches the convention used by other CLI commands that already honor --output json (bundle validate, pipelines run, etc.).

Test plan

  • databricks aitools list --output json against a workspace with a mix of installed/uninstalled skills, both scopes — JSON validates against the shape above.
  • databricks aitools list --output json --scope=globalsummary only contains global.
  • databricks aitools list (no --output) — output is byte-for-byte unchanged from main.
  • Unit: TestRenderListJSON, TestRenderListJSONScopeFiltersSummary, TestInstalledStatusFromEntry cover the rendering paths.

This pull request was AI-assisted by Isaac.

@jamesbroadhead jamesbroadhead force-pushed the jbroadhead/aitools-public branch from b3b6d1a to 9df5e93 Compare May 11, 2026 14:52
Base automatically changed from jbroadhead/aitools-public to main May 18, 2026 19:26
@jamesbroadhead jamesbroadhead force-pushed the jb/aitools-list-json branch from c02b45c to c4ef02c Compare May 18, 2026 21:57
@jamesbroadhead jamesbroadhead changed the base branch from main to jb/aitools-interface May 18, 2026 21:57
@jamesbroadhead jamesbroadhead marked this pull request as ready for review May 18, 2026 22:00
@jamesbroadhead
Copy link
Copy Markdown
Contributor Author

👋 @simonfaltum — Claude here on James's behalf.

Rebased onto the new tip of #5234 (which itself was rebased onto current main after #4917 landed) and flipped this out of draft. The diff is now small (3 files, +283/-71) showing only the actual --output json work.

Drift fixes applied during the rebase:

Stacking note: PR base is set to jb/aitools-interface (#5234), not main. Once #5234 merges, GitHub will auto-retarget the base.

Ready for review whenever you've got time.

(comment posted by Claude)

@jamesbroadhead jamesbroadhead force-pushed the jb/aitools-interface branch from 7666312 to 24d5351 Compare May 19, 2026 08:41
@jamesbroadhead jamesbroadhead force-pushed the jb/aitools-list-json branch from c4ef02c to e71f268 Compare May 19, 2026 09:42
denik pushed a commit that referenced this pull request May 20, 2026
## Summary

Promotes the **aitools skills-management surface** out of
`experimental/` so the stable half lives at `databricks aitools …` and
slots in next to the other top-level command groups. The matching
**interface changes** (`--scope` enum, `--project`/`--global`
deprecation, `--agents` auto-detect doc) live in a stacked follow-up:
**#5234**.

This is mostly a move, but it is not move-only — see [Non-move
changes](#non-move-changes) below.

- Source files for `install`, `update`, `uninstall`, `list`, `version`
(and the agents/installer libs they depend on) physically move from
`experimental/aitools/` to `cmd/aitools/` + `libs/aitools/`, matching
the existing `cmd/apps/` + `libs/apps/` layout. OWNERS, Taskfile, and
the pr-checklist skill are updated to match.
- The top-level command is registered at `databricks aitools …`.
- **Keeps the `tools` subtree under `experimental/aitools/`** — `query`,
`discover-schema`, `get-default-warehouse`, `statement …` — because
`tools.go` still says "There are no stability guarantees for these
tools".
- The old paths under `databricks experimental aitools
install/update/uninstall/list/version` and `databricks experimental
aitools skills install/list` keep working as **deprecated
backward-compat aliases** that print a notice pointing at the new path
(via cobra's `Deprecated` field).

The aitools skills-management surface is feature-complete after the 5-PR
series (#4810#4814) that added state tracking, lifecycle commands, and
project scope support. The `tools` subtree is functionally useful but
its shape is still in flux, so promoting only the stable half.

## Non-move changes

In addition to the file moves, this PR:

- Removes the redundant `aitools/README.md` (apps/pipelines don't carry
one); the same info lives in the command's Long description.
- Rewrites the Long description on the new top-level `databricks
aitools` command.
- Adds a deprecation notice to every legacy alias under `databricks
experimental aitools` (Lennart's review ask — they used to forward
silently).
- Refactors how the legacy `experimental aitools skills install [name]`
wrapper is wired: the wrapper now lives in
`cmd/aitools/legacy_skills.go` alongside the install code it wraps, and
the previously-exported test-injection vars (`InstallSkillsForAgentsFn`,
`ListSkillsFn`, `PromptAgentSelection`) are back to unexported. The two
now-empty experimental files (`experimental/aitools/cmd/skills.go` and
`skills_test.go`) are deleted.

## What's not in this PR

These are deliberately separated and reviewed independently:

- **#5234** — `--scope=project|global|both` flag, deprecation of
`--project`/`--global` via `cobra.Deprecated`, `--agents` auto-detect
help text.
- **#5233** (draft) — `--output json` on `databricks aitools list`.

## Command shape after this PR

```
# Stable, top-level
databricks aitools install      # use --skills <name>[,<name>...] for specific skills
databricks aitools update
databricks aitools uninstall
databricks aitools list
databricks aitools version

# Backward-compat aliases (print deprecation notice; point at the new paths)
databricks experimental aitools install/update/uninstall/list/version
databricks experimental aitools skills {list,install}

# Experimental, unchanged path
databricks experimental aitools tools query
databricks experimental aitools tools discover-schema
databricks experimental aitools tools get-default-warehouse
databricks experimental aitools tools statement {submit,get,status,cancel}
```

## Test plan

- [x] `databricks aitools --help` shows
install/update/uninstall/list/version (no `tools`)
- [x] `databricks --help` lists `aitools` in the output
- [x] `databricks experimental aitools install` prints a deprecation
notice and still forwards
- [x] `databricks experimental aitools tools query …` runs as before
- [x] `databricks experimental aitools tools --help` lists
query/discover-schema/get-default-warehouse/statement
- [x] Existing aitools tests pass; the legacy-wrapper tests moved with
the wrapper to `cmd/aitools/legacy_skills_test.go`

This pull request was AI-assisted by Isaac.

---------

Co-authored-by: simon <simon.faltum@databricks.com>
Co-authored-by: simon <4305831+simonfaltum@users.noreply.github.com>
Copy link
Copy Markdown
Member

@simonfaltum simonfaltum left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good after the fixes on this branch.

I also merged the latest stacked base/main, resolved the changelog/list conflicts, restored manifest fallback behavior, and added coverage for preserving scoped text labels while adding JSON output.

@simonfaltum simonfaltum temporarily deployed to test-trigger-is May 20, 2026 14:41 — with GitHub Actions Inactive
@simonfaltum simonfaltum temporarily deployed to test-trigger-is May 20, 2026 14:41 — with GitHub Actions Inactive
Base automatically changed from jb/aitools-interface to main May 20, 2026 15:29
Teaches list to render as a structured {release, skills[...], summary{}}
document when --output json is passed. Text rendering is unchanged.

Stacked-on-#5234 rebased onto main now that #5234 has merged. The branch
state was carrying stale rehashes of the scope-flag work; squashed onto
current main to keep only the JSON-output delta.

Co-authored-by: Isaac
@jamesbroadhead jamesbroadhead added this pull request to the merge queue May 20, 2026
Merged via the queue into main with commit c037584 May 20, 2026
24 checks passed
@jamesbroadhead jamesbroadhead deleted the jb/aitools-list-json branch May 20, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants