CLI Operations

Workspace

packages/cli        Go CLI and public Go package
packages/npm        npm wrapper for release binaries
packages/viewer     browser viewer and embedded CLI assets
packages/extension  experimental local MCP App and plugin
Wiki                canonical CLI documentation

The root package.json owns the release version and workspace commands. Go builds use the Go 1.26.9 security baseline. The viewer package and npm wrapper require Node 20 or a later version. The experimental extension requires Node 22 or a later version.

Local development

pnpm install --frozen-lockfile
pnpm test
pnpm build

pnpm test runs all policy checks. It also runs installer, viewer, CLI, and extension unit tests. Use Node 22 or a later version for this complete suite. The experimental extension has additional build and host checks:

pnpm --filter @openknowledge-sh/extension test
pnpm --filter @openknowledge-sh/extension build
pnpm --filter @openknowledge-sh/extension package:local

The local package includes runtime and CLI binaries for the build host. It is not part of the CLI release archives or npm wrapper. See the extension prototype for native host checks and current limitations.

Use pnpm dev:viewer -- Wiki when you change files in packages/viewer/src/viewer. Vite updates CSS without a restart. It reloads the page when a JavaScript change requires a full reload. Set OPENKNOWLEDGE_VIEWER_DEV_PORT to select the Vite port.

Continuous integration

.github/workflows/ci.yml runs for pull requests, main, and manual dispatch. It uses read-only repository permissions. It cancels a run when a newer run replaces it. The workflow does these tasks:

1. Install frozen Go, Node, and pnpm dependencies.
2. Verify tidy Go modules.
3. Verify Go formatting.
4. Run the policy and unit test suite.
5. Run the race detector, coverage report, and go vet.
6. Build the CLI and embedded viewer.
7. Test viewer journeys in Chromium.
8. Validate Wiki/ with the built binary.
9. Reject tracked viewer build output.
10. Build viewer assets before Go tests on Linux, macOS, and Windows.
11. Run CLI tests and builds on Linux, macOS, and Windows.
12. Verify npm and viewer behavior on Node 20.
13. Verify an installed packed artifact on Node 20.

Require the CI / verify check in branch protection.

Security automation runs for pull requests, main, and schedules. .github/workflows/security.yml and .github/dependabot.yml define this automation. It covers Go and JavaScript CodeQL, govulncheck, and checksum-verified OSV Scanner. It also covers npm, Go modules, Actions, and Docker. Results can change when vulnerability databases change.

Viewer and website boundaries

packages/viewer owns the local viewer and static HTML viewer assets. Vite builds the JavaScript and CSS from packages/viewer/src/viewer. Vite writes these files directly into the ignored Go embed directory. Commands that build or test the CLI generate these files first. Git does not track compiled viewer files.

pnpm build runs pnpm build:cli, which builds the viewer before the Go binary. The CLI release includes the embedded viewer.

The marketing website belongs to the separate openknowledge-website project. That project owns website pages, analytics, its telemetry relay, and deployment. It also owns publication of documentation, example, and schema snapshots. The product repository retains canonical Wiki/, examples/, and CLI schemas. Product builds and releases do not build or deploy the website.

Release

Run the manual workflow from the current default-branch tip:

Actions → Release → Run workflow → version: 0.14.0

The version input accepts 0.14.0, v0.14.0, or a prerelease such as v0.14.0-rc.1. The workflow serializes release runs and does not cancel an active release.

Before the workflow starts, move the release content from ## Unreleased to a dated changelog section. Keep ## Unreleased above it with No changes yet.

The verify job requires the current default-branch tip. It then completes these tasks before any repository write:

1. Update the root, npm, and Go fallback versions.
2. Install frozen dependencies and verify version alignment.
3. Extract the matching dated changelog section as release notes.
4. Verify tidy Go modules, Go formatting, policy checks, tests, and builds.
5. Run race tests, go vet, and Chromium browser journeys.
6. Build the release binary and validate Wiki/ with that binary.
7. Install the packed npm artifact in an isolated test project.
8. Build and inspect a six-archive GoReleaser snapshot.
9. Verify NPM_TOKEN with the npm registry.

Parallel release jobs run CLI tests on macOS and Windows. A separate security job runs govulncheck and OSV Scanner. All release jobs must pass before the version commit.

The commit_release job applies the same version update to the verified source. It pushes a version commit only when the tracked version files change. The publish_release job checks out that exact commit and prepares the release tag. It reuses the tag only when the tag already points to that commit.

The publication job rebuilds viewer assets before GoReleaser runs. GoReleaser publishes six archives, checksums, licenses, the installer, and the prepared release notes. The workflow attests the archives from dist/checksums.txt.

The final npm job checks out the release tag. It verifies the package version before it publishes the wrapper with npm provenance. Stable releases use the npm latest tag. Prereleases use the next tag.

Only commit_release and publish_release receive repository write access. Only publish_release receives attestation access. The publication and npm jobs receive only their required OIDC access.

Deployable projects build a pinned runtime from the committed .openknowledge/runtime/Dockerfile. Releases do not publish role images.

Use this command to verify an archive:

gh attestation verify openknowledge_darwin_arm64.tar.gz \
  -R openknowledge-sh/openknowledge

The required external controls are NPM_TOKEN and default-branch protection. A tag ruleset must limit v* creation to the release workflow.