diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml new file mode 100644 index 0000000..c965ba9 --- /dev/null +++ b/.github/workflows/techdocs.yml @@ -0,0 +1,126 @@ +name: TechDocs + +# Keeps the Backstage TechDocs corpus in sync with the GitHub docs. +# +# How the sync works end to end: +# 1. catalog-info.yaml registers skill-pool in Backstage; the System carries +# `backstage.io/techdocs-ref: dir:.`, so Backstage builds TechDocs from +# ./mkdocs.yml on its own refresh schedule (builder: local) — no push +# needed from here. +# 2. docs/index.md is generated from README.md by scripts/sync-techdocs.py so +# the GitHub landing page and the TechDocs home never drift. +# 3. This workflow guarantees `main` always holds a buildable, in-sync docs +# tree (PR gate below), and can optionally pre-publish a built site to a +# TechDocs external storage bucket when one is configured. + +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'README.md' + - 'openapi.yaml' + - 'catalog-info.yaml' + - 'scripts/sync-techdocs.py' + - '.github/workflows/techdocs.yml' + pull_request: + branches: [main] + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'README.md' + - 'openapi.yaml' + - 'catalog-info.yaml' + - 'scripts/sync-techdocs.py' + - '.github/workflows/techdocs.yml' + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + # --------------------------------------------------------------------------- + # Validate: README↔index sync + a real mkdocs build. Runs on PRs and main. + # No cloud credentials required. + # --------------------------------------------------------------------------- + build: + name: Build TechDocs + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install TechDocs MkDocs toolchain + run: pip install --disable-pip-version-check mkdocs-techdocs-core + + - name: Verify docs/index.md is in sync with README.md + run: python3 scripts/sync-techdocs.py --check + + - name: Build TechDocs site + run: mkdocs build --site-dir techdocs-site + + - name: Upload built site + uses: actions/upload-artifact@v4 + with: + name: techdocs-site + path: techdocs-site + retention-days: 14 + + # --------------------------------------------------------------------------- + # Publish: only on main, and only when an external TechDocs publisher is + # configured (set repo variable TECHDOCS_PUBLISH=true and the AWS bits below). + # A no-op otherwise — Backstage's local builder already serves from the repo. + # --------------------------------------------------------------------------- + publish: + name: Publish to TechDocs storage + needs: build + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.TECHDOCS_PUBLISH == 'true' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + id-token: write # for AWS OIDC, mirrors the deploy workflow + env: + ENTITY_NAMESPACE: default + ENTITY_KIND: system + ENTITY_NAME: skill-pool + TECHDOCS_S3_BUCKET_NAME: ${{ vars.TECHDOCS_S3_BUCKET_NAME }} + AWS_REGION: ${{ vars.AWS_REGION }} + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install toolchains + run: | + pip install --disable-pip-version-check mkdocs-techdocs-core + npm install -g @techdocs/cli + + - name: Configure AWS credentials (OIDC) + uses: aws-actions/configure-aws-credentials@v4 + with: + role-to-assume: ${{ vars.TECHDOCS_PUBLISH_ROLE_ARN }} + aws-region: ${{ env.AWS_REGION }} + + - name: Generate + publish TechDocs + run: | + techdocs-cli generate --no-docker --verbose + techdocs-cli publish \ + --publisher-type awsS3 \ + --storage-name "$TECHDOCS_S3_BUCKET_NAME" \ + --entity "$ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME" diff --git a/README.md b/README.md index 51fc882..df55e2f 100644 --- a/README.md +++ b/README.md @@ -186,6 +186,19 @@ Full subcommand list: `init`, `login`, `ensure`, `add` / `add-agent` / `add-comm - **[`docs/lifecycle.md`](docs/lifecycle.md)** — embeddings, dependency resolution, decay - **[`docs/tenancy.md`](docs/tenancy.md)** · **[`docs/sso.md`](docs/sso.md)** · **[`docs/scim.md`](docs/scim.md)** · **[`docs/theming.md`](docs/theming.md)** · **[`docs/enterprise.md`](docs/enterprise.md)** +### Backstage + +This repo is annotated for [Backstage](https://backstage.io/): the Software +Catalog descriptor lives in [`catalog-info.yaml`](catalog-info.yaml) (a +`skill-pool` System with the server/web/cli Components, the REST `API`, and the +db/object-store/cache Resources), and the full `docs/` tree is published as +[TechDocs](https://backstage.io/docs/features/techdocs/) via +[`mkdocs.yml`](mkdocs.yml). The TechDocs home is generated from this README by +[`scripts/sync-techdocs.py`](scripts/sync-techdocs.py), and the +[`TechDocs` workflow](.github/workflows/techdocs.yml) keeps the two in sync on +every push. See [`docs/backstage.md`](docs/backstage.md) for the catalog model +and sync details. + ## Bundled demo content This portal ships ready to seed with 120+ curated skills, agents, and commands from [borghei/Claude-Skills](https://github.com/borghei/Claude-Skills) (License: MIT + Commons Clause — attribution preserved in each item's frontmatter). The set spans `code-reviewer`, `design-auditor`, `api-design-reviewer`, `rag-architect`, `ci-cd-pipeline-builder`, `terraform-patterns`, and dozens more. See the [Bundled Skills page](./docs/wiki/Bundled-Skills.md) for the full list. diff --git a/catalog-info.yaml b/catalog-info.yaml index c31638c..1ec6d78 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -1,17 +1,162 @@ -# Auto-generated by olafkfreund/backstage catalog-onboard workflow. -# Hand-edit at will — the bot only fires for repos that lack this -# file entirely. +# Backstage Software Catalog descriptor for skill-pool. +# Registered as a Location pointing at this file on the default branch; the +# Backstage GitHub provider re-reads it on a schedule. TechDocs are built from +# ./mkdocs.yml (see the System entity's backstage.io/techdocs-ref annotation). apiVersion: backstage.io/v1alpha1 -kind: Component +kind: System metadata: - name: skill_pool - description: "Self-hosted Claude Code skill/agent/command registry for teams — CLI, web UI, auto-bootstrap, retrospective capture." + name: skill-pool + title: skill-pool + description: Self-hosted, multi-tenant Claude Code skill/agent/command/plugin registry for teams. annotations: + github.com/project-slug: olafkfreund/skill_pool backstage.io/techdocs-ref: dir:. + backstage.io/source-location: url:https://github.com/olafkfreund/skill_pool/tree/main/ + links: + - url: https://github.com/olafkfreund/skill_pool + title: Repository + icon: github + - url: https://github.com/olafkfreund/skill_pool/tree/main/docs/wiki + title: Wiki + icon: docs + tags: + - rust + - claude-code + - registry + - multi-tenant +spec: + owner: group:default/olafkfreund + domain: public + +--- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: skill-pool-server + title: skill-pool server + description: Rust + Axum API server — REST surface, MCP JSON-RPC transport, plugin git endpoints, and the retrospective-capture daemon. + annotations: github.com/project-slug: olafkfreund/skill_pool - tags: [] + backstage.io/techdocs-ref: dir:. + backstage.io/source-location: url:https://github.com/olafkfreund/skill_pool/tree/main/server/ + tags: + - rust + - axum + - sqlx + - tokio spec: type: service lifecycle: production - owner: olafkfreund - domain: public + owner: group:default/olafkfreund + system: skill-pool + providesApis: + - skill-pool-api + dependsOn: + - resource:default/skill-pool-db + - resource:default/skill-pool-object-store + - resource:default/skill-pool-cache + +--- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: skill-pool-web + title: skill-pool web portal + description: SvelteKit 2 + Svelte 5 web portal — catalog browse, Monaco editor, version history, drafts inbox, per-tenant theming, RBAC. + annotations: + github.com/project-slug: olafkfreund/skill_pool + backstage.io/source-location: url:https://github.com/olafkfreund/skill_pool/tree/main/web/ + tags: + - sveltekit + - svelte + - tailwindcss + - typescript +spec: + type: website + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool + consumesApis: + - skill-pool-api + +--- +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: skill-pool-cli + title: skill-pool CLI + description: Rust CLI (clap + reqwest) — detect/bootstrap, publish/install, capture, doctor, direnv + Claude Code hook installation. + annotations: + github.com/project-slug: olafkfreund/skill_pool + backstage.io/source-location: url:https://github.com/olafkfreund/skill_pool/tree/main/cli/ + tags: + - rust + - clap + - cli +spec: + type: library + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool + consumesApis: + - skill-pool-api + +--- +apiVersion: backstage.io/v1alpha1 +kind: API +metadata: + name: skill-pool-api + title: skill-pool REST API + description: Tenant-scoped REST + MCP + plugin-marketplace/git surface served by the skill-pool server. + annotations: + github.com/project-slug: olafkfreund/skill_pool + backstage.io/source-location: url:https://github.com/olafkfreund/skill_pool/tree/main/openapi.yaml + tags: + - rest + - openapi +spec: + type: openapi + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool + definition: + $text: ./openapi.yaml + +--- +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + name: skill-pool-db + title: skill-pool database + description: Postgres 17 + pgvector 0.7 — catalog rows, tenancy, audit log, usage events, and description embeddings. +spec: + type: database + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool + +--- +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + name: skill-pool-object-store + title: skill-pool object storage + description: opendal-backed bundle storage — S3 / GCS / Azure Blob / MinIO / filesystem from one DSN-style config. +spec: + type: object-storage + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool + +--- +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + name: skill-pool-cache + title: skill-pool queue + cache + description: Optional Redis — async job queue with DLQ and read-through auth/marketplace cache. Fail-open; server stays up if Redis is down. +spec: + type: cache + lifecycle: production + owner: group:default/olafkfreund + system: skill-pool diff --git a/docs/backstage.md b/docs/backstage.md new file mode 100644 index 0000000..3d26ebb --- /dev/null +++ b/docs/backstage.md @@ -0,0 +1,66 @@ +# Backstage integration + +skill-pool is registered in the [Backstage](https://backstage.io/) Software +Catalog and ships its documentation as [TechDocs](https://backstage.io/docs/features/techdocs/) +built straight from this repository. This page describes the catalog model and +how the docs stay in sync. + +## Catalog model + +The catalog descriptor lives at [`catalog-info.yaml`](https://github.com/olafkfreund/skill_pool/blob/main/catalog-info.yaml) +in the repo root. It declares one `System` and the entities that make it up: + +| Entity | Kind | Notes | +| --- | --- | --- | +| `skill-pool` | System | Umbrella; owns the TechDocs (`backstage.io/techdocs-ref: dir:.`), domain `public`. | +| `skill-pool-server` | Component (`service`) | Rust + Axum API; **provides** `skill-pool-api`; **depends on** the db, object store, and cache. | +| `skill-pool-web` | Component (`website`) | SvelteKit portal; **consumes** `skill-pool-api`. | +| `skill-pool-cli` | Component (`library`) | Rust CLI; **consumes** `skill-pool-api`. | +| `skill-pool-api` | API (`openapi`) | Definition tracked in [`openapi.yaml`](https://github.com/olafkfreund/skill_pool/blob/main/openapi.yaml). | +| `skill-pool-db` | Resource (`database`) | Postgres 17 + pgvector. | +| `skill-pool-object-store` | Resource (`object-storage`) | opendal bundle storage (S3/GCS/Azure/MinIO/fs). | +| `skill-pool-cache` | Resource (`cache`) | Optional Redis queue + cache. | + +All entities are owned by `group:default/olafkfreund` and grouped under the +`skill-pool` system, so Backstage renders the full provides/consumes/depends-on +graph on the system page. + +## How docs stay in sync + +There are three moving parts, and together they make the sync hands-off: + +1. **Registration + local builder.** Once `catalog-info.yaml` is registered as a + Location, Backstage re-reads it on a schedule. Because the System carries + `backstage.io/techdocs-ref: dir:.`, the TechDocs *local builder* rebuilds the + site from [`mkdocs.yml`](https://github.com/olafkfreund/skill_pool/blob/main/mkdocs.yml) + on `main` — no push from CI required. + +2. **README → TechDocs home.** `README.md` is the single source of truth for the + project overview. [`scripts/sync-techdocs.py`](https://github.com/olafkfreund/skill_pool/blob/main/scripts/sync-techdocs.py) + regenerates `docs/index.md` from it, rewriting links for the TechDocs context + (repo-relative `docs/...` links are stripped; links to code outside `docs/` + become absolute GitHub URLs). Run it after editing the README: + + ```bash + python3 scripts/sync-techdocs.py # regenerate docs/index.md + python3 scripts/sync-techdocs.py --check # CI gate: fail if drifted + ``` + +3. **CI gate + optional publish.** The + [`TechDocs` workflow](https://github.com/olafkfreund/skill_pool/blob/main/.github/workflows/techdocs.yml) + runs on every PR and on `main`: it checks the README↔index sync and does a + real `mkdocs build`, so broken docs never reach `main`. An optional + `publish` job pushes a pre-built site to an external TechDocs bucket (AWS S3) + when the repo variable `TECHDOCS_PUBLISH=true` and the publisher settings are + present; otherwise Backstage's local builder serves the docs directly. + +## Building the docs locally + +```bash +python3 -m venv .venv && . .venv/bin/activate +pip install mkdocs-techdocs-core +mkdocs serve # live preview on http://127.0.0.1:8000 +mkdocs build # one-shot build into ./site +``` + +This mirrors exactly what the Backstage TechDocs builder runs. diff --git a/docs/index.md b/docs/index.md index 0c2d80b..4abc45e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,4 @@ - + # skill-pool @@ -12,7 +11,7 @@ [![Postgres 17 + pgvector](https://img.shields.io/badge/db-Postgres%2017%20%2B%20pgvector-336791?logo=postgresql&logoColor=white)](https://www.postgresql.org/) [![Claude Code compatible](https://img.shields.io/badge/Claude%20Code-compatible-7c5cff)](https://docs.claude.com/en/docs/claude-code) -![skill-pool hero](docs/images/hero.webp) +![skill-pool hero](images/hero.webp) ## What is this? @@ -24,25 +23,25 @@ The trick: **retrospective capture**. When Claude finishes a non-trivial fix in ## Demo -