Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

ci: generate README plugin and demo tables from their live sources (#174)

TamL.954cd5845e90
diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml
index 679cc55..3eb2348 100644
--- a/.github/workflows/docs-quality.yml
+++ b/.github/workflows/docs-quality.yml
@@ -3,6 +3,8 @@ name: Docs quality
# Deterministic, stdlib-only gates (scripts/ci/*.py, Python 3.10). No third-party actions.
on:
pull_request:
+ # `edited` re-runs pr-scope when only the PR title changes.
+ types: [opened, synchronize, reopened, edited]
permissions:
contents: read
diff --git a/.github/workflows/readme-tables-sync.yml b/.github/workflows/readme-tables-sync.yml
new file mode 100644
index 0000000..d2d4b2e
--- /dev/null
+++ b/.github/workflows/readme-tables-sync.yml
@@ -0,0 +1,95 @@
+name: README tables sync
+
+# Keeps the generated README tables equal to their sources: the plugin table to the img2 catalog
+# (scripts/ci/plugin_table.py) and the demo table to the gallery's demos.json (scripts/ci/showcase_table.py).
+# Stdlib Python + the preinstalled gh CLI only; no third-party actions beyond checkout/setup-python.
+on:
+ schedule:
+ - cron: "17 5 * * *"
+ workflow_dispatch:
+ repository_dispatch:
+ types: [catalog-updated]
+ pull_request:
+ paths:
+ - README.md
+ - scripts/ci/plugin_table.py
+ - scripts/ci/showcase_table.py
+
+permissions:
+ contents: read
+
+jobs:
+ drift-warning:
+ # Non-blocking: reports drift as a warning annotation, never fails the PR.
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.10"
+ - name: Check README tables against their sources
+ run: |
+ cd scripts/ci
+ for t in plugin_table showcase_table; do
+ python3 $t.py --readme ../../README.md --check \
+ || echo "::warning file=README.md::$t differs from its source; the daily sync opens an issue; run scripts/ci/$t.py --write to refresh it."
+ done
+
+ sync:
+ # Actions may not create PRs in this repo, so drift is reported as an issue
+ # (one open issue, updated in place); a maintainer runs --write and opens the PR.
+ if: github.event_name != 'pull_request'
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ issues: write
+ env:
+ GH_TOKEN: ${{ github.token }}
+ TITLE: "README generated tables are out of date"
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: main
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.10"
+ - name: Regenerate the tables
+ id: regen
+ # One unreachable source must not block the other table; the job still fails at the end.
+ run: |
+ failed=""
+ for t in plugin_table showcase_table; do
+ (cd scripts/ci && python3 $t.py --readme ../../README.md --write) || failed="$failed $t"
+ done
+ echo "failed=$failed" >> "$GITHUB_OUTPUT"
+ - name: Open or update the drift issue
+ run: |
+ existing=$(gh issue list --state open --search "in:title \"$TITLE\"" --json number,title \
+ -q ".[] | select(.title == env.TITLE) | .number" | head -1)
+ if git diff --quiet -- README.md; then
+ echo "README already matches the catalog"
+ if [ -n "$existing" ]; then
+ gh issue close "$existing" --comment "README matches the catalog again."
+ fi
+ exit 0
+ fi
+ {
+ echo "A generated table in README.md no longer matches its source (img2 catalog or gallery demos.json)."
+ echo
+ echo "To fix: \`cd scripts/ci && python3 plugin_table.py --readme ../../README.md --write && python3 showcase_table.py --readme ../../README.md --write\`, then open a PR with the README change."
+ echo
+ echo '```diff'
+ git diff -- README.md
+ echo '```'
+ } > body.md
+ if [ -n "$existing" ]; then
+ gh issue edit "$existing" --body-file body.md
+ else
+ gh issue create --title "$TITLE" --body-file body.md
+ fi
+ - name: Fail if a source could not be read
+ if: steps.regen.outputs.failed != ''
+ run: |
+ echo "::error::could not regenerate:${{ steps.regen.outputs.failed }}"
+ exit 1
diff --git a/README.md b/README.md
index 52c2f68..a68eb1f 100644
--- a/README.md
+++ b/README.md
@@ -51,28 +51,27 @@ Every model in the gallery is generated code, running in your browser. No mesh f
Reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open any model to orbit it, inspect its reference, and read the generated source.
+<!-- showcase:start -->
| Demo | Subject | Built with | View | Source |
| --- | --- | --- | --- | --- |
-| Dual-Sword Warrior — TypeScript procedural surfaces ⚠︎ | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/girl-character) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/girl-character/createGirlCharacterModel.ts) |
-| Low-Poly Humanoid — Rigged Character ⚠︎ | character | `v1.5.0` | [Live](https://img2threejs.io/#/demo/low-poly-humanoid) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/low-poly-humanoid/createLowPolyHumanoidModel.ts) |
+| Tropical Island — Code-only Diorama | object | — | [Live](https://img2threejs.io/#/demo/tropical-island) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/tropical-island/createTropicalIslandModel.ts) |
+| Man Robot · Segment Color Studio | character | — | [Live](https://img2threejs.io/#/demo/man-robot-studio) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/man-robot-studio/robotModel.ts) |
+| Snowbound Crossing — Mini Game | object | — | [Live](https://img2threejs.io/#/demo/snowy-village) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/snowy-village/createSnowyVillageModel.ts) |
+| Ocean Blue PRS Guitar — Measured Surface Flow | object | `v1.5.2` | [Live](https://img2threejs.io/#/demo/prs-ocean) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/prs-ocean/createPrsOceanModel.ts) |
+| Groot — Heart of the Forest | character | `v1.5.2` | [Live](https://img2threejs.io/#/demo/monster-tree) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/monster-tree/createMonsterTreeModel.ts) |
+| Raz — Detonating Strike VFX | character | `v1.5.2` | [Live](https://img2threejs.io/#/demo/raz) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/raz/razVfx.ts) |
+| Starship + Super Heavy | object | `v1.2.0` | [Live](https://img2threejs.io/#/demo/starship-super-heavy) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/starship-super-heavy/createStarshipSuperHeavyModel.ts) |
+| Mars Cat — Measured Procedural Surfaces | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/mars-cat) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/mars-cat/createMarsCatModel.ts) |
+| Lee Sin — Game Character | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/leesin) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/leesin/createLeesinModel.ts) |
+| Dual-Sword Warrior — Procedural Character | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/girl-character-3) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/girl-character-3/createGirlCharacter3Model.ts) |
+| AWP \| Medusa (Minimal Wear) · V2 rebuild | object | `v1.4.4` | [Live](https://img2threejs.io/#/demo/awp-medusa-v2) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/awp-medusa-v2/createAwpMedusaModelV2.ts) |
| ★ Talon Knife \| Doppler Ruby (Factory New) | object | `v1.4.4` | [Live](https://img2threejs.io/#/demo/talon-doppler-ruby) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/talon-doppler-ruby/createTalonDopplerRubyModel.ts) |
-| AWP \| Medusa (Minimal Wear) · V2 rebuild | object | `V2` | [Live](https://img2threejs.io/#/demo/awp-medusa-v2) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/awp-medusa-v2/createAwpMedusaModelV2.ts) |
-| Pikachu 10K Star Celebration ⚠︎ | character | `v1.5-beta` | [Live](https://img2threejs.io/#/demo/electric-mouse-mascot) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/electric-mouse-mascot/createElectricMouseMascotModel.ts) |
-| Glock-18 \| Ghost Protocol (Well-Worn) | object | `v1.4.1` | [Live](https://img2threejs.io/#/demo/glock-ghost-protocol) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/glock-ghost-protocol/createGlockGhostProtocolModel.ts) |
-| Classic Knife \| Fade (Minimal Wear) | object | `v1.3` | [Live](https://img2threejs.io/#/demo/classic-fade) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/classic-fade/createClassicFadeModel.ts) |
-| BMX Endurance Bike | object | `v1.3` | [Live](https://img2threejs.io/#/demo/bmx-endurance) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/bmx-endurance/createBmxEnduranceBikeModel.ts) |
-| M9 Bayonet \| Doppler Phase 2 | object | `v1.3` | [Live](https://img2threejs.io/#/demo/m9-doppler) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/m9-doppler/createM9DopplerModel.ts) |
-| Sony WF-1000XM3 Earbuds + Case | object | `v1.2` | [Live](https://img2threejs.io/#/demo/sony-wf1000xm3) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/sony-wf1000xm3/createSonyWf1000xm3Model.ts) |
-| ISSACA 12 Gauge Shotgun | object | `v1.2` | [Live](https://img2threejs.io/#/demo/issaca-shotgun) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/issaca-shotgun/createIssacaShotgunModel.ts) |
-| Gerber Paracord Knife | object | `v1.2` | [Live](https://img2threejs.io/#/demo/gerber-knife) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/gerber-knife/createGerberKnifeModel.ts) |
-| Doraemon House (isometric diorama) | object | `v1.2` | [Live](https://img2threejs.io/#/demo/doraemon-house) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/doraemon-house/createDoraemonHouseModel.ts) |
-| War-Hauler "SECTOR 07" | object | `v1.2` | [Live](https://img2threejs.io/#/demo/warhauler) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/warhauler/createWarHaulerModel.ts) |
-| Crowned Loot Chest ⚠︎ | object | `v1.2` | [Live](https://img2threejs.io/#/demo/crown-chest) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/crown-chest/createCrownChestModel.ts) |
-
-⚠︎ marks a demo whose registry `status` is still `placeholder` rather than `final` — it renders, but it
-is not finished work. The **Built with** column is the version each demo's own registry entry records in
-`generatedWith`, not an inference from dates; `awp-medusa-v2` records `V2`, which is that demo's rebuild
-pass rather than a release number. Rows are ordered newest first by the commit that added the demo.
+<!-- showcase:end -->
+
+The newest finished demos, generated from the gallery's
+[`demos.json`](https://img2threejs.io/demos.json) by `scripts/ci/showcase_table.py`. The gallery
+also has work in progress. **Built with** is the version tag in each demo's own `generatedWith`
+record (— when it names none).
The gallery source lives in [img2threejs/img2threejs-showcase](https://github.com/img2threejs/img2threejs-showcase). If this project is useful, a star on this repo helps others find it.
@@ -144,17 +143,19 @@ It links an `img2` command if `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local
### 3. Choose plugins — do not install everything by default
+<!-- plugins:start -->
| Plugin / source README | Adds | Access | Install after harness setup |
|---|---|---|---|
-| [cs2](https://github.com/img2threejs/plugin-cs2) | `cs2` profile — CS2 weapon/glove skin reconstruction, family adapters, finish rules and blocking domain review gates | Public | `img2 add cs2 --yes` |
-| [character](https://github.com/img2threejs/plugin-character) | `animated-character` profile — character workflow plus Stage R rigging/animation gates | Public | `img2 add character --yes` |
-| [environment](https://github.com/img2threejs/plugin-environment) | The environment plugin, distributed from a private repository | **Private — authorized Git access required** | `img2 add environment --yes` |
-| [img2glb](https://github.com/img2threejs/plugin-img2glb) | Explicit `image → glb` route through the hosted TRELLIS space; generated mesh output, not the default code-only route | Public | `img2 add img2glb --yes` |
-| [hello-cube](https://github.com/img2threejs/plugin-hello-cube) | Small deterministic image-to-Three.js cube example and plugin contract exerciser | Public | `img2 add hello-cube --yes` |
-
-These are announced plugins; use `img2 plugins` for the current catalog. Open each
-plugin's linked README for its input requirements, dependencies and tool setup.
-For example, the CS2 plugin:
+| [character](https://github.com/img2threejs/plugin-character) | Character rigging and animation: skeleton from a GLB, skin conditioning, clip measurement, action design, and a twelve-check rig gate. | Public | `img2 add character --yes` |
+| [cs2](https://github.com/img2threejs/plugin-cs2) | Counter-Strike 2 weapon and glove skin reconstruction: intake contract, authoritative classification, finish/material recipes, and a blocking review gate. | Public | `img2 add cs2 --yes` |
+| [environment](https://github.com/img2threejs/plugin-environment) | Install and manage the private img2 environment plugin through the img2 harness. Authorized GitHub access is required. | **Private — authorized Git access required** | `img2 add environment --yes` |
+| [hello-cube](https://github.com/img2threejs/plugin-hello-cube) | Turn an image into a deterministic Three.js cube (contract exerciser) | Public | `img2 add hello-cube --yes` |
+| [img2glb](https://github.com/img2threejs/plugin-img2glb) | Turn an image into a GLB 3D mesh via the hosted TRELLIS space | Public | `img2 add img2glb --yes` |
+<!-- plugins:end -->
+
+The table above is generated from the live catalog (`scripts/ci/plugin_table.py`); list all
+plugins with `img2 plugins`. Open each plugin's linked README for its input requirements,
+dependencies and tool setup. Example (the `cs2` plugin; substitute any catalog id):
```bash
img2 add cs2 --yes
diff --git a/SKILL.md b/SKILL.md
index 8c1fcf9..85eea08 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -92,7 +92,7 @@ python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence
silent omission is forbidden. Loop counts derive from `reviewHistory` actions
(`refine-spec`/`refine-code`), not agent memory. Defaults: 3 corrections per pass, 6 total.
- A domain profile's steps, gates and reference material come from the **registry**: in-repo
- modules (`character`) and installed plugins (`cs2`, `animated-character` from plugin-character) register identically, and
+ modules (`character`) and installed plugins (e.g. `cs2`) register identically, and
`forge/state.py init` names what is available. A profile adds mandatory gates without changing
the core order -- a domain plugin typically requires an authoritative classification, an intake
manifest, and a machine-readable domain review before AI review; `character` requires the
@@ -407,6 +407,7 @@ a missing profile is handled by the preflight above, and only a plugin that does
upstream is a blocker to report.
```bash
+img2 plugins # list plugins
img2 add img2threejs/plugin-<id> --ref <tag> # install a plugin at a tag (e.g. plugin-cs2)
img2 doctor # what each host resolves: base-skill path + version, plugin gates
img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge
diff --git a/scripts/ci/plugin_table.py b/scripts/ci/plugin_table.py
new file mode 100644
index 0000000..4af3248
--- /dev/null
+++ b/scripts/ci/plugin_table.py
@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Render the README plugin table from the img2 catalog.
+
+Usage: plugin_table.py [--catalog URL|FILE] [--readme FILE] [--write | --check]
+Replaces the text between <!-- plugins:start --> and <!-- plugins:end -->.
+No flag prints the rendered table. --check exits 1 on drift; --write updates the file.
+"""
+import argparse
+import json
+import re
+import sys
+import urllib.request
+
+CATALOG_URL = "https://raw.githubusercontent.com/img2threejs/img2/main/catalog.json"
+START, END = "<!-- plugins:start -->", "<!-- plugins:end -->"
+HEADER = ["Plugin / source README", "Adds", "Access", "Install after harness setup"]
+
+
+def load_catalog(src):
+ if re.match(r"https?://", src):
+ with urllib.request.urlopen(src, timeout=30) as r: # noqa: S310 (fixed https URL)
+ data = json.load(r)
+ else:
+ with open(src, encoding="utf-8") as f:
+ data = json.load(f)
+ plugins = data.get("plugins") if isinstance(data, dict) else None
+ if not isinstance(plugins, list):
+ raise ValueError("catalog has no 'plugins' list")
+ for p in plugins:
+ for k in ("id", "description", "source", "access"):
+ if not p.get(k):
+ raise ValueError(f"catalog plugin missing '{k}': {p!r}")
+ return plugins
+
+
+def cell(text):
+ return " ".join(str(text).split()).replace("|", "\\|")
+
+
+def render(plugins):
+ rows = [
+ "| " + " | ".join(HEADER) + " |",
+ "|---|---|---|---|",
+ ]
+ for p in sorted(plugins, key=lambda p: p["id"]):
+ access = p["access"].capitalize()
+ if p["access"] != "public":
+ access = f"**{access} — authorized Git access required**"
+ rows.append(
+ f"| [{cell(p['id'])}](https://github.com/{p['source']}) | {cell(p['description'])} "
+ f"| {access} | `img2 add {p['id']} --yes` |"
+ )
+ return "\n".join(rows)
+
+
+def replace_block(text, table, start=START, end=END):
+ i, j = text.find(start), text.find(end)
+ if i < 0 or j < i:
+ raise ValueError(f"README needs {start} ... {end} markers")
+ return text[: i + len(start)] + "\n" + table + "\n" + text[j:]
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+ ap.add_argument("--catalog", default=CATALOG_URL, help="catalog URL or local file")
+ ap.add_argument("--readme", default="README.md")
+ g = ap.add_mutually_exclusive_group()
+ g.add_argument("--write", action="store_true")
+ g.add_argument("--check", action="store_true")
+ a = ap.parse_args(argv)
+ try:
+ table = render(load_catalog(a.catalog))
+ with open(a.readme, encoding="utf-8") as f:
+ old = f.read()
+ new = replace_block(old, table)
+ except (OSError, ValueError, json.JSONDecodeError) as e:
+ print(f"plugin_table: {e}", file=sys.stderr)
+ return 2
+ if a.check:
+ if new != old:
+ print(f"{a.readme}: plugin table differs from the catalog; run plugin_table.py --write")
+ return 1
+ print("plugin table matches the catalog")
+ elif a.write:
+ if new != old:
+ with open(a.readme, "w", encoding="utf-8") as f:
+ f.write(new)
+ print(f"{a.readme}: plugin table updated")
+ else:
+ print("plugin table already up to date")
+ else:
+ print(table)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/ci/showcase_table.py b/scripts/ci/showcase_table.py
new file mode 100644
index 0000000..b02970b
--- /dev/null
+++ b/scripts/ci/showcase_table.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Render the README demo table from the showcase gallery's demos.json.
+
+Usage: showcase_table.py [--catalog URL|FILE] [--readme FILE] [--limit N] [--write | --check]
+Lists the newest N demos whose status is final (the gallery's own order), between
+<!-- showcase:start --> and <!-- showcase:end -->. Work in progress stays in the gallery only.
+No flag prints the rendered table. --check exits 1 on drift; --write updates the file.
+"""
+import argparse
+import json
+import re
+import sys
+import urllib.request
+
+from plugin_table import cell, replace_block
+
+CATALOG_URL = "https://img2threejs.io/demos.json"
+START, END = "<!-- showcase:start -->", "<!-- showcase:end -->"
+LIMIT = 12
+REQUIRED = ("id", "title", "subjectClass", "status", "updatedAt", "url", "sourceUrl")
+
+
+def load_demos(src):
+ if re.match(r"https?://", src):
+ req = urllib.request.Request(src, headers={"User-Agent": "img2threejs-readme-sync"})
+ with urllib.request.urlopen(req, timeout=30) as r: # noqa: S310 (fixed https URL)
+ data = json.load(r)
+ else:
+ with open(src, encoding="utf-8") as f:
+ data = json.load(f)
+ demos = data.get("demos") if isinstance(data, dict) else None
+ if not isinstance(demos, list):
+ raise ValueError("demos.json has no 'demos' list")
+ for d in demos:
+ for k in REQUIRED:
+ if not d.get(k):
+ raise ValueError(f"demo missing '{k}': {d.get('id', d)!r}")
+ return demos
+
+
+def render(demos, limit=LIMIT):
+ final = [d for d in demos if d["status"] == "final"]
+ final.sort(key=lambda d: d["updatedAt"], reverse=True) # stable: keeps the gallery's order on ties
+ rows = [
+ "| Demo | Subject | Built with | View | Source |",
+ "| --- | --- | --- | --- | --- |",
+ ]
+ for d in final[:limit]:
+ version = f"`{d['version']}`" if d.get("version") else "—"
+ rows.append(
+ f"| {cell(d['title'])} | {cell(d['subjectClass'])} | {version} "
+ f"| [Live]({d['url']}) | [code]({d['sourceUrl']}) |"
+ )
+ return "\n".join(rows)
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+ ap.add_argument("--catalog", default=CATALOG_URL, help="demos.json URL or local file")
+ ap.add_argument("--readme", default="README.md")
+ ap.add_argument("--limit", type=int, default=LIMIT)
+ g = ap.add_mutually_exclusive_group()
+ g.add_argument("--write", action="store_true")
+ g.add_argument("--check", action="store_true")
+ a = ap.parse_args(argv)
+ try:
+ table = render(load_demos(a.catalog), a.limit)
+ with open(a.readme, encoding="utf-8") as f:
+ old = f.read()
+ new = replace_block(old, table, START, END)
+ except (OSError, ValueError, json.JSONDecodeError) as e:
+ print(f"showcase_table: {e}", file=sys.stderr)
+ return 2
+ if a.check:
+ if new != old:
+ print(f"{a.readme}: demo table differs from the gallery; run showcase_table.py --write")
+ return 1
+ print("demo table matches the gallery")
+ elif a.write:
+ if new != old:
+ with open(a.readme, "w", encoding="utf-8") as f:
+ f.write(new)
+ print(f"{a.readme}: demo table updated")
+ else:
+ print("demo table already up to date")
+ else:
+ print(table)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/ci/tests/test_ci_scripts.py b/scripts/ci/tests/test_ci_scripts.py
index 71b2dc1..3515576 100644
--- a/scripts/ci/tests/test_ci_scripts.py
+++ b/scripts/ci/tests/test_ci_scripts.py
@@ -7,7 +7,9 @@ import unittest
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
import md_links # noqa: E402
import md_tables # noqa: E402
+import plugin_table # noqa: E402
import pr_scope # noqa: E402
+import showcase_table # noqa: E402
import skill_budget # noqa: E402
GOOD = "| a | b |\n|---|:-:|\n| 1 | 2 |\n"
@@ -95,5 +97,120 @@ class ScopeTests(unittest.TestCase):
self.assertEqual(r, {5: ["b"]})
+def _plugin(i, access="public"):
+ return {"id": i, "description": f"{i} desc", "source": f"org/plugin-{i}", "access": access, "npmCli": None}
+
+
+class PluginTableTests(unittest.TestCase):
+ def setUp(self):
+ self.d = tempfile.mkdtemp()
+ self.cat = os.path.join(self.d, "catalog.json")
+ self.readme = os.path.join(self.d, "README.md")
+ with open(self.readme, "w") as f:
+ f.write("intro\n<!-- plugins:start -->\nold\n<!-- plugins:end -->\noutro\n")
+
+ def _cat(self, *plugins):
+ with open(self.cat, "w") as f:
+ json.dump({"schema": 1, "plugins": list(plugins)}, f)
+
+ def _run(self, *flags):
+ return plugin_table.main(["--catalog", self.cat, "--readme", self.readme, *flags])
+
+ def _text(self):
+ with open(self.readme) as f:
+ return f.read()
+
+ def test_write_then_check_clean(self):
+ self._cat(_plugin("b"), _plugin("a", "private"))
+ self.assertEqual(self._run("--check"), 1)
+ self.assertEqual(self._run("--write"), 0)
+ self.assertEqual(self._run("--check"), 0)
+ t = self._text()
+ self.assertTrue(t.startswith("intro\n") and t.endswith("outro\n"))
+ self.assertIn("[a](https://github.com/org/plugin-a)", t)
+ self.assertIn("`img2 add b --yes`", t)
+ self.assertIn("**Private", t)
+ self.assertLess(t.index("[a]"), t.index("[b]"))
+ self.assertEqual(md_tables.check_text(t), [])
+
+ def test_add_and_remove_change_table(self):
+ self._cat(_plugin("a"))
+ self._run("--write")
+ self._cat(_plugin("a"), _plugin("c"))
+ self.assertEqual(self._run("--check"), 1)
+ self._run("--write")
+ self.assertIn("img2 add c --yes", self._text())
+ self._cat(_plugin("a"))
+ self.assertEqual(self._run("--check"), 1)
+ self._run("--write")
+ self.assertNotIn("img2 add c", self._text())
+
+ def test_missing_markers_and_bad_catalog(self):
+ with open(self.readme, "w") as f:
+ f.write("no markers\n")
+ self._cat(_plugin("a"))
+ self.assertEqual(self._run("--check"), 2)
+ with open(self.cat, "w") as f:
+ f.write("{}")
+ self.assertEqual(self._run("--check"), 2)
+
+ def test_pipe_in_description_escaped(self):
+ p = _plugin("a")
+ p["description"] = "x | y"
+ self.assertIn("x \\| y", plugin_table.render([p]))
+
+
+def _demo(i, date, status="final", version="v1.5.2"):
+ return {"id": f"d{i}", "title": f"Demo {i}", "subjectClass": "object", "status": status,
+ "updatedAt": date, "version": version, "url": f"https://x/#/demo/d{i}",
+ "sourceUrl": f"https://x/src/d{i}.ts"}
+
+
+class ShowcaseTableTest(unittest.TestCase):
+ def setUp(self):
+ self.d = tempfile.mkdtemp()
+ self.cat = os.path.join(self.d, "demos.json")
+ self.readme = os.path.join(self.d, "README.md")
+ with open(self.readme, "w") as f:
+ f.write("a\n<!-- showcase:start -->\nold\n<!-- showcase:end -->\nb\n")
+
+ def _cat(self, *demos):
+ with open(self.cat, "w") as f:
+ json.dump({"schema": 1, "demos": list(demos)}, f)
+
+ def _run(self, *flags):
+ return showcase_table.main(["--catalog", self.cat, "--readme", self.readme, *flags])
+
+ def test_newest_final_only_and_limit(self):
+ demos = [_demo(i, f"2026-01-{i + 1:02d}") for i in range(14)] + [_demo(99, "2026-12-31", "placeholder")]
+ table = showcase_table.render(demos, limit=12)
+ self.assertNotIn("Demo 99", table)
+ self.assertIn("Demo 13", table)
+ self.assertNotIn("Demo 1 |", table)
+ self.assertLess(table.index("Demo 13"), table.index("Demo 12"))
+ self.assertEqual(len(table.splitlines()), 14)
+ self.assertEqual(md_tables.check_text(table + "\n"), [])
+
+ def test_missing_version_and_pipe(self):
+ d = _demo(1, "2026-01-01", version=None)
+ d["title"] = "Knife | Fade"
+ table = showcase_table.render([d])
+ self.assertIn("| — |", table)
+ self.assertIn("Knife \\| Fade", table)
+
+ def test_write_check_and_new_demo(self):
+ self._cat(_demo(1, "2026-01-01"))
+ self.assertEqual(self._run("--check"), 1)
+ self.assertEqual(self._run("--write"), 0)
+ self.assertEqual(self._run("--check"), 0)
+ self._cat(_demo(1, "2026-01-01"), _demo(2, "2026-02-01"))
+ self.assertEqual(self._run("--check"), 1)
+
+ def test_bad_catalog(self):
+ with open(self.cat, "w") as f:
+ f.write('{"demos": [{"id": "x"}]}')
+ self.assertEqual(self._run("--check"), 2)
+
+
if __name__ == "__main__":
unittest.main()