Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Deploy Pages

on:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: true

jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Configure Pages
uses: actions/configure-pages@v5
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
with:
path: docs
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,20 @@ The initial catalog direction is documented in [the GitHub trends research note]
## 📄 License

MIT. See [LICENSE](LICENSE).

## 🌐 Try the live demo

**[Open the OpenApps storefront](https://juwonllee2024-dotcom.github.io/openapps/)** in your browser. It is the same static catalog you can generate locally, with no account and no runtime cloud dependency.

![OpenApps real CLI smoke test](assets/openapps-demo.gif)

This recording was generated from real `replace`, `plan`, `share`, and `render` commands in this repository. Read the exact output in [the smoke-test transcript](assets/openapps-demo-transcript.txt).

## 📦 Install a release

Download the latest tested wheel from [GitHub Releases](https://github.com/juwonllee2024-dotcom/openapps/releases/latest), then run:

python -m pip install openapps_catalog-0.2.0-py3-none-any.whl
openapps replace notion

Each release is checked in a clean temporary virtual environment with [`scripts/verify_release.ps1`](scripts/verify_release.ps1) before it is published.
29 changes: 29 additions & 0 deletions assets/openapps-demo-transcript.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
OpenApps real CLI smoke test
Generated by scripts/record_demo.py

$ python -m openapps replace notion
appflowy productivity AppFlowy - A privacy-first workspace for notes, tasks, and collaboration.
[exit code: 0]

$ python -m openapps plan rustdesk --platform all
Setup plan: RustDesk
Upstream: https://github.com/rustdesk/rustdesk
No verified local install command is bundled for this selection.
Review the upstream installation guide before running anything.
[exit code: 0]

$ python -m openapps share rustdesk
## RustDesk: an open-source alternative

I found RustDesk through OpenApps as an alternative to TeamViewer, AnyDesk.
- Privacy: self-hosted
- Pricing: free
- Setup: about 10 minutes
- Upstream: https://github.com/rustdesk/rustdesk

OpenApps provides discovery and reviewable plans; it never executes installation commands.
[exit code: 0]

$ python -m openapps render --format html --output docs/index.html
Wrote docs\index.html
[exit code: 0]
Binary file added assets/openapps-demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
541 changes: 541 additions & 0 deletions docs/index.html

Large diffs are not rendered by default.

144 changes: 144 additions & 0 deletions docs/superpowers/plans/2026-08-17-openapps-growth-release.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# OpenApps Growth Release Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox ([ ] / [x]) syntax for tracking.

**Goal:** Publish a real local demo, a reproducible recording of tested user flows, and an installable GitHub Release so OpenApps can be tried and shared without cloning the repository.

**Architecture:** Reuse the existing standard-library renderer to generate docs/index.html for GitHub Pages. Add a development-only recording script that runs the real CLI through sys.executable -m openapps, captures its outputs, and renders a terminal GIF plus transcript. Keep release artifacts outside git and attach them to a tagged GitHub Release after the branch is merged.

**Tech Stack:** Python 3.11+, standard library runtime, Pillow and ffmpeg for local artifact generation, GitHub Actions Pages deployment, setuptools wheel/sdist.

## Global Constraints

- Do not add Pillow or ffmpeg as runtime dependencies.
- The recording must execute the actual CLI commands and preserve their captured output in a text transcript.
- The GIF and transcript must be generated from a clean worktree using the current source.
- The Pages site must be static and must not collect analytics or make runtime network requests.
- Release validation must install the built wheel into a temporary virtual environment without reaching PyPI.
- Preserve all existing tests and the safety boundary: OpenApps never executes catalog install commands.

---

### Task 1: Add reproducible demo and Pages assets

**Files:**
- Create: scripts/record_demo.py
- Create: docs/index.html by running the existing renderer
- Create: .github/workflows/pages.yml
- Test: tests/test_catalog.py

**Interfaces:**
- scripts/record_demo.py --output-dir assets runs four real flows and writes assets/openapps-demo.gif and assets/openapps-demo-transcript.txt.
- The Pages workflow deploys the checked-in docs/ directory on pushes to main.
- README must link to https://juwonllee2024-dotcom.github.io/openapps/ and embed assets/openapps-demo.gif.

- [ ] Step 1: Write failing documentation/asset assertions

Assert that README contains the demo URL and GIF path, and that the workflow contains actions/configure-pages, actions/upload-pages-artifact, and actions/deploy-pages.

- [ ] Step 2: Run the focused assertions and confirm they fail

Run: rtk py -m unittest tests.test_catalog.DocumentationTests -v

Expected: FAIL because no public demo link or recording path exists yet.

- [ ] Step 3: Implement the workflow, recording script, and generated demo page

The script must capture these real commands:

python -m openapps replace notion
python -m openapps plan rustdesk --platform all
python -m openapps share rustdesk
python -m openapps render --format html --output docs/index.html

Render each captured result as a terminal-style Pillow frame, save an animated GIF, and save the exact command/output transcript. Run the script from the repository root so docs/index.html is the real storefront.

- [ ] Step 4: Run focused assertions and the recording script

Run: rtk py -m unittest tests.test_catalog.DocumentationTests -v

Expected: PASS.

Run: rtk py scripts/record_demo.py --output-dir assets

Expected: the GIF and transcript exist and the transcript contains AppFlowy, RustDesk, and the generated docs/index.html path.

- [ ] Step 5: Commit demo assets and workflow

rtk git add scripts/record_demo.py docs/index.html .github/workflows/pages.yml assets/openapps-demo.gif assets/openapps-demo-transcript.txt tests/test_catalog.py README.md
rtk git commit -m "feat: add public demo and tested product recording"

### Task 2: Add release validation and build artifacts

**Files:**
- Create: scripts/verify_release.ps1
- Modify: README.md
- Test: tests/test_catalog.py

**Interfaces:**
- scripts/verify_release.ps1 -WheelPath <path> creates a temporary venv, installs only the wheel from the local directory, runs python -m openapps doctor, and runs python -m openapps replace notion.
- README includes install instructions for the GitHub Release asset and a visible latest-release link.

- [ ] Step 1: Write failing documentation assertions for release install

Assert README contains the GitHub releases URL, pip install, and openapps replace notion.

- [ ] Step 2: Run the focused test and confirm the release section is missing

Run: rtk py -m unittest tests.test_catalog.DocumentationTests -v

Expected: FAIL on the release URL assertion.

- [ ] Step 3: Add the verifier and release instructions

Build with python -m pip wheel . --no-deps --no-build-isolation --wheel-dir dist, run the verifier against the wheel, and document the exact local install command using the release asset. The verifier must remove only its own temporary venv under the worktree.

- [ ] Step 4: Build and test the wheel

Run: rtk py -m pip wheel . --no-deps --no-build-isolation --wheel-dir dist

Expected: a wheel named openapps_catalog-0.2.0-py3-none-any.whl.

Run: rtk powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify_release.ps1 -WheelPath <wheel path>

Expected: doctor reports 27 valid apps and replacement search returns AppFlowy.

- [ ] Step 5: Commit release tooling

rtk git add scripts/verify_release.ps1 README.md tests/test_catalog.py
rtk git commit -m "feat: add release install verification"

### Task 3: Full verification, publish, and release

**Files:**
- Verify: all changed files, generated assets, GitHub Actions, and release assets

- [ ] Step 1: Run the full local suite and artifact checks

Run: rtk py -m unittest discover -s tests -v

Expected: all tests pass.

Run: rtk py -m openapps doctor

Expected: Catalog valid: 27 apps.

Run: rtk powershell -NoProfile -Command "Get-Item assets/openapps-demo.gif,assets/openapps-demo-transcript.txt,docs/index.html | Select-Object Name,Length"

Expected: all three artifacts exist and the GIF has nonzero size.

- [ ] Step 2: Push and merge the growth branch

Push codex/openapps-growth, create a PR targeting main, wait for CI, and merge only after checks pass.

- [ ] Step 3: Enable and verify GitHub Pages

Configure Pages to deploy through the workflow, verify the workflow succeeds, and confirm the public URL serves the generated storefront.

- [ ] Step 4: Create GitHub Release v0.2.0

Build and locally verify the wheel, then create v0.2.0 with the wheel and sdist attached. Release notes must link the demo, GIF, and tested CLI flows.

- [ ] Step 5: Report evidence

Report the release URL, Pages URL, demo GIF path, test count, wheel verification result, and any external limitation such as Pages propagation delay. Do not claim virality; report the public distribution assets and measurable next actions.
5 changes: 4 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "openapps-catalog"
version = "0.1.0"
version = "0.2.0"
description = "Discover and compare open-source software you can run yourself."
readme = "README.md"
requires-python = ">=3.11"
Expand All @@ -25,3 +25,6 @@ openapps = "openapps.cli:main"

[tool.setuptools.package-data]
openapps = ["catalog.json"]

[tool.setuptools.packages.find]
include = ["openapps*"]
139 changes: 139 additions & 0 deletions scripts/record_demo.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
"""Record the real OpenApps CLI smoke test as a shareable GIF.

Requires Pillow only when regenerating demo assets. The commands themselves
run through the local package so the transcript reflects the current checkout.
"""

from __future__ import annotations

import argparse
import subprocess
import sys
import textwrap
from pathlib import Path

from PIL import Image, ImageDraw, ImageFont


ROOT = Path(__file__).resolve().parents[1]
COMMANDS = (
("replace notion", ("replace", "notion")),
("plan rustdesk", ("plan", "rustdesk", "--platform", "all")),
("share rustdesk", ("share", "rustdesk")),
(
"render storefront",
("render", "--format", "html", "--output", "docs/index.html"),
),
)


def _font(size: int) -> ImageFont.ImageFont:
for candidate in (
Path(r"C:\Windows\Fonts\CascadiaMono.ttf"),
Path(r"C:\Windows\Fonts\CascadiaCode.ttf"),
Path(r"C:\Windows\Fonts\consola.ttf"),
):
if candidate.exists():
return ImageFont.truetype(str(candidate), size)
return ImageFont.load_default()


def _run(args: tuple[str, ...]) -> tuple[str, int]:
completed = subprocess.run(
[sys.executable, "-m", "openapps", *args],
cwd=ROOT,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
text=True,
encoding="utf-8",
errors="replace",
check=False,
)
return completed.stdout.rstrip(), completed.returncode


def _frame(label: str, command: str, output: str, return_code: int) -> Image.Image:
image = Image.new("RGB", (1400, 800), "#0b1020")
draw = ImageDraw.Draw(image)
title_font = _font(24)
body_font = _font(21)
small_font = _font(18)

draw.rounded_rectangle((34, 30, 1366, 770), radius=24, fill="#111827", outline="#334155", width=2)
draw.rounded_rectangle((34, 30, 1366, 96), radius=24, fill="#172033")
draw.rectangle((34, 70, 1366, 96), fill="#172033")
for x, color in ((68, "#fb7185"), (98, "#fbbf24"), (128, "#34d399")):
draw.ellipse((x - 8, 55, x + 8, 71), fill=color)
draw.text((170, 48), "OPENAPPS / REAL SMOKE TEST", font=title_font, fill="#e2e8f0")
draw.text((1160, 52), label.upper(), font=small_font, fill="#67e8f9")

y = 132
draw.text((72, y), f"$ {command}", font=body_font, fill="#86efac")
y += 46
wrapped: list[str] = []
for line in output.splitlines() or ["(no output)"]:
wrapped.extend(textwrap.wrap(line, width=112) or [""])
max_lines = 25
if len(wrapped) > max_lines:
wrapped = wrapped[: max_lines - 1] + ["... see the full transcript in assets/"]
for line in wrapped:
draw.text((72, y), line, font=body_font, fill="#cbd5e1")
y += 25
status_color = "#86efac" if return_code == 0 else "#fb7185"
draw.text((72, 724), f"exit code: {return_code}", font=small_font, fill=status_color)
return image


def record(output_dir: Path) -> tuple[Path, Path]:
output_dir.mkdir(parents=True, exist_ok=True)
frames: list[Image.Image] = []
durations: list[int] = []
transcript: list[str] = [
"OpenApps real CLI smoke test",
"Generated by scripts/record_demo.py",
"",
]

for label, args in COMMANDS:
command = "python -m openapps " + " ".join(args)
output, return_code = _run(args)
transcript.extend((f"$ {command}", output, f"[exit code: {return_code}]", ""))
frames.append(_frame(label, command, output, return_code))
durations.append(2800)
if return_code != 0:
raise RuntimeError(f"Smoke test failed for {command} with exit code {return_code}")

gif_path = output_dir / "openapps-demo.gif"
frames[0].save(
gif_path,
save_all=True,
append_images=frames[1:],
duration=durations,
loop=0,
optimize=False,
)
transcript_path = output_dir / "openapps-demo-transcript.txt"
transcript_path.write_text("\n".join(transcript).rstrip() + "\n", encoding="utf-8")
return gif_path, transcript_path


def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--output-dir",
type=Path,
default=Path("assets"),
help="Directory for the GIF and transcript (relative to the repository root).",
)
arguments = parser.parse_args()
output_dir = arguments.output_dir
if not output_dir.is_absolute():
output_dir = ROOT / output_dir
gif_path, transcript_path = record(output_dir)
print(f"Recorded {gif_path.relative_to(ROOT)}")
print(f"Transcript {transcript_path.relative_to(ROOT)}")
return 0


if __name__ == "__main__":
raise SystemExit(main())
Loading
Loading