feat: workflow marketplace v0 — catalog, JSON endpoint, CLI search/install by coleam00 · Pull Request #1624 · coleam00/Archon

coleam00 · 2026-05-09T16:00:54Z

Summary

Problem: There was no way to discover and install community workflows without manually finding YAML files.
Why it matters: A marketplace lowers the barrier for users to adopt proven workflows and for contributors to share their work.
What changed: Added a typed data registry, browsable catalog + detail pages on the docs site, a machine-readable JSON endpoint, two CLI subcommands (workflow search / workflow install), a PR-gated lint Action, and a CONTRIBUTING.md section.
What did not change: Web UI, existing workflow engine, server API, database schema, or any platform adapter logic.

UX Journey

Before

User                          Archon CLI
────                          ──────────
wants community workflow
searches GitHub manually ───▶ (no discovery path)
downloads YAML manually
copies to .archon/workflows/

After

User                          Archon CLI             archon.diy
────                          ──────────             ──────────
wants community workflow
                              workflow search ──────▶ GET /workflows.json
                              prints table   ◀──────── returns entries
picks slug
                              workflow install <slug> ▶ GET raw.githubusercontent.com/<sha>/...
                              writes YAML    ◀──────── YAML content
runs workflow ──────────────▶ workflow run <slug> ...

Architecture Diagram

Before

packages/
  cli/commands/workflow.ts   (list, run, status, resume, etc.)
  docs-web/src/pages/        (roadmap.astro only)
  docs-web/src/data/         (roadmap.ts only)

After

packages/
  cli/commands/workflow.ts   [~] +workflowSearchCommand, +workflowInstallCommand
  cli/src/cli.ts             [~] +search early-exit, +install case, +force flag
  docs-web/src/data/
    marketplace.ts           [+] MarketplaceEntry interface + 4 seed entries
  docs-web/src/pages/
    workflows/index.astro    [+] catalog page (standalone HTML, client-side filter)
    workflows/[slug].astro   [+] detail page (getStaticPaths, install cmd, source link)
    workflows.json.ts        [+] flat JSON array API endpoint
  docs-web/scripts/
    lint-marketplace.ts      [+] Bun lint script (slugs, host allowlist, SHA checks)
  docs-web/astro.config.mjs  [~] +Marketplace sidebar entry
.github/workflows/
  marketplace-lint.yml       [+] PR Action for marketplace.ts changes
CONTRIBUTING.md              [~] +Contributing Workflows section

Connection inventory:

From	To	Status	Notes
cli.ts	workflowSearchCommand	new	early-exit before git check
cli.ts	workflowInstallCommand	new	inside workflow switch
workflowInstallCommand	@archon/git findRepoRoot	new	resolves repo root for write path
workflowInstallCommand	raw.githubusercontent.com	new	downloads YAML at pinned SHA
workflowSearchCommand	archon.diy/workflows.json	new	fetches marketplace index
lint-marketplace.ts	marketplace.ts	new	validates entries
marketplace-lint.yml	lint-marketplace.ts	new	CI trigger on marketplace.ts PRs
index.astro	marketplace.ts	new	renders catalog
[slug].astro	marketplace.ts	new	renders detail pages
workflows.json.ts	marketplace.ts	new	serves JSON endpoint

Label Snapshot

Risk: risk: low
Size: size: L
Scope: cli, docs, ci
Module: cli:workflow, docs-web:marketplace

Change Metadata

Change type: feature
Primary scope: multi

Linked Issue

Closes #

Validation Evidence (required)

bun run type-check   # ✓ zero errors
bun run lint         # ✓ zero warnings
bun run format:check # ✓ clean
bun run test         # ✓ no regressions (2 pre-existing failures on Windows: ClaudeProvider UID 0 check, dag-executor script node — unrelated to this PR)
cd packages/docs-web && bun run build  # ✓ all 4 detail pages + workflows.json generated

Evidence provided: CI validation run locally — all checks pass
Pre-existing test failures are Windows-specific and unrelated to marketplace changes

Security Impact (required)

New permissions/capabilities? Yes — workflow install writes files to .archon/workflows/ and workflow search fetches from the network
New external network calls? Yes — both commands fetch from archon.diy/workflows.json (overridable via ARCHON_MARKETPLACE_URL)
Secrets/tokens handling changed? No
File system access scope changed? Yes — workflow install writes to the repo's .archon/workflows/ directory

