ShipOS — The Universal Submission Engine

Repository · Issues · Pull requests · Looping GIF · MP4 teaser · Captions

Overview

ShipOS helps developers turn a GitHub repository into a launch or submission kit. It audits repository evidence, drafts a README and optimization assets, and prepares demo material. The full package records whether claims are verified, partial, or rejected. The Proof Ledger links this README's main capability claims to source files.

The problem

Preparing a project for launch means turning repository details into clear documentation, proof, and media. That work is easy to repeat across tools, and unsupported claims can make their way into the final package.

The solution

Start with a repository URL for the live engines or run GitHub Workbench on local evidence. ShipOS puts repository auditing, launch assets, developer utilities, and demo production in one workspace.

Contents

• Features and modes
• Quick start, environment variables, and troubleshooting
• Architecture, project structure, and tech stack
• Available scripts and API examples
• Testing and continuous integration, deployment, and security
• Repository statistics, commit intelligence, and development history
• Why this repository, proof ledger, and roadmap
• FAQ, support, and contributing
• Changelog, acknowledgments, star history, and license

Features and modes

Mode	What it does	Implementation
GitHub Workbench	40 evidence checks, 30 launch assets, and 30 runnable utilities. Exports a profile README, banner previews, and launch files. The local CLI produces GIF, MP4, and WebVTT media.	Workbench guide
Full Package	Creates a README, demo script and storyboard, pitch deck, project report, viva prep, compliance checklist, claim ledger, and export bundle. Includes SEO and repo health scores.	Pipeline
Full Repo Auditor	Runs 50 deterministic checks, assigns an S–F grade, and returns ranked fixes with code. Categories are docs (25 points), code quality (25), security (20), DevOps (15), and community (15). Supports strictness levels and a zero-network file-list scan.	Audit rules
Optimization Engine	Measures SEO, AEO, and GEO signals on a 0–100 scale. Its 54-point review pack includes description, topics, agents.txt, llms.txt, FAQ, JSON-LD, AI crawler guidance, and launch copy. Apply changes and rerun to measure results.	Optimizer
Demo Maker	Creates a 10-act film plan for 60, 150, or 300 seconds, with a brief, captions, and a scene editor. Uses an LLM-written voiceover script when available, with a deterministic fallback. Exports browser video and caption files or hands off to Render Cloud.	Demo engine
README Upgrader	Audits a README across eight categories, produces an upgraded draft, and reports its score under the README rubric.	Upgrader
Video Studio (Path A)	Plays an editable cinematic scene schema on a canvas and exports WebM or MP4, depending on browser support. Keep the tab visible during export.	Video Studio
Render Cloud (Path B)	Models a 4K workflow and its 300 GPU-second daily budget. Exports a Hugging Face Space bundle for GPU-assisted voiceover, banners, and captions, with Remotion and FFmpeg render steps. The app tracks progress through a time-based job simulation.	Render worker · Deployment bundle
Competitor Radar	Bundled November 8 snapshot of 15 repo-to-video tools, five categories, an 11-capability matrix, four patterns, and six roadmap opportunities.	Competitor data
Model Radar	Browsable bundled catalog of open and free model options, with capability filters.	Model data
PRO	Demo tier for the 4K render flow, audit schedule records, team seats, and API-key management for /api/v1/audit.	PRO API · Public audit API
Evidence engine (P0)	Builds an Engineering Index quality profile (proposed weights, no silent points), GitHub security and workflow intelligence, and acceptance gates G0, G6, and G7. Untested gates stay NOT_VERIFIED.	Evidence engine · CLI · API

Publishing media

The banner above is the committed 1280 × 640 PNG. The repository also includes an SVG banner, the GIF, the MP4 teaser, and WebVTT captions. The Workbench guide explains how to create your own media and publish it with a profile README or GitHub social preview. An alternate capsule banner is available for the same project.

Quick start

Open the hosted Workbench for browser audits, launch kits, utilities, and media. The local setup below runs the full Next.js app and its server-backed modes.

