diff --git a/.github/workflows/catalog-listing.yml b/.github/workflows/catalog-listing.yml new file mode 100644 index 0000000..daa1be3 --- /dev/null +++ b/.github/workflows/catalog-listing.yml @@ -0,0 +1,59 @@ +name: Publish Internal Tool Builder catalog listing + +# The catalog listing (catalog/listing.yaml + catalog/screenshots) is +# presentation only: a change never implies a release. On main it replaces the +# listing of the entry the catalog already records and requests a publication. + +on: + push: + branches: [main] + paths: + - catalog/listing.yaml + - catalog/screenshots/** + - hack/catalog-listing.ts + - .github/workflows/catalog-listing.yml + workflow_dispatch: + +permissions: + contents: read + +# Shares the writer with the release publisher: one read/merge/PUT at a time. +concurrency: + group: tool-builder-catalog-publish + cancel-in-progress: false + +jobs: + listing: + if: github.repository == 'appthrust/tool-builder' + runs-on: ubuntu-24.04 + timeout-minutes: 20 + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 + with: + persist-credentials: false + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 + with: + bun-version: 1.4.1 + - name: Validate the listing + run: bun hack/publish-entry.ts validate-listing + - name: Submit the listing + id: catalog + env: + CLOUD_API_URL: ${{ vars.CLOUD_API_URL || 'https://api.appthrust.com' }} + CLOUD_CATALOG_ADMIN_TOKEN: ${{ secrets.CLOUD_CATALOG_ADMIN_TOKEN }} + run: bun hack/publish-entry.ts listing + - name: Mint the Cloud workflow dispatch token + if: steps.catalog.outputs.state == 'snapshot' + id: cloud-token + uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2 + with: + app-id: ${{ secrets.APPTHRUST_GITHUB_ACTIONS_APP_ID }} + private-key: ${{ secrets.APPTHRUST_GITHUB_ACTIONS_APP_PRIVATE_KEY }} + owner: appthrust + repositories: cloud + - name: Dispatch Cloud catalog publication + if: steps.catalog.outputs.state == 'snapshot' + env: + GH_TOKEN: ${{ steps.cloud-token.outputs.token }} + SNAPSHOT_ID: ${{ steps.catalog.outputs.snapshot_id }} + run: gh api -X POST repos/appthrust/cloud/dispatches -f event_type=catalog-publish -f "client_payload[snapshot_id]=$SNAPSHOT_ID" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e4f8478..6de0d15 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,4 +53,4 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 with: bun-version: 1.4.1 - - run: bun test hack/publish-entry.test.ts + - run: bun test hack diff --git a/catalog/listing.yaml b/catalog/listing.yaml new file mode 100644 index 0000000..29b3055 --- /dev/null +++ b/catalog/listing.yaml @@ -0,0 +1,113 @@ +locales: + en: + title: Internal Tool Builder + tagline: Build tables, forms and dashboards on your Project's data and publish them as tools your team can use. + overview: | + Internal Tool Builder is for teams that need small internal tools such as an order lookup, a refund form or a stock dashboard, built directly on the databases and apps in their Project. Editors place tables, detail panels, forms, charts and counters on a canvas and connect them to queries. Everyone else opens the published tool at its own address and uses it without seeing the queries behind it. + + Editors write SQL in the query editor. Placeholders take their values from search boxes, selects or the selected table row, and filters can narrow the rows without changing the SQL. A write query becomes an action on a table: the person using the tool picks a row, fills in a form and confirms before anything changes. Every action run is recorded with who ran it, the release and the result, and the history is kept for 90 days. + + Edits stay in a draft until they are published. The preview runs the draft against real data while members keep seeing the live release, and any earlier release can be restored. Tools are shared with Directory groups with Use or Edit access, and a single action can be limited to chosen groups, for example letting only support leads and finance issue refunds. Team administrators can open and edit every tool. + + Data sources are the Project's PostgreSQL databases and installed apps such as Directory, connected by a Team administrator. Database queries run with the access of the connection, so connect only what tools should reach. Queries to an installed app run as the person using the tool and return only what that person may see. Tools, drafts and run history are stored in the app's own database inside the Project, and people sign in with their organisation account. + ja: + title: 社内ツールビルダー + tagline: Project のデータを使うテーブル、フォーム、ダッシュボードを作り、チームで使えるツールとして公開できます。 + overview: | + 社内ツールビルダーは、注文の検索、返金の受付、在庫の確認といった業務用の小さなツールを、Project にあるデータベースやアプリの上に直接作るためのアプリです。編集者がテーブル、詳細パネル、フォーム、グラフ、数値をキャンバスに並べてクエリとつなぎます。ほかのメンバーは公開されたツールを専用のアドレスで開き、裏のクエリを意識せずに使えます。 + + クエリはクエリエディターで SQL として書きます。プレースホルダーには検索欄や選択肢、テーブルで選んだ行の値が入り、絞り込みを追加すれば SQL を書き換えずに行を絞れます。書き込みクエリはテーブルのアクションになり、利用者は行を選んでフォームに入力し、確認してから実行します。アクションの実行は、実行者、リリース、結果とともに記録され、90 日間保存されます。 + + 編集内容は公開するまで下書きに残ります。プレビューでは下書きを実際のデータで動かせますが、メンバーには公開中のリリースが表示されたままです。以前のリリースはいつでも復元できます。ツールはディレクトリのグループに「利用」または「編集」の権限で共有し、返金のような操作はサポートリーダーと経理だけ、というようにアクション単位で実行できるグループを絞れます。Team の管理者はすべてのツールを開いて編集できます。 + + データソースには、Project の PostgreSQL データベースと、ディレクトリなどのインストール済みアプリを Team の管理者が接続します。データベースへのクエリは接続の権限で実行されるため、ツールに見せてよいものだけを接続します。インストール済みアプリへのクエリはツールを使う人の権限で実行され、その人が見られるものだけが返ります。ツール、下書き、実行履歴は Project 内にあるこのアプリ専用のデータベースに保存され、サインインには組織のアカウントを使います。 +highlights: + - screenshot: editor + locales: + en: + title: Lay out tools on a canvas + body: Drag tables, detail panels, forms, charts, counters, search boxes and tabs onto a grid. The canvas shows live data and draws how values flow between components and queries. + ja: + title: キャンバスで画面を組み立て + body: テーブル、詳細、フォーム、グラフ、数値、検索、タブなどをグリッドに配置します。キャンバスには実際のデータが表示され、コンポーネントとクエリの間で値がどう流れるかも線で確認できます。 + - screenshot: table + locales: + en: + title: Select a row, see the details + body: A search box and a status filter feed the table, and selecting a row loads the full record into the detail panel beside it. + ja: + title: 行を選ぶと詳細を表示 + body: 検索欄と状態の選択でテーブルを絞り込み、行を選ぶと隣の詳細パネルにそのレコードの内容が表示されます。 + - screenshot: form + locales: + en: + title: Confirm before writing + body: Write queries run as actions on a row. They take their input from a form and can ask for confirmation before anything changes. + ja: + title: 確認してから書き込み + body: 書き込みクエリは行に対するアクションとして実行します。フォームの入力を受け取り、変更の前に確認ダイアログを表示できます。 + - screenshot: dashboard + locales: + en: + title: Dashboards from the same parts + body: Put bar, line and area charts and counters next to tables, each fed by its own query, so several data sources share one screen. + ja: + title: 同じ部品でダッシュボードも + body: 棒グラフ、折れ線グラフ、面グラフ、数値をテーブルと並べます。部品ごとにクエリを選べるので、複数のデータソースの内容をひとつの画面にまとめられます。 + - screenshot: queries + locales: + en: + title: SQL with bound parameters + body: Placeholders take their values from the components on the screen, filters narrow the rows without editing SQL, and a run shows the rows and how long the query took. + ja: + title: パラメーター付きの SQL + body: プレースホルダーには画面の入力値が入り、絞り込みを使えば SQL を書き換えずに行を絞れます。実行すると結果の行と所要時間が表示されます。 + - screenshot: sharing + locales: + en: + title: Share with Directory groups + body: Give each group Use or Edit access, effective at once without a new release, and limit actions such as refunds to the groups you choose. + ja: + title: ディレクトリのグループに共有 + body: グループごとに「利用」か「編集」の権限を付けます。変更はリリースなしですぐに反映され、返金のような操作は選んだグループだけが実行できるようにできます。 +screenshots: + - name: editor + file: editor.webp + alt: + en: The editor (Japanese UI) of an order desk tool. Component palette on the left; the canvas shows a search box, status filter, open-orders counter, the selected orders table, a detail panel and a refund form with data-flow arrows; table column settings on the right. + ja: 「受注デスク」の編集画面。左にコンポーネント一覧、中央のキャンバスに検索欄、注文テーブル、詳細パネル、返金フォームとデータの流れを示す矢印、右にテーブルの列設定があります。 + - name: table + file: table.webp + alt: + en: A published order desk tool (Japanese UI). In the orders table with order number, customer, total, status badge and order time, order SO-10464 is selected and its payment method and other details appear in the panel on the right. + ja: 公開中の「受注デスク」ツール。注文番号、顧客、合計、状態、注文日時の列があるテーブルで注文 SO-10464 が選ばれ、右のパネルに支払い方法などの詳細が表示されています。 + - name: form + file: form.webp + alt: + en: A confirmation dialog for refunding order SO-10465 (Japanese UI), with a refund amount of 3200, a reason saying one mug was damaged in delivery, and Cancel and Refund buttons. + ja: 注文 SO-10465 に対する「返金を実行します」の確認ダイアログ。返金額 3200 と理由「マグカップ 1 点が配送中に破損していたため」が入力され、「キャンセル」と「返金する」のボタンがあります。 + - name: dashboard + file: dashboard.webp + alt: + en: An orders and stock dashboard tool (Japanese UI) with a bar chart of stock per product, an open-orders counter showing 7, a bar chart of items per open order, and a table of open orders. + ja: 「受注・在庫ダッシュボード」ツール。商品別の在庫数の棒グラフ、未処理の注文数 7、未処理の注文ごとの点数の棒グラフ、未処理の注文の一覧テーブルが並んでいます。 + - name: queries + file: queries.webp + alt: + en: The query editor with the connected data sources and the tool's queries on the left, the SQL of search_orders with search and statuses placeholders in the middle, its first result rows below, and the parameter settings on the right. + ja: クエリエディター。左に接続中のデータソースとツールのクエリ一覧、中央に search と statuses のプレースホルダーを含む search_orders の SQL とその実行結果、右にパラメーターの設定が表示されています。 + - name: sharing + file: sharing.webp + alt: + en: The sharing page of the order desk tool (Japanese UI). Customer Support, Support Leads and Finance have Use access, IT Platform has Edit access, and the refund action is limited to Support Leads and Finance. + ja: 「受注デスク」の共有画面。カスタマーサポート、サポートリーダー、経理に「利用」、IT プラットフォームに「編集」の権限があり、「返金する」アクションはサポートリーダーと経理だけに限定されています。 + - name: tools + file: tools.webp + alt: + en: The tool list (Japanese UI) with four tools the signed-in person can edit, each with its address and status, such as Live v14 for the order desk and Not published for a customer lookup tool. + ja: ツールの一覧。編集できるツールが 4 件並び、それぞれにアドレスと状態が表示されています。「受注デスク」は「公開中 v14」、「顧客検索」は「未公開」です。 + - name: data-sources + file: data-sources.webp + alt: + en: The data sources page (Japanese UI) listing two databases, a storefront app and the Directory app, all marked Ready, with buttons to add an installed app or connect a database. + ja: データソースの画面。データベース 2 件、ストアのアプリ、「社員名簿」として追加したディレクトリが並び、すべて「利用可能」です。「インストール済みアプリを追加」と「データベースを接続」のボタンがあります。 diff --git a/catalog/screenshots/dashboard.webp b/catalog/screenshots/dashboard.webp new file mode 100644 index 0000000..7991c7c Binary files /dev/null and b/catalog/screenshots/dashboard.webp differ diff --git a/catalog/screenshots/data-sources.webp b/catalog/screenshots/data-sources.webp new file mode 100644 index 0000000..dbcff78 Binary files /dev/null and b/catalog/screenshots/data-sources.webp differ diff --git a/catalog/screenshots/editor.webp b/catalog/screenshots/editor.webp new file mode 100644 index 0000000..ced8e5d Binary files /dev/null and b/catalog/screenshots/editor.webp differ diff --git a/catalog/screenshots/form.webp b/catalog/screenshots/form.webp new file mode 100644 index 0000000..5df9362 Binary files /dev/null and b/catalog/screenshots/form.webp differ diff --git a/catalog/screenshots/queries.webp b/catalog/screenshots/queries.webp new file mode 100644 index 0000000..6eb4c14 Binary files /dev/null and b/catalog/screenshots/queries.webp differ diff --git a/catalog/screenshots/sharing.webp b/catalog/screenshots/sharing.webp new file mode 100644 index 0000000..3f9b15e Binary files /dev/null and b/catalog/screenshots/sharing.webp differ diff --git a/catalog/screenshots/table.webp b/catalog/screenshots/table.webp new file mode 100644 index 0000000..fc08ed1 Binary files /dev/null and b/catalog/screenshots/table.webp differ diff --git a/catalog/screenshots/tools.webp b/catalog/screenshots/tools.webp new file mode 100644 index 0000000..b15c9fd Binary files /dev/null and b/catalog/screenshots/tools.webp differ diff --git a/cmd/server/internal/api/api_test.go b/cmd/server/internal/api/api_test.go index 241dd6a..15f2052 100644 --- a/cmd/server/internal/api/api_test.go +++ b/cmd/server/internal/api/api_test.go @@ -59,14 +59,12 @@ func newTestAPI(t *testing.T, db *store.Store, eng Engine, issuer *testutil.OIDC } w.Header().Set("Content-Type", "application/json") switch r.URL.Path { - case "/api/v1/projects/pj-test": - _ = json.NewEncoder(w).Encode(map[string]any{"teamSlug": "test"}) - case "/api/v1/teams": + case "/api/v1/projects/pj-test/access": role := "Viewer" if admin { role = "Admin" } - _ = json.NewEncoder(w).Encode(map[string]any{"items": []any{map[string]any{"id": "team", "slug": "test", "role": role}}}) + _ = json.NewEncoder(w).Encode(map[string]any{"member": true, "role": role}) case "/api/v1/projects/pj-test/app-installations/tool-builder": _, _ = w.Write([]byte(`{"id":"tool-builder","stackId":"adopted-tool-stack","links":[{"definitionId":"knowledge","state":"Absent"},{"definitionId":"builder-console","state":"Installing"}]}`)) case "/api/v1/projects/pj-test/components/orders-db": diff --git a/cmd/server/server_test.go b/cmd/server/server_test.go index 3bf9371..37e34ea 100644 --- a/cmd/server/server_test.go +++ b/cmd/server/server_test.go @@ -214,10 +214,8 @@ func TestServedOpenAPIEqualsCommittedContract(t *testing.T) { platform := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { require.Equal(t, bearer, r.Header.Get("Authorization")) switch r.URL.Path { - case "/api/v1/projects/pj-test": - _, _ = w.Write([]byte(`{"teamSlug":"test"}`)) - case "/api/v1/teams": - _, _ = w.Write([]byte(`{"items":[{"id":"team","slug":"test","role":"Viewer"}]}`)) + case "/api/v1/projects/pj-test/access": + _, _ = w.Write([]byte(`{"member":true,"role":"Viewer"}`)) default: t.Errorf("unexpected platform route %s", r.URL.Path) w.WriteHeader(http.StatusNotFound) diff --git a/go.mod b/go.mod index 8985c4c..5600078 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,7 @@ module github.com/appthrust/tool-builder go 1.26.0 require ( - github.com/appthrust/appserver-go v0.2.0 + github.com/appthrust/appserver-go v0.3.0 github.com/lib/pq v1.12.3 github.com/oklog/ulid/v2 v2.1.1 github.com/stretchr/testify v1.11.1 diff --git a/go.sum b/go.sum index 855dd9f..3faaba0 100644 --- a/go.sum +++ b/go.sum @@ -1,5 +1,5 @@ -github.com/appthrust/appserver-go v0.2.0 h1:TLb4pzbTXy3uMER5vQAXdzeeOTLxuNYEUXXvTAVzWm8= -github.com/appthrust/appserver-go v0.2.0/go.mod h1:0KSf9RQZ6OxBcE0lxYzzjKF37nfwbKps3wXUGlE0oFo= +github.com/appthrust/appserver-go v0.3.0 h1:zxOz0hkspZSXjLq3KWGDLkZIz42Jag6wqRujZ8lTru0= +github.com/appthrust/appserver-go v0.3.0/go.mod h1:0KSf9RQZ6OxBcE0lxYzzjKF37nfwbKps3wXUGlE0oFo= github.com/coreos/go-oidc/v3 v3.20.0 h1:EtE0WIBHk03N+DqGkY4+UONzzZHk7amKt6IyNd7OsZE= github.com/coreos/go-oidc/v3 v3.20.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4= github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= diff --git a/hack/catalog-listing.test.ts b/hack/catalog-listing.test.ts new file mode 100644 index 0000000..2a235da --- /dev/null +++ b/hack/catalog-listing.test.ts @@ -0,0 +1,130 @@ +import { describe, expect, test } from 'bun:test' +import { createHash } from 'node:crypto' +import { mkdtemp, mkdir, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { imageDimensions, loadListing, uploadMedia, validateListing, type Listing } from './catalog-listing' +import { renderEntry, renderListingUpdate, type CatalogEntry } from './publish-entry' + +/** Minimal valid PNG: 8-byte signature + IHDR chunk; dimensions only, no pixel data. */ +function png(width: number, height: number): Uint8Array { + const bytes = new Uint8Array(33) + bytes.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0) + const view = new DataView(bytes.buffer) + view.setUint32(8, 13) + bytes.set([0x49, 0x48, 0x44, 0x52], 12) + view.setUint32(16, width) + view.setUint32(20, height) + return bytes +} + +function webpVP8X(width: number, height: number): Uint8Array { + const bytes = new Uint8Array(30) + bytes.set([0x52, 0x49, 0x46, 0x46], 0) + bytes.set([0x57, 0x45, 0x42, 0x50], 8) + bytes.set([0x56, 0x50, 0x38, 0x58], 12) + const w = width - 1, h = height - 1 + bytes.set([w & 0xff, (w >> 8) & 0xff, (w >> 16) & 0xff], 24) + bytes.set([h & 0xff, (h >> 8) & 0xff, (h >> 16) & 0xff], 27) + return bytes +} + +const listing: Listing = { + locales: { + en: { tagline: 'People, groups and profiles.', overview: 'Who is who.\n\nSearch and browse.' }, + ja: { tagline: 'この組織のメンバー、グループ、プロフィール。', overview: '誰が誰か。' }, + }, + highlights: [{ locales: { en: { title: 'Search' }, ja: { title: '検索' } }, screenshot: 'people' }], + screenshots: [{ + name: 'people', digest: `sha256:${'a'.repeat(64)}`, mediaType: 'image/png', size: 33, width: 1280, height: 800, + alt: { en: 'People list', ja: 'メンバー一覧' }, + }], +} + +describe('imageDimensions', () => { + test('reads PNG IHDR and WebP VP8X', () => { + expect(imageDimensions(png(1280, 800))).toEqual({ mediaType: 'image/png', width: 1280, height: 800 }) + expect(imageDimensions(webpVP8X(1440, 900))).toEqual({ mediaType: 'image/webp', width: 1440, height: 900 }) + expect(() => imageDimensions(new Uint8Array(40))).toThrow('PNG or WebP') + }) +}) + +describe('validateListing', () => { + test('accepts the sample and enforces the contract', () => { + expect(() => validateListing(listing)).not.toThrow() + expect(() => validateListing({ locales: { ja: { tagline: 'x' } } })).toThrow('requires the "en" locale') + expect(() => validateListing({ ...listing, highlights: [{ locales: { en: { title: 'x' } }, screenshot: 'missing' }] })) + .toThrow('unknown screenshot "missing"') + expect(() => validateListing({ ...listing, screenshots: [{ ...listing.screenshots![0], size: 600_000 }] })).toThrow('bytes') + expect(() => validateListing({ ...listing, screenshots: [{ ...listing.screenshots![0], alt: { ja: 'x' } }] })).toThrow('requires the "en" locale') + expect(() => validateListing({ locales: { en: { tagline: 'x'.repeat(201) } } })).toThrow('exceeds 200') + }) +}) + +describe('loadListing', () => { + test('resolves screenshot files to digests, sizes and dimensions', async () => { + const dir = await mkdtemp(join(tmpdir(), 'listing-')) + await mkdir(join(dir, 'screenshots')) + const image = png(1200, 750) + await writeFile(join(dir, 'screenshots', 'people.png'), image) + await writeFile(join(dir, 'listing.yaml'), [ + 'locales:', ' en: { tagline: People, groups and profiles. }', ' ja: { tagline: メンバー一覧 }', + 'highlights:', ' - screenshot: people', ' locales: { en: { title: Search }, ja: { title: 検索 } }', + 'screenshots:', ' - name: people', ' file: people.png', ' alt: { en: People list, ja: メンバー一覧 }', + ].join('\n')) + const { listing: loaded, media } = await loadListing(pathToFileURL(`${dir}/`)) + const digest = `sha256:${createHash('sha256').update(image).digest('hex')}` + expect(media).toHaveLength(1) + expect(media[0].bytes).toEqual(image) + expect(loaded.screenshots).toEqual([{ name: 'people', digest, mediaType: 'image/png', size: 33, width: 1200, height: 750, alt: { en: 'People list', ja: 'メンバー一覧' } }]) + expect(loaded.highlights?.[0].screenshot).toBe('people') + }) + + test('rejects paths escaping catalog/screenshots', async () => { + const dir = await mkdtemp(join(tmpdir(), 'listing-')) + await writeFile(join(dir, 'listing.yaml'), 'locales: { en: { tagline: x } }\nscreenshots: [{ name: a, file: ../x.png, alt: { en: a } }]\n') + await expect(loadListing(pathToFileURL(`${dir}/`))).rejects.toThrow('relative path') + }) +}) + +describe('uploadMedia', () => { + test('PUTs each blob by hex digest and checks the stored descriptor', async () => { + const image = png(10, 10) + const digest = `sha256:${createHash('sha256').update(image).digest('hex')}` + const calls: Array<{ url: string; type: string }> = [] + const fetcher = async (url: string, init: RequestInit): Promise => { + calls.push({ url, type: (init.headers as Record)['content-type'] }) + return Response.json({ digest, mediaType: 'image/png', size: 33 }) + } + await uploadMedia([{ ...listing.screenshots![0], digest, bytes: image }], 'https://api.example', 'token', fetcher) + expect(calls).toEqual([{ url: `https://api.example/api/v1/catalog/media/${digest.slice(7)}`, type: 'image/png' }]) + const mismatch = async (): Promise => Response.json({ digest, mediaType: 'image/png', size: 1 }) + await expect(uploadMedia([{ ...listing.screenshots![0], digest, bytes: image }], 'https://api.example', 'token', mismatch)) + .rejects.toThrow('does not match') + }) +}) + +describe('listing in entries', () => { + const template = [ + 'apiVersion: appthrust.io/v1alpha1', 'kind: ApplicationStackDefinition', 'metadata: { name: tool-builder }', + 'spec:', ' display: { title: Directory, description: People., category: collaborate, iconRef: { name: tool-builder } }', + ' versions: []', ' updatePolicy: { default: pinned, allowed: [pinned, follow] }', + ].join('\n') + const digest = `sha256:${'b'.repeat(64)}` + + test('renderEntry carries the authored listing and otherwise preserves the stored one', () => { + const first = renderEntry(template, '0.2.0', digest, undefined, listing) + expect(first.listing).toEqual(listing) + const next = renderEntry(template, '0.2.1', `sha256:${'c'.repeat(64)}`, first) + expect(next.listing).toEqual(listing) + expect(renderEntry(template, '0.2.0', digest).listing).toBeUndefined() + }) + + test('renderListingUpdate replaces only the listing', () => { + const current: CatalogEntry = { ...renderEntry(template, '0.2.0', digest), publishedAt: '2026-11-01T00:00:00Z' } + const updated = renderListingUpdate(current, listing) + expect(updated).toEqual({ ...current, listing }) + expect(() => renderListingUpdate({ ...current, slug: 'other' }, listing)).toThrow('slug tool-builder') + }) +}) diff --git a/hack/catalog-listing.ts b/hack/catalog-listing.ts new file mode 100644 index 0000000..f615dda --- /dev/null +++ b/hack/catalog-listing.ts @@ -0,0 +1,202 @@ +// Catalog listing: the publisher-authored presentation of this app (localized +// copy, highlights, digest-pinned screenshots). Authored in catalog/listing.yaml +// with screenshot files under catalog/screenshots/, uploaded to the Cloud +// catalog media store, and submitted inside the catalog entry. The platform +// projects it onto ApplicationStackDefinition.spec.display and the Dashboard +// renders it on the Marketplace card and detail page. +// +// Bounds mirror the platform contract (pkg/appcatalog.ValidateListing): +// locales ≤ 16 with "en" required; tagline ≤ 200, title ≤ 100, overview ≤ 4000, +// notes ≤ 2000 per version (≤ 32 versions); highlights ≤ 6 (title ≤ 80, +// body ≤ 400); screenshots ≤ 8, each ≤ 512 KiB image/webp or image/png with +// alt ≤ 300 per locale. +import { createHash } from 'node:crypto' +import { readFile } from 'node:fs/promises' +import { YAML } from 'bun' + +export const FALLBACK_LOCALE = 'en' +export const MAX_MEDIA_SIZE = 512 * 1024 + +export interface ListingLocale { + title?: string + tagline: string + overview?: string + notes?: Record +} + +export interface ListingHighlight { + locales: Record + screenshot?: string +} + +export interface ListingMedia { + name: string + digest: string + mediaType: 'image/webp' | 'image/png' + size: number + width: number + height: number + alt: Record +} + +export interface Listing { + locales: Record + highlights?: ListingHighlight[] + screenshots?: ListingMedia[] +} + +/** catalog/listing.yaml: screenshots name a file instead of a digest. */ +interface ListingSource { + locales: Record + highlights?: ListingHighlight[] + screenshots?: Array<{ name: string; file: string; alt: Record }> +} + +export interface MediaBlob extends ListingMedia { + bytes: Uint8Array +} + +const localeTag = /^[a-z]{2,3}$/ +const dnsLabel = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/ +const versionName = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/ + +// Limits are UTF-8 bytes, as the Cloud store and the CRD measure them. +function bound(value: string | undefined, max: number, what: string): void { + if (value !== undefined && Buffer.byteLength(value) > max) throw new Error(`${what} exceeds ${max} UTF-8 bytes`) +} + +function localizedText(text: Record | undefined, max: number, what: string): void { + if (!text || typeof text !== 'object') throw new Error(`${what} must map locales to text`) + if (!(FALLBACK_LOCALE in text)) throw new Error(`${what} requires the "${FALLBACK_LOCALE}" locale`) + if (Object.keys(text).length > 16) throw new Error(`${what} has more than 16 locales`) + for (const [tag, value] of Object.entries(text)) { + if (!localeTag.test(tag)) throw new Error(`${what} locale "${tag}" must be a BCP 47 primary tag`) + if (!value || Buffer.byteLength(value) > max) throw new Error(`${what} locale "${tag}" must be 1-${max} UTF-8 bytes`) + } +} + +export function validateListing(listing: Listing): void { + if (!listing.locales || typeof listing.locales !== 'object') throw new Error('listing.locales is required') + if (!(FALLBACK_LOCALE in listing.locales)) throw new Error(`listing requires the "${FALLBACK_LOCALE}" locale`) + if (Object.keys(listing.locales).length > 16) throw new Error('listing has more than 16 locales') + for (const [tag, locale] of Object.entries(listing.locales)) { + if (!localeTag.test(tag)) throw new Error(`listing locale "${tag}" must be a BCP 47 primary tag`) + if (typeof locale.tagline !== 'string' || !locale.tagline) throw new Error(`listing locale "${tag}" requires a tagline`) + bound(locale.title, 100, `locale ${tag} title`) + bound(locale.tagline, 200, `locale ${tag} tagline`) + bound(locale.overview, 4000, `locale ${tag} overview`) + const notes = locale.notes ?? {} + if (Object.keys(notes).length > 32) throw new Error(`locale ${tag} has more than 32 version notes`) + for (const [version, text] of Object.entries(notes)) { + if (!versionName.test(version)) throw new Error(`locale ${tag} notes version "${version}" is invalid`) + bound(text, 2000, `locale ${tag} notes for ${version}`) + } + } + const screenshots = listing.screenshots ?? [] + if (screenshots.length > 8) throw new Error('listing has more than 8 screenshots') + const names = new Set() + for (const media of screenshots) { + if (!dnsLabel.test(media.name) || Buffer.byteLength(media.name) > 63 || names.has(media.name)) { + throw new Error(`screenshot name "${media.name}" is invalid or duplicated`) + } + names.add(media.name) + if (!/^sha256:[a-f0-9]{64}$/.test(media.digest)) throw new Error(`screenshot ${media.name} must pin a sha256 digest`) + if (media.mediaType !== 'image/webp' && media.mediaType !== 'image/png') { + throw new Error(`screenshot ${media.name} has unsupported media type ${media.mediaType}`) + } + if (!(media.size > 0 && media.size <= MAX_MEDIA_SIZE)) throw new Error(`screenshot ${media.name} must be 1-${MAX_MEDIA_SIZE} bytes`) + if (!(media.width > 0 && media.height > 0)) throw new Error(`screenshot ${media.name} has invalid dimensions`) + localizedText(media.alt, 300, `screenshot ${media.name} alt`) + } + const highlights = listing.highlights ?? [] + if (highlights.length > 6) throw new Error('listing has more than 6 highlights') + highlights.forEach((highlight, index) => { + if (!highlight.locales || !(FALLBACK_LOCALE in highlight.locales)) throw new Error(`highlight ${index} requires the "${FALLBACK_LOCALE}" locale`) + if (Object.keys(highlight.locales).length > 16) throw new Error(`highlight ${index} has more than 16 locales`) + for (const [tag, locale] of Object.entries(highlight.locales)) { + if (!localeTag.test(tag) || !locale.title || Buffer.byteLength(locale.title) > 80 || Buffer.byteLength(locale.body ?? '') > 400) { + throw new Error(`highlight ${index} locale "${tag}" is invalid`) + } + } + if (highlight.screenshot !== undefined && !names.has(highlight.screenshot)) { + throw new Error(`highlight ${index} references unknown screenshot "${highlight.screenshot}"`) + } + }) +} + +/** Image dimensions from the PNG IHDR or WebP VP8/VP8L/VP8X header. */ +export function imageDimensions(bytes: Uint8Array): { mediaType: ListingMedia['mediaType']; width: number; height: number } { + const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) + if (bytes.length >= 24 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) { + return { mediaType: 'image/png', width: view.getUint32(16), height: view.getUint32(20) } + } + if (bytes.length >= 30 && String.fromCharCode(...bytes.subarray(0, 4)) === 'RIFF' && String.fromCharCode(...bytes.subarray(8, 12)) === 'WEBP') { + const chunk = String.fromCharCode(...bytes.subarray(12, 16)) + if (chunk === 'VP8X') { + const width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) + const height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) + return { mediaType: 'image/webp', width, height } + } + if (chunk === 'VP8L') { + const b0 = bytes[21], b1 = bytes[22], b2 = bytes[23], b3 = bytes[24] + return { mediaType: 'image/webp', width: 1 + (((b1 & 0x3f) << 8) | b0), height: 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6)) } + } + if (chunk === 'VP8 ') { + return { mediaType: 'image/webp', width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff } + } + } + throw new Error('screenshot must be a PNG or WebP image') +} + +/** Reads catalog/listing.yaml and its screenshot files; returns the listing with digests and the blobs to upload. */ +export async function loadListing(catalogDir: URL): Promise<{ listing: Listing; media: MediaBlob[] }> { + const source = YAML.parse(await readFile(new URL('listing.yaml', catalogDir), 'utf8')) as ListingSource + const media: MediaBlob[] = [] + for (const shot of source.screenshots ?? []) { + if (typeof shot.file !== 'string' || shot.file.includes('..') || shot.file.startsWith('/')) { + throw new Error(`screenshot ${shot.name} file must be a relative path under catalog/screenshots`) + } + const bytes = new Uint8Array(await readFile(new URL(`screenshots/${shot.file}`, catalogDir))) + const { mediaType, width, height } = imageDimensions(bytes) + media.push({ + name: shot.name, + digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`, + mediaType, + size: bytes.byteLength, + width, + height, + alt: shot.alt, + bytes, + }) + } + const listing: Listing = { + locales: source.locales, + ...(source.highlights ? { highlights: source.highlights } : {}), + ...(media.length ? { screenshots: media.map(({ bytes: _bytes, ...descriptor }) => descriptor) } : {}), + } + validateListing(listing) + return { listing, media } +} + +/** Idempotent immutable uploads; the Cloud verifies the body digest against the path. */ +export async function uploadMedia( + media: MediaBlob[], + baseURL: string, + token: string, + fetcher: (url: string, init: RequestInit) => Promise = fetch, +): Promise { + for (const blob of media) { + const response = await fetcher(`${baseURL}/api/v1/catalog/media/${blob.digest.slice(7)}`, { + method: 'PUT', + headers: { authorization: `Bearer ${token}`, 'content-type': blob.mediaType }, + body: blob.bytes as Uint8Array, + signal: AbortSignal.timeout(60_000), + redirect: 'error', + }) + if (response.status !== 200) throw new Error(`PUT /catalog/media/${blob.name} failed (${response.status})`) + const stored = await response.json() as { digest?: string; size?: number; mediaType?: string } + if (stored.digest !== blob.digest || stored.size !== blob.size || stored.mediaType !== blob.mediaType) { + throw new Error(`stored media ${blob.name} does not match the local file`) + } + } +} diff --git a/hack/publish-entry.ts b/hack/publish-entry.ts index 29f7c53..7b853f7 100644 --- a/hack/publish-entry.ts +++ b/hack/publish-entry.ts @@ -3,6 +3,7 @@ import { execFile } from 'node:child_process' import { appendFile } from 'node:fs/promises' import { parseArgs, promisify } from 'node:util' import { YAML } from 'bun' +import { loadListing, type Listing, type MediaBlob, uploadMedia, validateListing } from './catalog-listing' const catalogRepository = 'ghcr.io/appthrust/catalog' const imageRepository = 'ghcr.io/appthrust/tool-builder' @@ -25,6 +26,7 @@ export interface CatalogEntry { versions: CatalogVersion[] updatePolicy: { default: 'pinned' | 'follow'; allowed: Array<'pinned' | 'follow'> } display: { category?: string; icon?: string } + listing?: Listing publishedAt: string | null } @@ -48,7 +50,7 @@ export function validateRelease(version: string, digest: string): void { } } -export function renderEntry(template: string, version: string, digest: string, previous?: CatalogEntry): CatalogEntry { +export function renderEntry(template: string, version: string, digest: string, previous?: CatalogEntry, listing?: Listing): CatalogEntry { validateRelease(version, digest) const definition = YAML.parse(template) as Definition if (definition.apiVersion !== 'appthrust.io/v1alpha1' || definition.kind !== 'ApplicationStackDefinition' || definition.metadata.name !== 'tool-builder') { @@ -81,16 +83,31 @@ export function renderEntry(template: string, version: string, digest: string, p default: true, }) definition.spec.versions = [...versions.values()] + if (listing) validateListing(listing) + const carried = listing ?? previous?.listing return { slug: 'tool-builder', definitionYAML: YAML.stringify(definition), versions: definition.spec.versions, updatePolicy: definition.spec.updatePolicy, display: { category: definition.spec.display.category, icon: definition.spec.display.iconRef?.name }, + ...(carried ? { listing: carried } : {}), publishedAt: previous?.publishedAt ?? null, } } +/** + * Replaces only the listing of the entry the catalog already records. Versions, + * policy and display stay exactly as stored: a listing change never implies a + * release. Requires a published entry; the first tag publish carries the + * listing itself. + */ +export function renderListingUpdate(current: CatalogEntry, listing: Listing): CatalogEntry { + if (current.slug !== 'tool-builder') throw new Error('current entry must have slug tool-builder') + validateListing(listing) + return { ...current, listing } +} + export function catalogContainsRelease(index: unknown, version: string, digest: string): boolean { if (!index || typeof index !== 'object' || !('schemaVersion' in index) || index.schemaVersion !== 1 || !('entries' in index) || !Array.isArray(index.entries)) return false @@ -132,15 +149,46 @@ export interface CatalogPublication { state: 'queued' | 'snapshot' } -export async function submitEntry( - template: string, +/** + * The image digest the catalog already records for `version`, or null. A + * re-run of the publish workflow (for example after a failed Cloud signing + * dispatch) must reuse this image instead of building a new one: versions are + * immutable, so a second build with a different digest is rejected. + */ +export async function recordedDigest( version: string, - digest: string, baseURL: string, token: string, fetcher: (url: string, init: RequestInit) => Promise = fetch, -): Promise { - validateRelease(version, digest) +): Promise { + const response = await fetcher(`${baseURL}/api/v1/catalog/entries`, { + method: 'GET', + headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, + signal: AbortSignal.timeout(30_000), + redirect: 'error', + }) + if (response.status !== 200) throw new Error(`GET /catalog/entries failed (${response.status})`) + const current = await response.json() as { data: CatalogEntry[] } + if (!Array.isArray(current.data)) throw new Error('catalog entries response must contain data[]') + const recorded = current.data.find(entry => entry.slug === 'tool-builder')?.versions.find(entry => entry.name === version) + if (!recorded) return null + const image = recorded.images.web + if (typeof image !== 'string' || !image.startsWith(`${imageRepository}@`) || Object.keys(recorded.images).length !== 1) { + throw new Error(`version ${version} is recorded with an unexpected image set`) + } + const digest = image.slice(imageRepository.length + 1) + if (!digestPattern.test(digest)) throw new Error(`version ${version} is recorded with an invalid digest`) + return digest +} + +interface CatalogClient { + request(path: string, method: string, body?: unknown): Promise + entryRequest(path: string, method: string, body?: unknown): Promise + currentEntry(): Promise + publish(): Promise +} + +function catalogClient(baseURL: string, token: string, fetcher: (url: string, init: RequestInit) => Promise): CatalogClient { async function request(path: string, method: string, body?: unknown): Promise { return fetcher(`${baseURL}/api/v1/catalog/${path}`, { method, @@ -155,25 +203,102 @@ export async function submitEntry( if (response.status !== 200) throw new Error(`${method} /catalog/${path} failed (${response.status})`) return response.json() } - const current = await entryRequest('entries', 'GET') as { data: CatalogEntry[] } - if (!Array.isArray(current.data)) throw new Error('catalog entries response must contain data[]') - const entry = renderEntry(template, version, digest, current.data.find(entry => entry.slug === 'tool-builder')) - await entryRequest('entries/tool-builder', 'PUT', entry) - const response = await request('publish', 'POST') - if (response.status !== 200 && response.status !== 202) throw new Error(`POST /catalog/publish failed (${response.status})`) - const publication = await response.json() as CatalogPublication - if (typeof publication.id !== 'string' || !publication.id || /[\r\n]/.test(publication.id) || - !(response.status === 202 && publication.state === 'queued' || response.status === 200 && publication.state === 'snapshot')) { - throw new Error('catalog publish response must contain a queued (202) or snapshot (200) snapshot id') + return { + request, + entryRequest, + async currentEntry() { + const current = await entryRequest('entries', 'GET') as { data: CatalogEntry[] } + if (!Array.isArray(current.data)) throw new Error('catalog entries response must contain data[]') + return current.data.find(entry => entry.slug === 'tool-builder') + }, + async publish() { + const response = await request('publish', 'POST') + if (response.status !== 200 && response.status !== 202) throw new Error(`POST /catalog/publish failed (${response.status})`) + const publication = await response.json() as CatalogPublication + if (typeof publication.id !== 'string' || !publication.id || /[\r\n]/.test(publication.id) || + !(response.status === 202 && publication.state === 'queued' || response.status === 200 && publication.state === 'snapshot')) { + throw new Error('catalog publish response must contain a queued (202) or snapshot (200) snapshot id') + } + return publication + }, } - return publication +} + +export async function submitEntry( + template: string, + version: string, + digest: string, + baseURL: string, + token: string, + fetcher: (url: string, init: RequestInit) => Promise = fetch, + listing?: { listing: Listing; media: MediaBlob[] }, +): Promise { + validateRelease(version, digest) + const client = catalogClient(baseURL, token, fetcher) + const previous = await client.currentEntry() + if (listing) await uploadMedia(listing.media, baseURL, token, fetcher) + const entry = renderEntry(template, version, digest, previous, listing?.listing) + await client.entryRequest('entries/tool-builder', 'PUT', entry) + return client.publish() +} + +/** Uploads screenshots, replaces the stored entry's listing, and requests a publication. */ +export async function submitListing( + source: { listing: Listing; media: MediaBlob[] }, + baseURL: string, + token: string, + fetcher: (url: string, init: RequestInit) => Promise = fetch, +): Promise { + const client = catalogClient(baseURL, token, fetcher) + const current = await client.currentEntry() + if (!current) throw new Error('catalog has no tool-builder entry yet; publish a release tag first') + await uploadMedia(source.media, baseURL, token, fetcher) + await client.entryRequest('entries/tool-builder', 'PUT', renderListingUpdate(current, source.listing)) + return client.publish() +} + +async function optionalListing(): Promise<{ listing: Listing; media: MediaBlob[] } | undefined> { + const catalogDir = new URL('../catalog/', import.meta.url) + if (!(await Bun.file(new URL('listing.yaml', catalogDir)).exists())) return undefined + return loadListing(catalogDir) } async function main(): Promise { const [subcommand, ...args] = Bun.argv.slice(2) const { values } = parseArgs({ args, options: { version: { type: 'string' }, digest: { type: 'string' } }, strict: true }) + if (subcommand === 'recorded') { + if (!values.version || values.digest) throw new Error('usage: bun hack/publish-entry.ts recorded --version ') + validateRelease(values.version, `sha256:${'1'.repeat(64)}`) + const token = process.env.CLOUD_CATALOG_ADMIN_TOKEN + if (!token) throw new Error('CLOUD_CATALOG_ADMIN_TOKEN is required') + const baseURL = (process.env.CLOUD_API_URL ?? 'https://api.appthrust.com').replace(/\/$/, '') + const digest = await recordedDigest(values.version, baseURL, token) + if (process.env.GITHUB_OUTPUT) await appendFile(process.env.GITHUB_OUTPUT, `digest=${digest ?? ''}\n`) + console.log(digest ? `Catalog already records ${values.version} as ${digest}` : `Catalog has no image for ${values.version}`) + return + } + if (subcommand === 'validate-listing') { + const source = await optionalListing() + if (!source) throw new Error('catalog/listing.yaml not found') + console.log(`Listing valid: ${Object.keys(source.listing.locales).join(',')} locales, ${source.listing.highlights?.length ?? 0} highlights, ${source.media.length} screenshots (${source.media.reduce((sum, media) => sum + media.size, 0)} bytes)`) + return + } + if (subcommand === 'listing') { + if (values.version || values.digest) throw new Error('usage: bun hack/publish-entry.ts listing') + const token = process.env.CLOUD_CATALOG_ADMIN_TOKEN + if (!token) throw new Error('CLOUD_CATALOG_ADMIN_TOKEN is required') + const baseURL = (process.env.CLOUD_API_URL ?? 'https://api.appthrust.com').replace(/\/$/, '') + const source = await optionalListing() + if (!source) throw new Error('catalog/listing.yaml not found') + const publication = await submitListing(source, baseURL, token) + if (process.env.GITHUB_OUTPUT) { + await appendFile(process.env.GITHUB_OUTPUT, `snapshot_id=${publication.id}\nstate=${publication.state}\n`) + } + console.log(`Catalog snapshot ${publication.id}: ${publication.state}`) + return + } if ((subcommand !== 'submit' && subcommand !== 'await') || !values.version || !values.digest) { - throw new Error('usage: bun hack/publish-entry.ts --version --digest ') + throw new Error('usage: bun hack/publish-entry.ts --version [--digest ]') } validateRelease(values.version, values.digest) if (subcommand === 'submit') { @@ -181,7 +306,7 @@ async function main(): Promise { if (!token) throw new Error('CLOUD_CATALOG_ADMIN_TOKEN is required') const baseURL = (process.env.CLOUD_API_URL ?? 'https://api.appthrust.com').replace(/\/$/, '') const template = await Bun.file(new URL('../catalog/entry.yaml', import.meta.url)).text() - const publication = await submitEntry(template, values.version, values.digest, baseURL, token) + const publication = await submitEntry(template, values.version, values.digest, baseURL, token, fetch, await optionalListing()) if (process.env.GITHUB_OUTPUT) { await appendFile(process.env.GITHUB_OUTPUT, `snapshot_id=${publication.id}\nstate=${publication.state}\n`) }