Risk and mitigation:

Host allowlist enforced at both install time and lint time (only github.com sources permitted)
SHA pinning ensures content integrity at a known commit
--force required to overwrite existing files (default throws)
ARCHON_MARKETPLACE_URL env var enables local testing without DNS dependency

Compatibility / Migration

Backward compatible? Yes — additive only; no existing commands changed
Config/env changes? No (new optional ARCHON_MARKETPLACE_URL env var)
Database migration needed? No

Human Verification (required)

Verified scenarios: TypeScript compiles clean, Astro build generates all expected static outputs, lint script passes on seed entries
Edge cases checked: workflow install with --force flag, missing git repo error path, bad slug error message
What was not verified: live archon.diy deployment (docs site not deployed yet); CLI end-to-end against live URL

Side Effects / Blast Radius (required)

Affected subsystems: CLI help text updated, docs sidebar gains Marketplace entry
Potential unintended effects: None — no server/engine/adapter code touched
Guardrails: ARCHON_MARKETPLACE_URL override for offline/local testing

Rollback Plan (required)

Fast rollback: Revert this PR — no database or schema changes
Feature flags: ARCHON_MARKETPLACE_URL can point to an empty [] array endpoint to effectively disable
Observable failure symptoms: workflow search / workflow install throw on network failure with descriptive error

Risks and Mitigations

Risk: SHA pins go stale as dev evolves (seed entries point to 69b2c89)
- Mitigation: Acceptable for v0 — update SHAs at release time; lint Action will catch broken SHAs on future PRs
Risk: archon.diy not deployed when CLI ships
- Mitigation: ARCHON_MARKETPLACE_URL env override; CLI fails fast with descriptive error
Risk: feat/roadmap Roadmap nav link is dead if that branch hasn't merged
- Mitigation: Low impact — 404 on hover only; acceptable for v0

Summary by CodeRabbit

New Features
- Added a workflow marketplace with searchable, tag-filterable catalog of community workflows
- Added CLI commands: workflow search to find marketplace workflows and workflow install <slug> to install them
- Individual workflow detail pages with installation instructions and metadata
Documentation
- Added workflow contribution guidelines detailing submission requirements and validation rules
- Added marketplace section to documentation site navigation
Chores
- Added automated CI validation for marketplace entries

PIV Task 1: Create marketplace.ts with MarketplaceEntry interface, tagConfig, VALID_HOSTS, and 4 seed entries pinned to SHA 69b2c89.

PIV Tasks 2-5: Standalone Astro catalog page with client-side filter, dynamic detail pages via getStaticPaths, workflows.json endpoint, and sidebar entry in astro.config.mjs.

PIV Tasks 6-7: Add workflowSearchCommand (fetches workflows.json, filters by query) and workflowInstallCommand (downloads YAML at pinned SHA, writes to .archon/workflows/). Wire in cli.ts with early-exit for search (no git required) and install case in switch.

PIV Tasks 8-10: Bun lint script validates slug uniqueness, host allowlist, and SHA+file existence. GitHub Action runs on PRs touching marketplace.ts. CONTRIBUTING.md documents submission process.

- Validate slug against ^[a-z0-9-]+$ before path construction to prevent path traversal when ARCHON_MARKETPLACE_URL points to an untrusted server - Validate required fields (slug, sourceUrl, tags) on each marketplace entry in fetchMarketplace() to surface clear errors on malformed responses Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Changes: - workflowInstallCommand now handles both blob (single-file) and tree (directory) URLs - Directory installs fetch GitHub Contents API listing and install files by convention (commands/ → .archon/commands/, scripts/ → .archon/scripts/, etc.) - Main workflow identified by slug-matching filename or sole .yaml in directory root - Lint script validates directory entries via GitHub Contents API instead of raw URL - Updated MarketplaceEntry.sourceUrl comment to reflect file-or-directory semantics - CONTRIBUTING.md documents both single-file and directory submission formats Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-05-09T16:01:01Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 99fa36d0-6206-4af9-b660-11135b302033

📥 Commits

Reviewing files that changed from the base of the PR and between eafff6b and 90bac07.

📒 Files selected for processing (10)