Use Git, Node.js 24, and Bun 1.3.4, matching CI. The CLI media commands also require FFmpeg with librsvg and libx264.

git clone https://github.com/CodesbyFebin/Ship-Repo-OS.git
cd Ship-Repo-OS

bun install --frozen-lockfile
cp .env.example .env
mkdir -p prisma/db && touch prisma/db/custom.db
bun run db:push
bun run dev

Open http://localhost:3000 and select GitHub Workbench. To use it from the terminal, run node scripts/workbench.mjs --help or bun run workbench --help.

Usage examples

# Audit a local checkout, then generate a launch pack for review.
node scripts/workbench.mjs audit .
node scripts/workbench.mjs pack --repo CodesbyFebin/Ship-Repo-OS --against . --out ./local-launch-pack

# Try one of the 30 utilities.
node scripts/workbench.mjs tool semver-bump --input "1.1.0 minor"
# 1.2.0

See the Workbench guide for evidence inputs, score calculation, exports, and media commands.

Environment variables

Variable	Use	Required
DATABASE_URL	Prisma SQLite database. The sample value is file:./db/custom.db. Use an absolute SQLite path for standalone deployment.	For the server
GITHUB_TOKEN	Optional token used by the GitHub scraper for authenticated API requests. Keep it server-side.	No
OPENAI_API_KEY	Listed as an optional example in .env.example. The current LLM bridge initializes the ZAI SDK.	No
SHIPOS_ADMIN_TOKEN	Protects /api/apikeys. Requests must send the token as x-shipos-admin-token or Authorization: Bearer <token>. If unset, those routes return 503.	To manage API keys
SHIPOS_EVIDENCE_HMAC_KEY	Optional HMAC key used to sign evidence receipts. Receipts still include a content hash when this is unset.	No

Troubleshooting

Symptom	Likely cause	Fix
command not found: bun	Bun is unavailable	Install the CI-pinned version and rerun setup.
Install returns EACCES	A global install needs elevated privileges	Run the project scripts with a user-local Bun installation.
Startup reports a missing variable or SQLite file	Local configuration or database setup is incomplete	Copy .env.example, create the default SQLite path, and run bun run db:push.
CI fails while the local run passes	Runtime or dependency drift	Match the CI versions and commands and use a frozen install.
Port 3000 is in use	Another process is listening	Stop that process or run bunx next dev -p 3001.

Architecture

flowchart TD
  UI["React / Next.js app"] --> API["Job APIs"]
  UI --> Local["Offline Workbench"]
  API --> Ingest["GitHub ingestion"]
  Ingest --> Audit["Audit and claim verification"]
  Audit --> Pack["Launch artifacts"]
  Audit --> Demo["Demo schema"]
  Demo --> Render["WebM or render bundle"]
  API --> ORM["Prisma / SQLite"]

Loading

Live ingestion retries transient failures with exponential backoff. When ingestion fails and a previous snapshot is available, ShipOS labels that evidence as a snapshot. A GitHub 404 is returned as a repository error. The full package uses the resulting evidence to build its claim ledger and exports.

The audits run deterministically. LLM-assisted demo scripts and the optimization pack can fall back to templates when the LLM is unavailable.

Design notes

• TypeScript-first. Use the shared contracts and let the type checker catch interface drift.
• Locked dependencies. Use the committed Bun lockfile for repeatable installs.
• Typed storage. Use the Prisma schema for data-model changes and document how to apply them.
• Tests and CI. Use the regression tests and workflow when changing behavior or diagnosing a build.

Project structure

