local-cli-development.md

Local CLI Development

This document explains how to run the current checkout as the Wiki Graph CLI during development.

It covers two different workflows:

• install the current branch as the machine-level wg command;
• run the current branch through pnpm without installing it.

Use the pnpm workflow for day-to-day development and regression checks. Use the install workflow only when you explicitly need to preview the packaged CLI as a global command.

Install The Current Branch

Use this workflow when you want the current branch to behave like an installed release:

pnpm cli:install-local

This builds and globally installs the CLI together with its local workspace package dependencies, so unpublished workspace versions are used consistently.

The script builds the workspace, packs all five publishable workspace packages, then installs their tarballs together through npm install --global --force. After it finishes, wg and wikigraph resolve through the machine-level global installation without requiring unreleased package versions from the registry.

This workflow is useful for:

• previewing an unreleased version outside the repository;
• checking package contents, dist output, shebangs, and bin entries;
• testing how a normal user will experience the CLI after installation.

This workflow previews the complete local CLI dependency graph. Applications should use wiki-graph-sdk, rather than the CLI runner, for typed programmatic access.

It is not the default regression workflow for agents or parallel worktrees. A global install is shared by all shells and worktrees on the same machine, so one checkout can replace the wg command used by another checkout.

Remove the global preview install with:

pnpm cli:uninstall-local

Run Without Installing

Use this workflow for normal development, local regression checks, and agent worktree runs:

pnpm --filter wiki-graph dev --help
pnpm --filter wiki-graph dev wikg://book.wikg --help
pnpm --filter wiki-graph dev help uri

Do not add an extra argument separator after dev. For this package, write:

pnpm --filter wiki-graph dev wikg://book.wikg --help

Do not write:

pnpm --filter wiki-graph dev -- wikg://book.wikg --help

The extra -- is passed to the CLI and changes the parsed command.

Development State Directory

The installed CLI stores local runtime state under ~/.wikigraph. The development CLI entry point runs with a development entry policy and passes the repository-level .wikigraph/state directory through the explicit runtime context instead. Do not set Wiki Graph runtime environment variables manually; use the pnpm dev script so child processes such as build workers and GC use the same checkout-local state.

Use repository-root .wikigraph/ for local development data:

mkdir -p .wikigraph/state .wikigraph/out .wikigraph/input
pnpm --filter wiki-graph dev --help

pnpm --filter wiki-graph dev runs the package script from packages/cli. When you want an archive under the repository-level .wikigraph/out/ directory, pass an absolute wikg:// URI based on the repository root:

pnpm --filter wiki-graph dev "wikg://$PWD/.wikigraph/out/regression.wikg" --help

Recommended subdirectories:

• .wikigraph/state/: runtime state, cache, queue, logs, and temporary files;
• .wikigraph/out/: generated .wikg archives and exported regression output;
• .wikigraph/input/: private or temporary local input files.

Remove all local development data with:

pnpm cli:clean-dev-state

This deletes repository-root .wikigraph/, including .wikigraph/state/, .wikigraph/out/, and .wikigraph/input/. It does not affect the installed CLI's machine-level ~/.wikigraph directory.

For repeated shell use, define a local helper from the repository root:

wg-dev() {
  pnpm --filter wiki-graph dev "$@"
}

Then run:

wg-dev --help
wg-dev "wikg://$PWD/.wikigraph/out/regression.wikg" inspect

Choosing The Workflow

Use pnpm without installing when validating source changes, CLI behavior, help text, archive operations, state handling, or bug fixes in the current checkout.

Pull-request checks use the faster test entry point:

pnpm test:pr

Tests that exercise large durable fixtures, repeated archive settlements, or full index rebuilds live under full-regression/ and use the .full-regression.test.ts suffix. They are included in the daily main-branch regression run:

pnpm test:full-regression

The full regression workflow also runs the packed CLI E2E suite. It runs once per day and exits before running tests when main has no commit dated that day.

Use the install workflow only when the question is about the packaged command itself: global wg resolution, package layout, dist artifacts, executable metadata, or previewing an unreleased branch outside this repository.

When validating package installation boundaries, use the pack smoke workflow:

pnpm smoke:pack-install

For a black-box regression of the built and packed command, run:

pnpm test:e2e

The E2E suite packs the workspace packages, installs only wiki-graph as the temporary consumer project's direct dependency, and invokes only that project's wg executable. A separate bootstrap project supplies SDK-only test setup without changing the CLI consumer dependency graph. Package installation prefers pnpm's existing store and fetches metadata or packages that a clean runner is missing. Every case receives a separate temporary home, working directory, state directory, and archive. External LLM, WikiSpine, and Wikimedia calls are served by strict local protocol mocks. The suite neither reads ~/.wikigraph nor replaces a machine-level wg installation, and it removes its temporary installation and case data after the actual detached-worker leases are released.

When the workspace is already built, use pnpm test:e2e:run to skip the build.

That workflow separately packs and installs wiki-graph-core, wiki-graph-sdk, and wiki-graph in temporary projects so it can validate Core-only, SDK-only, and CLI installation scenarios. For manual tarball inspection, build first and pack the three packages explicitly:

pnpm build
pnpm --filter wiki-graph-core pack --pack-destination /tmp/wiki-graph-packs
pnpm --filter wiki-graph-sdk pack --pack-destination /tmp/wiki-graph-packs
pnpm --filter wiki-graph pack --pack-destination /tmp/wiki-graph-packs

Related Maintainer Docs

• Schema Upgrade Maintenance: how archive/home schema gates, version bumps, upgrader tests, and persistent-state boundaries are maintained.