.github/workflows/marketplace-lint.yml
CONTRIBUTING.md
packages/cli/src/cli.ts
packages/cli/src/commands/workflow.ts
packages/docs-web/astro.config.mjs
packages/docs-web/scripts/lint-marketplace.ts
packages/docs-web/src/data/marketplace.ts
packages/docs-web/src/pages/workflows.json.ts
packages/docs-web/src/pages/workflows/[slug].astro
packages/docs-web/src/pages/workflows/index.astro

📝 Walkthrough

Walkthrough

This PR introduces a complete marketplace system for Archon workflows. It adds a data-driven marketplace with CLI search and install commands, a browsable web UI with filtering, automated validation, and comprehensive contributor documentation. All marketplace entries are pinned to specific commit SHAs for security and reproducibility.

Changes

Marketplace Feature

Layer / File(s)	Summary
Marketplace Data Model `packages/docs-web/src/data/marketplace.ts`	`MarketplaceEntry` interface, `tagConfig` styling map, `VALID_HOSTS` allowlist, and `marketplaceEntries` array with metadata, pinned SHAs, version compatibility, and featured status.
Marketplace API Endpoint `packages/docs-web/src/pages/workflows.json.ts`	Astro `GET` route exposing `marketplaceEntries` as JSON for CLI and web consumption.
CLI Search and Install Commands `packages/cli/src/commands/workflow.ts`	Fetches marketplace from configurable URL, implements `workflowSearchCommand` with query filtering and JSON output mode. Implements `workflowInstallCommand`: validates slug, parses GitHub URLs, downloads single files or directory trees at pinned SHA, installs to `.archon/` with safe path handling and force overwrite option.
CLI Command Routing `packages/cli/src/cli.ts`	Routes `workflow search` before git-repo validation; adds `workflow install <slug>` subcommand with `--force` flag; updates help text and usage examples.
Marketplace Browsing UI `packages/docs-web/src/pages/workflows/index.astro`	Renders searchable, tag-filterable grid of workflow cards with metadata, install preview, and featured badge. Client-side filtering by query and active tag; theme persistence; responsive dark styling.
Workflow Detail Page `packages/docs-web/src/pages/workflows/[slug].astro`	Static per-slug page showing workflow metadata, install command with copy-to-clipboard, GitHub source link at pinned commit, compatibility badge, and tags. Theme and clipboard handling scripts; responsive dark styling.
Marketplace Validation `packages/docs-web/scripts/lint-marketplace.ts`, `.github/workflows/marketplace-lint.yml`	Lint script validates entries for duplicate slugs, required fields (slug/name/author/description/40-char SHA/tags/archonVersionCompat), host allowlist, and pinned SHA existence via GitHub API (directory) and raw.githubusercontent.com HEAD (single file). GitHub Actions workflow runs on marketplace changes with Bun.
Documentation `CONTRIBUTING.md`, `packages/docs-web/astro.config.mjs`	Adds "Contributing Workflows to the Marketplace" section with submission steps, formats, entry requirements table, and self-attestation checklist. Updates Starlight sidebar with "Marketplace" link to `/workflows/`.

🎯 4 (Complex) | ⏱️ ~60 minutes

🐰 A marketplace blooms in code today,
Where workflows hop and search and play,
Pinned by SHA, they're safe and sound,
Community gold we've finally found! ✨

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch archon/task-feat-workflow-marketplace-v0

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

The directory install code used `subdir.name` and `file.name` from the GitHub Contents API directly in path joins. Add an `isSafePathComponent` guard that rejects `.`, `..`, and any name containing path separators or non-portable characters before using it. Same defense-in-depth pattern as the existing slug validation in `workflowInstallCommand`.

…low-marketplace-v0 # Conflicts: # packages/docs-web/astro.config.mjs