Path	Role
src/app/	App Router pages and API routes for shipping, projects, audit, optimization, demos, render jobs, upgrades, PRO, schedules, teams, API keys, and feedback.
src/lib/shipos/	Repository ingestion, scoring, fixes, generators, provenance, optimizer, demo engines, render worker, and radar catalogs.
src/lib/shipos/workbench/	Evidence checks, launch pack, and utilities shared by the app and CLI.
src/components/shipos/ · src/ui/	Mode interfaces and the dark-first Material 3-inspired component kit.
prisma/ · scripts/ · tests/	SQLite schema, CLI, and regression tests.
docs/ · public/ · examples/websocket/ · mini-services/	Guides, media, static assets, a WebSocket example, and a reserved service directory.
Caddyfile · package.json · bun.lock	Reverse-proxy example, package manifest, and dependency lockfile.

Tech stack

Area	Technology
Application	Next.js 16.4.6 App Router, React 19, TypeScript 5, and JavaScript
UI and client state	Tailwind CSS 4, Radix UI, TanStack Query, Framer Motion, and the local component kit
Data and validation	Prisma 6, SQLite, and Zod 4
Development and CI	Node.js 24, Bun 1.3.4, ESLint, Node test runner, and GitHub Actions
Media and exports	Canvas, MediaRecorder, JSZip, FFmpeg, and the Remotion-based render bundle

Available scripts

Run each script as bun run <script>. See package.json for its exact definition.

