katalyst-plugin-bard 0.1.1a1__tar.gz

katalyst_plugin_bard-0.1.1a1/.gitignore

@@ -0,0 +1,123 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+# Not a Python build directory: Bard's SPA keeps shared helpers (utils.ts, download.ts) in
+# src/lib, and ignoring it left a fresh clone unable to build or test the SPA.
+!plugins/bard/web/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy / pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+*.local
+
+# Browser/Playwright state files
+browser-state-*.json
+
+# Agent harness scratch (run exhaust, never the design bundle)
+.opencode/sessions/
+.opencode/analysis/
+.opencode/package-lock.json
+
+# Build artifacts
+site/
+stack-tests/cucumber-report/
+stack-tests/test-results/
+
+# Generated artifacts (rebuild with `just generate-schemas`)
+taxonomy/src/katalyst_taxonomy/engine/generated/
+.worktrees/
+.plan-74-75-76-77.md
+.HANDOFF-scaffolding-wiring.md
+.HANDOFF-2-cicd-migration.md
+.HANDOFF-action-execution-fixes.md
+.HANDOFF-bdd-coverage.md
+.HANDOFF-*.md
+docs/superpowers/
+
+# Node dependencies — installed, never committed
+node_modules/

katalyst_plugin_bard-0.1.1a1/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to Katalyst Bard are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added (host contract 0.1.7)
+
+- **Refresh** in the shell header re-reads the schema, kinds, taxonomy and backends,
+  keeping the view, its route, the sidebar and open forms; disabled and spinning while
+  the read is in flight. The stopgap for changes made outside Bard (#269).
+  `useHost().refresh()` and `useHost().refreshing` offer the same to contributions
+  (optional). Additive: earlier contributions still load.
+
+### Added (host contract 0.1.2)
+
+- `useHost().taxonomy.previewCreate(request)` (the create dry run; not a write, no
+  re-read) and `unrelate({source, rel_type, target})` (`DELETE /api/taxonomy/relationships`,
+  a gated write); `CreateNodeRequest.scaffold_variant`; `CreatedNode.notes`; types
+  `CreatePreview`, `PlannedFile`. Both methods are optional on `TaxonomyApi`. Additive:
+  `^0.1.0`/`^0.1.1` contributions still load.
+
+### Changed (Settings follow-ups)
+
+- **"Saved to …" stays after a save that is not in effect.** A refresh never unmounts the
+  view on screen (hidden while the host re-reads or a read fails), and a node read that
+  fails while the server's state is still being re-read is not reported as an error.
+- **API access**: no "from the next start" — the API applies a change at once; origins the
+  API was started with (`--cors`) are listed apart.
+- **A plugin's config is checked by the API** against the plugin's schema as you type, in
+  its panel; Apply waits for it.
+
+### Fixed
+
+- **`--api-port N` is honoured or the start fails naming it**; it never fell back to
+  another port, though the help said so. A failed API start is an error, not a traceback.
+- **`KATALYST_CONFIG_WRITE=1 kata tax bard serve` gets an API that writes**: a running one
+  that does not is restarted with writes, as the desktop app does, and Bard says so.
+- **An `--api-url` API that refuses configuration writes is said to**: by the launcher
+  (desktop, or serve with `KATALYST_CONFIG_WRITE=1`) and by Settings, which is read-only
+  with the reason — `/api/settings/capability` also asks the API's `/status`
+  `config_writes` (`ConfigGateway.configWrites`).
+- Help and errors name `just build` / `just desktop-build` in `plugins/bard` (there is no
+  `just bard-build`); a stale CORS note in `settings-capability.ts` is corrected.
+- The sdist no longer lists the removed `docs` directory; the slot-docs test skips when
+  the site's docs are absent.
+
+### Added
+
+- **Settings covers the whole configuration file.** Backends of every type the API serves
+  (`GET /config/fields`), each rendered from its fields, credentials write-only; a
+  plugin's `priority` and `config` (typed from its `configSchema`, else YAML); a
+  **General** card for `metadata`, `outputFormat` and `workspace`; a sourced profile's
+  `profile` and `token_env`; an **API access** card for the CORS allowlist
+  (`/api/access/cors`). The draft is checked by the API (`POST /api/config/validate`)
+  and its problems are shown in the form; a refused save lists each reason.
+
+### Removed
+
+- The hard-coded per-type `FIELDS` map, `BACKEND_TYPES`/`READ_ONLY_TYPES` and the
+  per-type backend setting checks in `validate.ts`: the API owns them.
+
+### Changed
+
+- **Every request to the taxonomy API carries its token.** The launcher passes
+  `KATALYST_API_TOKEN` (from the API's state record, or this environment for `--api-url`);
+  the server and desktop shell read the record on each request
+  (`server/adapters/api-token.ts`) and fall back to `KATALYST_API_TOKEN`. Plugin routes
+  (`/api/ext/*`) carry it too. The write-token reader and `WRITES_DISABLED_UPSTREAM` are
+  gone: an API without writes answers its own `403`.
+- **A contribution's views are listed under its package's own sidebar heading**, never in
+  Explore (which holds Bard's own Wings, Kinds and Nodes; Settings stays in the footer).
+  The heading is the display name the contributing distribution declares once, under the
+  new `katalyst_bard.package` entry point (`display_name = "pkg.module:NAME"`, a string);
+  every contribution it declares merges under it. A view's `section` (or the manifest's
+  new `spec.section`) is a subsection inside it. A contribution whose package declares no
+  display name, or a main view with no section, is refused and named (by
+  `build-contribution`, the server and the loader) rather than falling into Explore.
+  `BARD_CONTRIBUTIONS` entries carry `package`.
+
+### Added
+
+- **`kata tax bard serve|desktop --no-contributions`** (or `BARD_NO_CONTRIBUTIONS=1`, which
+  the server and desktop shell also read): a plain Bard, with none of the installed
+  packages' views. A launcher that loads them sets the variable empty, so a product's
+  launcher always loads them.
+- **Sourced profiles in Settings.** A profile read from elsewhere (`source:` in the
+  config) is marked read-only in the profile list, and its page shows the source, the
+  profile in it, the pin and last fetch, its pinned backends and the clones they read, with
+  "Check source" (is it ahead?) and "Sync now" (gated like every write) instead of any
+  editing. Setup will not connect a backend into one. Bard's server forwards
+  `GET /api/config/sources` and `POST /api/config/sources/sync`.
+- **Runtime-loaded contributions.** A package ships a built contribution and declares it
+  under the `katalyst_bard.contributions` entry point; the launcher passes the installed ones
+  to the server, which lists them at `GET /api/contributions` and serves their modules (web
+  and desktop), and the SPA loads and registers them. A contribution is a plain ES module
+  importing React and `@katalyst/bard-host` by name; the page's import map resolves those to
+  the host's own instances, so any bundler that leaves them external works
+  (`kata tax bard build-contribution` is esbuild set up that way). An incompatible
+  `hostRange`, a missing file or a failing module is skipped and named, never fatal. See
+  `docs/plugins/bard/contributions.md` at the repository root; `web/vitest.contribution.config.ts` runs a contribution's tests
+  against the host.
+- **Sidebar sections**: a view's `section` lists it under its own heading.
+- **Contributions can write nodes and read a plugin's routes** (host contract 0.1.1):
+  `useHost().taxonomy` creates, updates and relates nodes through the taxonomy's validated
+  routes and calls the routes installed taxonomy plugins add under `/ext/<plugin>/`;
+  `useHost().writes` says whether this deployment may write, and why not. Bard's server
+  forwards `POST/PATCH /api/taxonomy/nodes…` and `POST /api/taxonomy/relationships` as gated
+  writes, and `GET`/`POST /api/ext/*` as reads without the write token.
+- **Release workflow** (`.github/workflows/release-bard.yml`, tags `bard-vX.Y.Z`), so bard
+  can be published to PyPI and depended on: katalyst-forge now lists it, making
+  `kata tax bard serve` part of a forge install.
+- **Dependency floors match the runtime it needs**: `katalyst-taxonomy>=5,<6`.
+
+- **Extracted into its own repository** from `katalyst-taxonomy/plugins/bard`, preserving history. Bard is consumed as an installable plugin via the `katalyst_taxonomy.plugins` and `katalyst_taxonomy.cli` entry points rather than vendored into the taxonomy workspace.
+- **Schema-driven rendering core.** Node kinds are rendered from their own `NodeDefinition` — display labels, field order, types, and constraints all come from the taxonomy's schema registry, so a kind bard has never seen renders correctly. `src/schema/NodeDetail.test.tsx` proves this against a kind fabricated in the test file.
+- **Field renderer registry** resolving `kind.field` → field name → `allowed_values` → `ref_target_kind` → `field_type` → JSON. `allowed_values` and `ref_target_kind` deliberately outrank `field_type`, since a `field_type: "string"` field carrying either is semantically an enum or a link. An unknown `field_type` degrades to JSON rather than crashing.
+- **View registry** where a view declares the wings or kinds it applies to, so one build adapts to any deployment without conditionals in the shell.
+- **Express server** serving the SPA and `/api` from one process on one origin — required by Databricks Apps, which permits only one service to bind the assigned port and does not allow customising CORS on its reverse proxy.
+- **`kata tax bard serve`** — Python launcher that ensures a taxonomy API is reachable, starts the Node server, and verifies it is actually serving before reporting success.
+- **Container and Databricks App support.** `Dockerfile` and `app.yaml`. `loadConfig()` reads `DATABRICKS_APP_PORT` and defaults `HOST` to `0.0.0.0` when present.
+- **Outdated-API detection.** `HttpSchemaGateway` translates a `/schema` 404 into an explicit "this API predates the schema API" message rather than surfacing a bare status code.
+- **CI bundle-self-containment check** that runs the built server from a directory with no `node_modules` anywhere above it, plus a Docker image smoke test asserting `/health` is 200 while `/api/ready` is 503 with no upstream.
+
+### Removed
+
+- **`kata tax bard compose`** and `web/src/generated/composed.ts`: build-time composition is
+  replaced by runtime loading.
+
+### Notes
+
+- The server is bundled by esbuild into a single self-contained `dist/server/index.cjs`. An unbundled emit cannot work: `web_dist/` ships inside the wheel with no `node_modules` above it, and Node resolves bare imports by walking up from the importing file.
+- Bard holds no taxonomy data and has no data access of its own — it speaks HTTP to the taxonomy API and nothing else. Which backend that API uses (filesystem, Databricks, Neo4j, Postgres) is the API's concern.

katalyst_plugin_bard-0.1.1a1/Dockerfile

@@ -0,0 +1,48 @@
+# Bard — schema-driven taxonomy UI.
+#
+# Pure Node: bard reads everything over HTTP from the taxonomy API, so this
+# image needs no Python, no taxonomy checkout, and no `kata` binary. Point it at
+# an API with TAXONOMY_API_URL and it works against whichever backend that API
+# is configured for (filesystem, Databricks, Neo4j, Postgres).
+
+FROM node:22-alpine AS build
+WORKDIR /app
+# All workspace manifests must be present before `npm ci`, or npm cannot build
+# the workspace tree. Contribution directories are copied whole rather than
+# glob-selecting their package.json files: Docker's COPY flattens globs, which
+# would put every package.json at the same path.
+COPY package.json package-lock.json ./
+COPY web/package.json ./web/
+COPY wings ./wings/
+COPY plugins-ui ./plugins-ui/
+RUN npm ci
+COPY web/ ./web/
+RUN npm run build
+
+FROM node:22-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+# The server is bundled into a single self-contained CJS file, so the runtime
+# stage needs no package.json and no node_modules at all.
+COPY --from=build /app/web/dist ./dist
+
+# Run unprivileged. The node image ships a `node` user.
+USER node
+
+# 0.0.0.0 is required in any container; binding loopback makes the app
+# unreachable through a reverse proxy.
+ENV HOST=0.0.0.0 \
+    PORT=5273 \
+    WEB_DIST_DIR=/app/dist/web \
+    TAXONOMY_API_URL=http://127.0.0.1:8000
+
+EXPOSE 5273
+
+# /health deliberately does not check the upstream API: a liveness probe that
+# fails when a dependency is down restarts the container for a problem
+# restarting cannot fix. Use /api/ready for readiness.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||5273)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["node", "dist/server/index.cjs"]

katalyst_plugin_bard-0.1.1a1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: katalyst-plugin-bard
+Version: 0.1.1a1
+Summary: Bard — a schema-driven web UI framework for the Katalyst taxonomy
+Project-URL: Repository, https://github.com/esimplicityinc/katalyst-bard
+Author: eSimplicity
+License: Proprietary
+Keywords: architecture,katalyst,plugin,taxonomy,ui
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: katalyst-taxonomy-mcp<5,>=4
+Requires-Dist: katalyst-taxonomy<6,>=5
+Description-Content-Type: text/markdown
+
+# Bard
+
+A schema-driven web and desktop UI for the Katalyst taxonomy: `kata tax bard serve` and
+`kata tax bard desktop`. It renders every kind the connected taxonomy has from the kind's
+own definition, edits your configuration in Settings, and loads the views other installed
+packages contribute.
+
+Documentation is on the docs site:
+
+- [Bard](../../docs/plugins/bard.md): running it, the API and its token, configuration
+  writes, Settings and product sections.
+- [Writing a contribution](../../docs/plugins/bard/contributions.md): adding a view to Bard
+  from your own package.
+- [Composition architecture](../../docs/plugins/bard/composition.md): the host contract,
+  runtime loading, flags, slots and the desktop shell.
+
+## Install
+
+Bard is discovered through the `katalyst_taxonomy.plugins` and `katalyst_taxonomy.cli`
+entry points, so installing it beside `kata` is enough. It needs Node.js 20 or newer.
+
+```bash
+pip install katalyst-plugin-bard
+kata tax bard serve      # in the browser
+kata tax bard desktop    # in a desktop window, settings editable
+```
+
+## From a checkout
+
+```bash
+just build               # npm install + build + stage assets in src/katalyst_plugin_bard/web_dist/
+just desktop-build       # also bundle the desktop shell
+just serve               # == kata tax bard serve
+just dev                 # Express on 5273, Vite on 5173 proxying to it
+just check               # everything CI runs (lint, types, pytest, vitest)
+```
+
+## Without the plugin
+
+Bard's server is plain Node and reads everything over HTTP, so it runs without Python, a
+taxonomy checkout or `kata`:
+
+```bash
+just docker
+docker run -p 5273:5273 -e TAXONOMY_API_URL=https://taxonomy.example.com \
+  -e KATALYST_API_TOKEN=<its token> katalyst-bard:dev
+```
+
+`app.yaml` is a Databricks Apps manifest. The server reads `DATABRICKS_APP_PORT` and binds
+`0.0.0.0` when it is set; set `TAXONOMY_API_URL` to an API reachable from the workspace and
+`KATALYST_API_TOKEN` to its token.
+
+`GET /health` is liveness and does not touch the API; `GET /api/ready` reports whether the
+API is reachable. Bard has no authentication of its own: do not expose it without putting
+authentication in front of it.
+
+## Layout
+
+```
+src/katalyst_plugin_bard/   the plugin: `kata tax bard`, the launcher, contribution discovery
+  web_dist/                 built SPA, the bundled server (index.cjs) and desktop shell, in the wheel
+web/server/                 Express server and the transport-agnostic API handler
+web/src/                    React: the schema-driven renderer, views, Settings, host contract
+apps/desktop/               Electron shell over the same API handler
+schemas/                    bard.manifest.schema.json, the contribution manifest schema
+xspec/, layer/              the plugin's black-box contract and fixtures
+```
+
+The server ships as one esbuild bundle because `web_dist/` sits in the wheel with no
+`node_modules` above it.

katalyst_plugin_bard-0.1.1a1/README.md

@@ -0,0 +1,70 @@
+# Bard
+
+A schema-driven web and desktop UI for the Katalyst taxonomy: `kata tax bard serve` and
+`kata tax bard desktop`. It renders every kind the connected taxonomy has from the kind's
+own definition, edits your configuration in Settings, and loads the views other installed
+packages contribute.
+
+Documentation is on the docs site:
+
+- [Bard](../../docs/plugins/bard.md): running it, the API and its token, configuration
+  writes, Settings and product sections.
+- [Writing a contribution](../../docs/plugins/bard/contributions.md): adding a view to Bard
+  from your own package.
+- [Composition architecture](../../docs/plugins/bard/composition.md): the host contract,
+  runtime loading, flags, slots and the desktop shell.
+
+## Install
+
+Bard is discovered through the `katalyst_taxonomy.plugins` and `katalyst_taxonomy.cli`
+entry points, so installing it beside `kata` is enough. It needs Node.js 20 or newer.
+
+```bash
+pip install katalyst-plugin-bard
+kata tax bard serve      # in the browser
+kata tax bard desktop    # in a desktop window, settings editable
+```
+
+## From a checkout
+
+```bash
+just build               # npm install + build + stage assets in src/katalyst_plugin_bard/web_dist/
+just desktop-build       # also bundle the desktop shell
+just serve               # == kata tax bard serve
+just dev                 # Express on 5273, Vite on 5173 proxying to it
+just check               # everything CI runs (lint, types, pytest, vitest)
+```
+
+## Without the plugin
+
+Bard's server is plain Node and reads everything over HTTP, so it runs without Python, a
+taxonomy checkout or `kata`:
+
+```bash
+just docker
+docker run -p 5273:5273 -e TAXONOMY_API_URL=https://taxonomy.example.com \
+  -e KATALYST_API_TOKEN=<its token> katalyst-bard:dev
+```
+
+`app.yaml` is a Databricks Apps manifest. The server reads `DATABRICKS_APP_PORT` and binds
+`0.0.0.0` when it is set; set `TAXONOMY_API_URL` to an API reachable from the workspace and
+`KATALYST_API_TOKEN` to its token.
+
+`GET /health` is liveness and does not touch the API; `GET /api/ready` reports whether the
+API is reachable. Bard has no authentication of its own: do not expose it without putting
+authentication in front of it.
+
+## Layout
+
+```
+src/katalyst_plugin_bard/   the plugin: `kata tax bard`, the launcher, contribution discovery
+  web_dist/                 built SPA, the bundled server (index.cjs) and desktop shell, in the wheel
+web/server/                 Express server and the transport-agnostic API handler
+web/src/                    React: the schema-driven renderer, views, Settings, host contract
+apps/desktop/               Electron shell over the same API handler
+schemas/                    bard.manifest.schema.json, the contribution manifest schema
+xspec/, layer/              the plugin's black-box contract and fixtures
+```
+
+The server ships as one esbuild bundle because `web_dist/` sits in the wheel with no
+`node_modules` above it.

katalyst_plugin_bard-0.1.1a1/app.yaml

@@ -0,0 +1,18 @@
+# Databricks Apps runtime configuration.
+#
+# The platform assigns a port via DATABRICKS_APP_PORT and only one service may
+# bind it. Bard serves the SPA and its API from a single Express process, which
+# also sidesteps the platform's non-customisable CORS headers.
+#
+# loadConfig() reads DATABRICKS_APP_PORT directly and defaults HOST to 0.0.0.0
+# when it is present, so no port wiring is needed here.
+command:
+  - node
+  - dist/server/index.cjs
+env:
+  - name: WEB_DIST_DIR
+    value: "./dist/web"
+  # Point this at a taxonomy API reachable from the workspace. Bard holds no
+  # taxonomy data of its own.
+  - name: TAXONOMY_API_URL
+    value: "http://127.0.0.1:8000"

katalyst_plugin_bard-0.1.1a1/apps/desktop/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@katalyst/bard-desktop",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Bard desktop shell — Electron over the same API handler as the web build",
+  "main": "dist/main.cjs",
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "esbuild src/main.ts --bundle --platform=node --target=node20 --format=cjs --outfile=dist/main.cjs --external:electron --sourcemap",
+    "start": "electron .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@katalyst/bard": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "electron": "33.4.11",
+    "esbuild": "^0.24.2",
+    "typescript": "^5.7.2"
+  }
+}