Skip to content

AI-native design editor. Open-source Figma alternative.

12.6 KB
Raw Blame

Repo tooling, CI, and releases

Private tooling lives under tools/<role>/<domain>/{src,tests}; Steiger enforces the layout and kebab-case domain names. Every tool is a workspace named @open-pencil/<domain>-tools, listed literally in the root workspaces (the manifest schema rejects globs on purpose), so it can declare dependencies and run through bun --filter. bun run check:tools type-checks every tool through tools/tsconfig.json, reporting only files under tools/ as check:test-types does for tests (tools/checks/test-types/src/index.ts); bun run test:tools runs every tool with a test script. A tool imports its own files through its package.json imports alias (#ci/*, #release/*), other tools through their package name, and the docs site config through the shared #docs-config/* path.

Role Contract Domains
checks/ Read the tree and exit non-zero; never write inside the repository except an own baseline behind an explicit --write architecture, lint, i18n, secret-scan, type-shapes, docs, test-homes, package-quality
generate/ Write generated files or artifacts, idempotently brand, demo, emoji-metrics, tauri-menu, authoring-reference, visual-oracles, landing-posters
release/ Build, verify, and publish packages and native artifacts package-artifacts, release-packages
ci/ Consumed by workflows: path classification and gate policy, container images, the review-guidance bot policy, images, pr-review-guidance
dev/ Test running, benchmarks, and local services for humans unit-tests, navigation-benchmark, dev-server, cloud
  • Nothing under generate/ or release/ runs from bun run check except through a check entrypoint; generate/authoring-reference keeps its check.ts beside generate.ts until it splits.
  • Resolve the workspace with resolveWorkspaceRoot from @open-pencil/package-artifacts-tools, not parent-directory traversal. Keep sibling imports relative.
  • checks/test-homes owns engine-baseline.txt and check:test-homes; dev/unit-tests owns the shard map and runner (tests/AGENTS.md).
  • No scripts/ entrypoints: root package.json scripts call tool files directly.

CI

  • .github/workflows/ci.yml and heavy-tests.yml define validation gates. PR CI always classifies changed paths through tools/ci/policy/src/policy.ts: root docs, package READMEs, every AGENTS.md, packages/docs Markdown and assets, and skill Markdown are docs-only; runtime prompt Markdown, executable examples, configuration, and unknown paths require code validation.
  • Docs-only changes run documentation integrity and the docs build; everything else runs the full suites (tools/ci/policy/src/policy.ts).
  • The Cloud suites run when a change touches what packages/cloud is built from, derived from its workspace dependencies (tools/ci/policy/src/cloud-inputs.ts).
  • The aggregate CI result gate requires successful classification and every applicable job; failures, cancellations, and unexpected skips cannot pass (tools/ci/policy/src/gate.ts).
  • Do not restore workflow-level path filtering on required CI: a required check whose workflow never runs stays pending and blocks the merge (.github/workflows/ci.yml).
  • commitlint.config.ts enforces commit structure in the Commit messages job; the separate PR title workflow validates titles. Preserve the Release vX.Y.Z and Release vX.Y.Z-beta.N exception, including the (#N) the merge queue appends, and product casing when changing rules; the known AI co-author check does not rewrite base history. Gate policy lives in tools/ci/policy/src/policy.ts.
  • tools/ci/policy runs right after Bun is set up, before any install, so it imports only Node built-ins; oxlint.json switches open-pencil/prefer-es-toolkit off there. Other CI tools install their workspace first, as pr-review-guidance.yml does through .github/actions/setup-bun.
  • Required checks must also run on merge_group, the merge queue's event; read base and head from merge_group.base_sha/head_sha there (ci.yml, pr-title.yml).
  • Path classification measures a pull request from its merge commit's first parent, the base as it is now; pull_request.base.sha lags when the base moves and would count the base's newer commits as the pull request's (tools/ci/policy/tests/classify.test.ts).
  • A passing pull request run records the tree it tested as the CI verified tree status on the PR head; a merge queue commit with that exact tree is classified verified and runs only the always-on checks. Any other tree, including a group with other PRs ahead, gets the full run (tools/ci/policy/src/verified-tree/).
  • The app production workflow runs on v* tags, and the docs workflow when a release is published, since the download page reads GitHub's releases at build time; both also run on workflow_dispatch, never on ordinary master pushes. build.yml checks the tooling out under .pipeline/ and runs tools/release/release-packages from there.

Releases

  • Update versions in the root and publishable package manifests plus desktop/tauri.conf.json and desktop/Cargo.toml; run bun run changelog:assemble, curate Unreleased (bun run check:changelog --release), and move it into ## x.y.z — YYYY-MM-DD; commit Release vX.Y.Z; tag and push vX.Y.Z. A pre-release uses X.Y.Z-beta.N throughout.
  • .github/workflows/build.yml is the source of truth: v* tags (or dispatches for an immutable stable tag) build shared frontend/package outputs once, build signed desktop artifacts in parallel, verify and attest one complete same-run artifact set, publish npm packages, and replace the draft release assets using the exact changelog section. Policy, provenance, and recovery: tools/release/release-packages/README.md.
  • .github/workflows/chromium.yml builds OpenPencil Chromium (Tauri v3 with CEF), a flavor of a release, by hand from build/tauri-v3 once that branch has merged exactly the release tag, and adds its macOS bundles and latest-chromium.json, its update feed, to that release after every macOS build succeeds; stable tooling and the download page skip those files (isChromiumAsset). Its steps live in tools/release/release-packages/src/chromium, beside the stable release scripts they reuse.
  • Public workspace packages are discovered by the package-artifacts catalog. Bun source exports require the complete src directory in package contents; Node exports use dist. Release preparation must preserve resolution maps. Prepared publish directories receive the root LICENSE when a package has none of its own, and every package needs a README.md because npm renders it. Publishing uses prepared npm tarballs verified through the shared Node/Bun consumer checks; never publish package directories manually. test:packages first runs the packaging guards in tools/checks/package-quality/src/smoke/guards.ts: fixture manifests packed with the real npm pack that must trip the tarball inspector and the Node/Bun consumer checks before those checks vouch for real packages.
  • Pre-releases are only vX.Y.Z-beta.N: they publish to npm's next dist-tag, draft as a GitHub pre-release that is never latest, install on Windows as MSI X.Y.Z.N, and skip the app and docs deploys (tools/release/release-packages/src/version.ts).
  • A beta's changelog section opens with the pre-release note and lists changes since the previous beta. The final X.Y.Z replaces its beta sections with one section written against the previous stable release, opened by a short highlights paragraph, with fixes to new features folded into their bullets; the GitHub pre-releases keep the beta notes (CHANGELOG.md).
  • Official builds (VITE_OPENPENCIL_FEEDBACK=on) emit hidden source maps; app.yml and the build.yml frontend job inject PostHog chunk IDs, upload the maps to PostHog error tracking as release openpencil@<version>, and strip them from dist, and build.yml attaches them as OpenPencil_<version>_sourcemaps.tar.gz. Both need the POSTHOG_CLI_API_KEY secret, a personal key with error tracking write and organization read (tools/release/release-packages/src/sourcemaps/publish.ts).
  • Ensure Tauri and Apple signing/notarization secrets are configured. Verify the draft title, body, and artifacts, then publish. Release titles are exactly the tag (vX.Y.Z) without a product-name prefix.
  • Homebrew's openpencil cask is managed upstream: BrewTestBot proposes bumps and Homebrew merges them. Check the upstream cask PR after publication; do not push to the archived custom tap or add bump automation. Users install the app with brew install --cask openpencil and the CLI through npm or Bun.

Demo document

The /demo document is a tour of eight chapters on one page, each a section stacked top to bottom, built from tools/generate/demo/src/document/: theme.ts (the Theme and App chrome collections, each with a Dark and a Light mode that src/app/demo/theme.ts switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), callout.tsx (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from chrome.tsx, drawn to the dark theme's tokens with the target ringed), player/ (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under chapters/, laid out by chapters/chapter.ts as numeral, heading, subject, and tip, with each section's and subject's name from chapters/names.ts, which hosts outside the app such as the docs landing import from @open-pencil/demo-tools/chapters; src/app/demo/viewport.ts opens the tour on the first chapter. It renders design JSX through document/icons.ts, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored public/demo.fig, which the app opens like any .fig file; it is never generated in the browser. ensureDemoDocument runs from vite.config.ts, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; bun run generate:demo forces it. A chapter that needs something new from the engine adds that package's src to the fingerprint in tools/generate/demo/src/ensure.ts. Shader fills get their still frames from src/shaders/stills.ts, which draws each preset in the Playwright Chromium with WebGPU, at the size and in the encoding the editor uses (shaderFramePixels and shaderFrameEncoding from scene-graph) (bunx playwright install chromium locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.

Landing posters

tools/generate/landing-posters/ captures WebP stills of every docs landing stage, per locale, theme, and layout, from a production docs build served locally in headless Chromium with software WebGL. build:production in packages/docs runs it after vitepress build; it reuses .cache/landing-posters/<fingerprint> when the inputs in src/fingerprint.ts are unchanged and copies the stills into dist, and generate:landing-posters forces a capture. The docs deploy workflow spreads the capture over runners: one job runs build:site, four run the generator with --shard i/4, and the deploy job gathers their stills and runs it with --assemble, which fails on any missing still; dispatching it with dry-run builds and captures without deploying and keeps the stills as an artifact. A stage that starts depending on a new source tree adds it to LANDING_POSTER_INPUTS.

Brand assets

Canonical artwork lives in assets/brand/ (main mark and optical micro master; see its README). tools/generate/brand/ derives web, docs, and native icons with RealFaviconGenerator and Tauri; generated assets are ignored, not committed. Vite and VitePress configs prepare their own targets, and Tauri dev/build hooks prepare native icons.