Script	Command or purpose
dev	next dev -p 3000
build	Runs next build and copies static assets into the standalone bundle.
start	node .next/standalone/server.js
test	node --test tests/*.test.mjs
test:coverage	Runs the regression tests and reports coverage for the shared Workbench modules.
audit	Runs Bun’s dependency audit for high and critical advisories.
typecheck	tsc --noEmit
lint	eslint .
lint:workbench	ESLint for the Workbench UI, shared modules, and CLI scripts.
db:push	prisma db push
db:generate	prisma generate
db:migrate	prisma migrate dev
db:reset	prisma migrate reset. This resets the configured database.
workbench	node scripts/workbench.mjs
evidence	node scripts/evidence.mjs

API examples

# Full package
curl -X POST http://localhost:3000/api/ship \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/honojs/hono","preset":"meta-hackathon"}'

# Full repo audit
curl -X POST http://localhost:3000/api/audit \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/honojs/hono","strictness":"balanced"}'

# Five-minute demo film
curl -X POST http://localhost:3000/api/demo \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/honojs/hono","targetSeconds":300,"style":"launch"}'

# Optimization pack
curl -X POST http://localhost:3000/api/optimize \
  -H 'content-type: application/json' \
  -d '{"repoUrl":"https://github.com/honojs/hono"}'

# Evidence engine (quality profile, optional URL fetches, artifact hashes, receipt)
curl -X POST http://localhost:3000/api/v1/evidence \
  -H 'content-type: application/json' \
  -d '{"action":"profile","snapshot":{"files":{"README.md":"# Example"}}}'

Evaluate a local checkout with node scripts/evidence.mjs suite --root .. Gate G0 also accepts --repo-url and --live-url. Artifact verification is node scripts/evidence.mjs g6 --sums SHA256SUMS --dir ./dist.

Job creation returns { ok, id }. Poll GET /api/projects/:id for a full package. For the other examples, poll GET /api/audit/:id, GET /api/demo/:id, or GET /api/optimize/:id and read status and stage. Download a finished full package at GET /api/projects/:id/export.

/api/v1/audit accepts x-api-key: skos_.... Managing those keys requires SHIPOS_ADMIN_TOKEN:

# List masked keys
curl http://localhost:3000/api/apikeys -H "x-shipos-admin-token: $SHIPOS_ADMIN_TOKEN"

# Create a key (the full secret is returned only in this response)
curl -X POST http://localhost:3000/api/apikeys   -H "x-shipos-admin-token: $SHIPOS_ADMIN_TOKEN"   -H "content-type: application/json"   -d '{"label":"ci-bot"}'

After pulling this schema change, run bun run db:push. If a previous database still has plaintext keys, run node scripts/migrate-apikeys.mjs (or let /api/v1/audit hash a legacy key on first successful use).

Testing and continuous integration

bun run test:coverage
bun run lint:workbench
bun run typecheck
bun run audit

The Repository checks workflow runs on pushes and pull requests and supports manual runs. It installs locked dependencies, generates the Prisma client, tests and lints Workbench, checks types, and builds the standalone app on Node.js 22 and 24. A container smoke test exercises a fresh SQLite volume. The dependency audit is a separate command and can report advisories even when the build passes. See current runs and the release review for the original verification and lint scope.

Deployment

Run bun run build && bun run start for the standalone Node.js build. Set the same absolute DATABASE_URL during schema setup and at runtime, and use a writable persistent volume for SQLite. The included Caddyfile is a reverse-proxy example. For the 4K render workflow, use the separate export from Render Cloud.

For a local container deployment, run docker compose up --build --wait. Compose applies the Prisma schema in a one-time initialization service, stores SQLite in a named volume, and publishes the app on 127.0.0.1:3000. Stop it with docker compose down to keep the data volume.

To publish a GitHub release, dispatch the release workflow against an existing stable vX.Y.Z tag that matches package.json.

Security

Run the server as a trusted single-instance demo. The shared job, project, and demo license APIs require an authentication and authorization layer for public multi-tenant use. /api/apikeys is an exception: it requires SHIPOS_ADMIN_TOKEN and never lists full key material. Keep live credentials out of source control and report vulnerabilities privately using the security policy.

Repository statistics

Metric	Where to check
Stars and forks	Live badges above or the GitHub repository. The supplied November 10 snapshot recorded zero of each.
Commit count and contributors	Main history and the dated snapshot below.
Languages	The supplied November 10 snapshot reported 71% TypeScript and 29% JavaScript. See the repository language breakdown for current figures.
Automation and tests	CI, CodeQL, tagged releases, and the Workbench regression suite.
License	MIT.

Commit intelligence

The November 10, 2026 snapshot at 724a8c7 contains 18 commits: eight dependency PR merges, eight Dependabot update commits, and two initial ShipOS commits. None of those 18 commit subjects uses a Conventional Commit prefix. The original snapshot did not resolve authors. The list below uses the repository's public commit author records.

Recent development history

Show the 18 commits in the November 10 snapshot

Commit	Type	Message	Author	Date
724a8c7	Merge	Merge pull request #8 from CodesbyFebin/dependabot/bun/radix-ui/react-dropdown-menu-2.2.1	Febin Francis	2026-11-10
4d4b01b	Merge	Merge pull request #6 from CodesbyFebin/dependabot/bun/radix-ui/react-toggle-1.2.1	Febin Francis	2026-11-10
54afe5c	Dependency update	Bump @radix-ui/react-toggle from 1.1.10 to 1.2.1	dependabot[bot]	2026-11-10
40985a4	Dependency update	Bump @radix-ui/react-dropdown-menu from 2.1.16 to 2.2.1	dependabot[bot]	2026-11-10
54d1a8a	Merge	Merge pull request #7 from CodesbyFebin/dependabot/bun/zustand-5.1.0	Febin Francis	2026-11-10
9367127	Merge	Merge pull request #5 from CodesbyFebin/dependabot/bun/radix-ui/react-progress-1.2.1	Febin Francis	2026-11-10
4e68a0c	Merge	Merge pull request #4 from CodesbyFebin/dependabot/bun/next-auth-4.24.15	Febin Francis	2026-11-10
96f73d5	Merge	Merge pull request #3 from CodesbyFebin/dependabot/bun/input-otp-1.5.0	Febin Francis	2026-11-10
305714c	Merge	Merge pull request #2 from CodesbyFebin/dependabot/github_actions/actions/setup-node-7.1.0	Febin Francis	2026-11-10
95481e2	Merge	Merge pull request #1 from CodesbyFebin/dependabot/github_actions/actions/checkout-7.0.1	Febin Francis	2026-11-10
ad18c3a	Dependency update	Bump zustand from 5.0.10 to 5.1.0	dependabot[bot]	2026-11-10
8c71bf2	Dependency update	Bump @radix-ui/react-progress from 1.1.8 to 1.2.1	dependabot[bot]	2026-11-10
8dbdc84	Dependency update	Bump next-auth from 4.24.13 to 4.24.15	dependabot[bot]	2026-11-10
b0d6225	Dependency update	Bump input-otp from 1.4.2 to 1.5.0	dependabot[bot]	2026-11-10
45894fd	Dependency update	Bump actions/setup-node from 4.4.0 to 7.1.0	dependabot[bot]	2026-11-10
c5b11cf	Dependency update	Bump actions/checkout from 4.2.2 to 7.0.1	dependabot[bot]	2026-11-10
f5f3040	Project setup	Ship ShipOS 1.1.0 and GitHub Workbench	Febin Francis	2026-11-10
7830904	Project setup	Initialize ShipOS repository	Febin Francis	2026-11-10

Why this repository

Need	What ShipOS provides
Repeatable setup	A frozen install, documented SQLite setup, and a local CLI.
Traceable results	Source-linked evidence, deterministic checks, and a claim ledger in the full package.
Reviewable launches	One workbench for docs, settings recommendations, scripts, and media drafts.
Open development	Public history, CI results, issues, and pull requests.

Proof ledger

This table is also the citable facts index for the project. Sources point to the implementation or repository records.

Claim	Evidence
The project uses TypeScript, React, Next.js, and Prisma.	Manifest · TypeScript configuration · Prisma schema
Workbench provides 40 checks, 30 launch assets, and 30 utilities.	Checks · Assets · Utilities · Catalog tests
The repository auditor scores 0–100 and provides ranked fixes.	Audit rules · Fix library
The full package includes an evidence ledger.	Provenance verifier · Package pipeline
Demo Maker prepares voiceover scripts and film scenes.	Demo engine · Demo runner
The optimization pack provides SEO, AEO, and GEO guidance.	Optimizer · Catalog
The repository has CI, automated tests, and an MIT license.	Workflow · Tests · License
The repository is public and has a traceable development history.	Repository · Snapshot commit

Audit trail and claim limits

The attached snapshot described its own generated claims as verified. This merged README links directly to the relevant source. It treats star and fork counts as a dated snapshot, uses live badges for current values, and describes 4K rendering as an exportable workflow with an in-app simulation. It also keeps repository readiness scores separate from optimizer drafts and omits the unsupported claim that the codebase reads every environment variable listed in the example.

Roadmap

See the Competitor Radar for product opportunities and the release review for the remaining verification and deployment work identified in ShipOS 1.1. Track proposed milestones in GitHub Issues.

FAQ

What can I run without the server?

Run the Workbench CLI on a local Git checkout for audits, launch packs, and utilities. The media command needs FFmpeg. Open the web app to use Video Studio or the server-backed modes.

Is ShipOS free?

The source is available under the MIT License. Browser WebM export and the offline tools run locally. Third-party rendering, model services, or hosting are subject to their own terms and quotas. The PRO checkout in this repository is a demo.

How do I verify the figures in this README?

Use the Proof Ledger for code and capability claims, the badges and GitHub Actions for live signals, and the dated commit table for the historical snapshot.

Support and community

See SUPPORT.md for help. Open an issue with reproduction steps and versions for a bug, or explain the problem and desired outcome for a feature request. Use the private reporting route described in SECURITY.md for vulnerabilities.

Contributing

Fork the repository, create a branch such as feat/your-feature, and run the relevant checks. Use descriptive commit subjects such as feat:, fix:, or docs:, and include verification results when you open a pull request. See CONTRIBUTING.md and the code of conduct.

Changelog

See CHANGELOG.md for release notes and the GitHub commit history for changes after the latest changelog entry.

Acknowledgments

Thanks to the project contributors and Dependabot for the dependency updates recorded in the project history.

Star history

Star the repository · Fork

License

MIT. See LICENSE.