…stall (coleam00#1624) * feat(docs-web): add marketplace data registry PIV Task 1: Create marketplace.ts with MarketplaceEntry interface, tagConfig, VALID_HOSTS, and 4 seed entries pinned to SHA 69b2c89. * feat(docs-web): add marketplace catalog, detail pages, and JSON endpoint PIV Tasks 2-5: Standalone Astro catalog page with client-side filter, dynamic detail pages via getStaticPaths, workflows.json endpoint, and sidebar entry in astro.config.mjs. * feat(cli): add workflow search and install marketplace commands PIV Tasks 6-7: Add workflowSearchCommand (fetches workflows.json, filters by query) and workflowInstallCommand (downloads YAML at pinned SHA, writes to .archon/workflows/). Wire in cli.ts with early-exit for search (no git required) and install case in switch. * feat: add marketplace lint script, GitHub Action, and contributing guide PIV Tasks 8-10: Bun lint script validates slug uniqueness, host allowlist, and SHA+file existence. GitHub Action runs on PRs touching marketplace.ts. CONTRIBUTING.md documents submission process. * fix(cli): validate marketplace slug and entry fields before install - Validate slug against ^[a-z0-9-]+$ before path construction to prevent path traversal when ARCHON_MARKETPLACE_URL points to an untrusted server - Validate required fields (slug, sourceUrl, tags) on each marketplace entry in fetchMarketplace() to surface clear errors on malformed responses Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat(cli): support directory-based marketplace installs Changes: - workflowInstallCommand now handles both blob (single-file) and tree (directory) URLs - Directory installs fetch GitHub Contents API listing and install files by convention (commands/ → .archon/commands/, scripts/ → .archon/scripts/, etc.) - Main workflow identified by slug-matching filename or sole .yaml in directory root - Lint script validates directory entries via GitHub Contents API instead of raw URL - Updated MarketplaceEntry.sourceUrl comment to reflect file-or-directory semantics - CONTRIBUTING.md documents both single-file and directory submission formats Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(cli): validate path components from GitHub API in directory install The directory install code used `subdir.name` and `file.name` from the GitHub Contents API directly in path joins. Add an `isSafePathComponent` guard that rejects `.`, `..`, and any name containing path separators or non-portable characters before using it. Same defense-in-depth pattern as the existing slug validation in `workflowInstallCommand`. --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

coleam00 and others added 6 commits May 9, 2026 10:25

feat(docs-web): add marketplace data registry

b957fd7

PIV Task 1: Create marketplace.ts with MarketplaceEntry interface, tagConfig, VALID_HOSTS, and 4 seed entries pinned to SHA 69b2c89.

feat(docs-web): add marketplace catalog, detail pages, and JSON endpoint

bb87394

PIV Tasks 2-5: Standalone Astro catalog page with client-side filter, dynamic detail pages via getStaticPaths, workflows.json endpoint, and sidebar entry in astro.config.mjs.

feat: add marketplace lint script, GitHub Action, and contributing guide

ae50603

PIV Tasks 8-10: Bun lint script validates slug uniqueness, host allowlist, and SHA+file existence. GitHub Action runs on PRs touching marketplace.ts. CONTRIBUTING.md documents submission process.

coleam00 added 2 commits May 10, 2026 09:01

Merge remote-tracking branch 'origin/dev' into archon/task-feat-workf…

90bac07

…low-marketplace-v0 # Conflicts: # packages/docs-web/astro.config.mjs

coleam00 marked this pull request as ready for review May 11, 2026 14:10

coleam00 merged commit b069680 into dev May 11, 2026
5 checks passed

coleam00 deleted the archon/task-feat-workflow-marketplace-v0 branch May 11, 2026 14:10

coleam00 mentioned this pull request May 11, 2026

feat(marketplace): add video-generic workflow #1639

Merged

Wirasm mentioned this pull request May 12, 2026

Release 0.3.11 #1653

Merged

This was referenced May 14, 2026

feat(marketplace): add archon-smart-mr-review (GitLab counterpart) #1681

Merged

feat(marketplace): add archon-resolve-mr-conflicts (GitLab counterpart) #1687

Open

feat(marketplace): add archon-comprehensive-mr-review (GitLab counterpart) #1686

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: workflow marketplace v0 — catalog, JSON endpoint, CLI search/install#1624

feat: workflow marketplace v0 — catalog, JSON endpoint, CLI search/install#1624
coleam00 merged 8 commits into
devfrom
archon/task-feat-workflow-marketplace-v0

coleam00 commented May 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 9, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

coleam00 commented May 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

UX Journey

Before

After

Architecture Diagram

Before

After

Label Snapshot

Change Metadata

Linked Issue

Validation Evidence (required)

Security Impact (required)

Compatibility / Migration

Human Verification (required)

Side Effects / Blast Radius (required)

Rollback Plan (required)

Risks and Mitigations

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coleam00 commented May 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 9, 2026 •

edited

Loading