### Run WPMoo Toolkit Guided Wizard

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Execute the guided wizard to set up a new Odoo project environment. This is the primary way to start a new project.

```bash
npx @wpmoo/toolkit
```

--------------------------------

### Install GitHub CLI

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Install the GitHub CLI using Homebrew. This is optional and used for repository inspection or creation.

```bash
brew install gh
gh auth login
```

--------------------------------

### Navigate to Environment and Open Cockpit

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

After project setup, change into the generated environment directory and launch the WPMoo cockpit. The default environment folder is `./<product>_dev`.

```bash
cd <product>_dev
./moo
```

--------------------------------

### Install Agent Skills Package

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Install the generic `@wpmoo/odoo-skills` package as a standalone Pi package.

```bash
pi install npm:@wpmoo/odoo-skills
```

--------------------------------

### getSystemPrerequisiteStatus(options) / renderSystemPrerequisiteGuidance(status)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Checks for required tools like Node.js, Git, and Docker before environment setup and provides guidance if checks fail.

```APIDOC
## getSystemPrerequisiteStatus(options) / renderSystemPrerequisiteGuidance(status)

### Description
Verifies the availability of essential tools such as Node.js 20.17+, Git, Docker Desktop, Docker Compose, and Docker Engine prior to initiating environment setup. `renderSystemPrerequisiteGuidance` can be used to display user-friendly messages based on the status.

### Usage Examples

```typescript
import { getSystemPrerequisiteStatus, renderSystemPrerequisiteGuidance } from '@wpmoo/toolkit';

const status = await getSystemPrerequisiteStatus();

if (!status.ok) {
  console.log(renderSystemPrerequisiteGuidance(status));
  // Output example:
  // Required tools before environment setup starts
  //
  // ✓ Node.js 20+           ok
  // ✓ Git                   ok
  // ✕ Docker Desktop        ↗ https://www.docker.com/products/docker-desktop/
  // Docker Desktop is installed, but Docker Engine is not running.
  // Start Docker Desktop, then check again.
  process.exit(1);
}

// status.checks: SystemPrerequisiteCheck[]
// status.issues: SystemPrerequisiteIssue[]  — only failing tools
```

**Simulating missing tools in tests:**
```bash
WPMOO_TEST_MISSING_TOOLS=docker,git npx @wpmoo/toolkit
```
```

--------------------------------

### Install Agent Skills Locally with npx

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Perform a project-local installation of the `@wpmoo/odoo-skills` package using npx, specifying a target directory.

```bash
npx @wpmoo/odoo-skills --target /path/to/project
```

--------------------------------

### Install and Run WPMoo Toolkit CLI

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Use npx to run the WPMoo Toolkit. It launches an interactive wizard for new environments or a cockpit for existing ones. Options include skipping update checks and showing help or version information.

```bash
npx @wpmoo/toolkit

npx wpmoo
npx @wpmoo/odoo
npx @wpmoo/odoo-dev

npx @wpmoo/toolkit --help

npx @wpmoo/toolkit --version

npx @wpmoo/toolkit --no-update-check
```

--------------------------------

### Install and Execute New Odoo CLI Package

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/compat/odoo-dev/README.md

Use this command to install and execute the new WPMoo Odoo CLI package, replacing the deprecated @wpmoo/odoo-dev.

```bash
npx @wpmoo/odoo
```

--------------------------------

### Run Vitest Test - Bash

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-generated-environment-verification-matrix.md

Command to execute a specific Vitest test file. Ensure Vitest is installed in your project.

```bash
npx vitest run test/generated-environment-scaffold.test.ts
```

--------------------------------

### Manage WPMoo Toolkit Services via Command

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Execute these commands for scripted workflows within automation or CI pipelines, including starting services, updating modules, running tests, and creating snapshots.

```bash
./moo start
```

```bash
./moo update <module>
```

```bash
./moo test <module>
```

```bash
./moo snapshot
```

--------------------------------

### WPMoo Toolkit Daily Actions: Services

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Commands for managing Docker Compose services within a WPMoo environment. Use these to start, stop, restart, and view logs for your Odoo containers.

```bash
# ── Services ──────────────────────────────────────────────────────────────────
./moo start                          # docker compose up -d
./moo stop                           # docker compose down
./moo restart                        # restart all containers
./moo logs                           # tail odoo logs (default service: odoo)
./moo logs odoo                      # tail a specific service
./moo shell                          # open shell inside the odoo container
```

--------------------------------

### WPMoo Toolkit Daily Actions: Module Management

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Commands for installing, updating, testing, and linting Odoo modules within your WPMoo environment. Also includes generating translation files.

```bash
# ── Modules ───────────────────────────────────────────────────────────────────
./moo install sale,crm               # install modules
./moo install sale devel             # install into a specific database
./moo update sale                    # update a module
./moo update sale,crm devel          # update into a specific database
./moo test sale                      # run Odoo tests for a module
./moo test sale --db devel --mode auto --tags base_setup   # advanced test options
./moo lint                           # run flake8/pylint on all source repos
./moo pot my_module                  # generate .pot translation file
```

--------------------------------

### Get Environment Status (Human-readable)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Checks the health of your WPMoo development environment. This command provides a human-readable overview of the environment's status.

```bash
# Human-readable status
npx @wpmoo/toolkit status
```

--------------------------------

### Get Environment Status (JSON Output)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Retrieves detailed environment health information in JSON format, suitable for programmatic consumption or CI pipelines. Includes details on Odoo version, source repositories, and potential issues.

```bash
# Machine-readable JSON output
npx @wpmoo/toolkit status --json
# Output:
# {
#   "schemaVersion": 1,
#   "command": "status",
#   "ok": true,
#   "status": {
#     "kind": "environment",
#     "target": "/workspace/my_product_dev",
#     "metadataPath": ".wpmoo/odoo.json",
#     "odooVersion": "18.0",
#     "sourceRepoCount": 2,
#     "sourceRepoPaths": ["my_product", "my_product_pro"],
#     "invalidSourceRepoPaths": [],
#     "moduleCandidateCount": 14,
#     "composeFiles": ["docker-compose.yml"],
#     "composeErrors": [],
#     "missingCoreFiles": [],
#     "recommendedNextAction": "Run npx @wpmoo/toolkit doctor for deep checks or ./moo start."
#   }
```

--------------------------------

### Provision WPMoo Toolkit Environment via Command

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Use this command in automation or CI pipelines to provision a repeatable environment. Specify product, Odoo version, and source repository URL.

```bash
npx @wpmoo/toolkit create --product ... --odoo-version ... --source-repo-url ...
```

--------------------------------

### Create New WPMoo Project with Agent Skills

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Use this command to scaffold a new WPMoo project, including optional agent skills. Specify product details, Odoo version, and repository URLs.

```bash
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 18.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git \
  --agent-skills-template
```

--------------------------------

### Create Project with Default Compose Source

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Generate a new project using the WPMoo CLI, specifying Docker Compose as the engine and a remote Git repository for the source code.

```bash
npx @wpmoo/toolkit create \
  --engine compose \
  --product my_product \
  --source-repo-url https://github.com/example-org/my_product.git
```

--------------------------------

### Create Project with Default Agent Skills

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Generate a new project using the WPMoo CLI, enabling the inclusion of agent skills from the default remote source.

```bash
npx @wpmoo/toolkit create \
  --product my_product \
  --source-repo-url https://github.com/example-org/my_product.git \
  --agent-skills-template
```

--------------------------------

### Create Project with Pinned Remote Sources

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Generate a project using the WPMoo CLI, pinning both the compose template and agent skills template to specific Git references (refs).

```bash
npx @wpmoo/toolkit create \
  --engine compose \
  --compose-template-ref v0.1.0 \
  --agent-skills-template \
  --agent-skills-template-ref v0.1.0 \
  --product my_product \
  --source-repo-url https://github.com/example-org/my_product.git
```

--------------------------------

### Delegate Snapshot and Lint Actions

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Delegate snapshot, restore, lint, and pot actions to compose scripts via the `./moo` command.

```bash
./moo snapshot ...
```

```bash
./moo restore-snapshot --dry-run ...
```

```bash
./moo restore-snapshot ...
```

```bash
./moo lint
```

```bash
./moo pot ...
```

--------------------------------

### Get WPMoo Toolkit Health Checks (JSON Output)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Utilize these commands for machine-readable health checks that can integrate with monitoring or VS Code tasks. The --json flag provides a versioned payload suitable for external parsing.

```bash
npx @wpmoo/toolkit status --json
```

```bash
npx @wpmoo/toolkit doctor --json
```

--------------------------------

### Create Project with Local Agent Skills

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Develop agent skills by using a local clone of the odoo-skills repository as the template source for the WPMoo CLI.

```bash
git clone https://github.com/wpmoo-org/odoo-skills ../odoo-skills

npx @wpmoo/toolkit create \
  --product my_product \
  --source-repo-url https://github.com/example-org/my_product.git \
  --agent-skills-template \
  --agent-skills-template-url ../odoo-skills
```

--------------------------------

### Manage Source Repositories

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Register and manage source repositories and their submodule lifecycles.

```bash
npx @wpmoo/toolkit add-repo ...
```

```bash
npx @wpmoo/toolkit remove-repo ...
```

--------------------------------

### Manage Modules

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Add or remove modules, updating the selected source repository configuration.

```bash
npx @wpmoo/toolkit add-module ...
```

```bash
npx @wpmoo/toolkit remove-module ...
```

--------------------------------

### WPMoo Toolkit Daily Actions: Direct via npx

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Alternative commands for performing daily actions directly using `npx`, suitable for CI environments. These mirror the `./moo` commands.

```bash
# ── Direct via npx (same commands, CI-friendly) ───────────────────────────────
npx @wpmoo/toolkit start
npx @wpmoo/toolkit update sale
npx @wpmoo/toolkit test sale --mode init
```

--------------------------------

### Run Baseline Coverage Test

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Execute the command to generate the initial test coverage report.

```bash
npm run test:coverage
```

--------------------------------

### Run Common Commands

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/AGENTS.md

Execute these commands before handing off code changes. Includes testing, type checking, and building.

```bash
npm test
npm run typecheck
npm run build
```

--------------------------------

### Create Generated Environment

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Use this command to scaffold new generated environments, including compose files and metadata.

```bash
npx @wpmoo/toolkit create ...
```

--------------------------------

### Create Project with Local Compose Template

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Develop compose resources by using a local clone of the odoo-docker-compose repository as the template source for the WPMoo CLI.

```bash
git clone https://github.com/wpmoo-org/odoo-docker-compose ../odoo-docker-compose

npx @wpmoo/toolkit create \
  --engine compose \
  --compose-template-url ../odoo-docker-compose \
  --product my_product \
  --source-repo-url https://github.com/example-org/my_product.git
```

--------------------------------

### Simulate Missing Tools for Testing

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

This command allows simulating missing system tools for testing purposes. It's useful for verifying how the toolkit behaves when certain prerequisites are not met.

```bash
WPMOO_TEST_MISSING_TOOLS=docker,git npx @wpmoo/toolkit
```

--------------------------------

### Local Project Verification and Build

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

These commands are used for local development tasks within the wpmoo-toolkit repository, including type checking, running tests, generating test coverage reports, and building the project.

```bash
npm run typecheck
```

```bash
npm test
```

```bash
npm run test:coverage
```

```bash
npm run build
```

--------------------------------

### List Source Manifest

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Use this command to inspect the current view of the source manifest, which records repository details like type, path, URL, and Odoo branch.

```bash
npx @wpmoo/toolkit source list
```

--------------------------------

### Access WPMoo Toolkit Cockpit

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Navigate to the product development directory and run this command to access the daily cockpit for service, module, database, and repository operations.

```bash
cd <product>_dev && ./moo
```

--------------------------------

### Scaffold a New Odoo Development Environment

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Use the 'create' command to generate a new Odoo development environment. Specify product name, Odoo version, and repository URLs. Options include custom target folders, dry runs, and auto-creation of missing GitHub repositories.

```bash
# Non-interactive create — minimum required flags
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 18.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git

# Multiple source repos: pass --source-repo-url multiple times
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 17.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git \
  --source-repo-url https://github.com/example-org/my_product_pro.git \
    --source-path my_product_pro \
    --source-addons my_product_sale,my_product_crm

# Custom target folder
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 19.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git \
  --target /workspace/my_product_dev

# Dry run — shows planned files and commands without touching disk
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 18.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git \
  --dry-run

# Auto-create missing GitHub repos and init empty ones
npx @wpmoo/toolkit create \
  --product my_product \
  --odoo-version 18.0 \
  --dev-repo-url https://github.com/example-org/my_product_dev.git \
  --source-repo-url https://github.com/example-org/my_product.git \
  --create-missing-repos \
  --init-empty-repos \
  --repo-visibility private
```

--------------------------------

### Safe Reset: Regenerate environment files

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Re-generates WPMoo-managed files without altering source code. Use `--dry-run` to preview changes. By default, changes are staged.

```bash
# Preview what will be refreshed (no changes made)
npx @wpmoo/toolkit reset --dry-run
```

```bash
# Perform the safe reset and stage changes
npx @wpmoo/toolkit reset
```

```bash
# Reset without staging
npx @wpmoo/toolkit reset --stage false
```

```bash
# Reset a specific target folder
npx @wpmoo/toolkit reset --target /workspace/my_product_dev
```

```bash
# Inside an environment via the cockpit alias
./moo safe-reset
```

--------------------------------

### Current Release Process Commands

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/handoff.md

Execute these commands sequentially to perform a release. Ensure any version bumps in package.json and package-lock.json are committed and pushed before tagging.

```bash
npm run release:check
npm run typecheck
npm run test
npm run build
VERSION="$(node -p \"require('./package.json').version\")"
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
```

--------------------------------

### Perform Safe Reset

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Refresh generated files and compose assets while preserving local runtime, data, and source module code. Use `--dry-run` to preview changes.

```bash
npx @wpmoo/toolkit reset --dry-run
```

```bash
npx @wpmoo/toolkit reset
```

--------------------------------

### Preview Snapshot Restore

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Use this command to preview a snapshot restore operation before performing a destructive restore.

```bash
./moo restore-snapshot --dry-run <snapshot-name> [db]
```

--------------------------------

### Check System Prerequisites for Odoo Environment

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Verifies the availability of Node.js, Git, Docker Desktop, Docker Compose, and Docker Engine. If checks fail, it provides guidance on how to resolve the issues.

```typescript
import { getSystemPrerequisiteStatus, renderSystemPrerequisiteGuidance } from '@wpmoo/toolkit';

const status = await getSystemPrerequisiteStatus();

if (!status.ok) {
  console.log(renderSystemPrerequisiteGuidance(status));
  // Output example:
  // Required tools before environment setup starts
  //
  // ✓ Node.js 20+           ok
  // ✓ Git                   ok
  // ✕ Docker Desktop        ↗ https://www.docker.com/products/docker-desktop/
  // Docker Desktop is installed, but Docker Engine is not running.
  // Start Docker Desktop, then check again.
  process.exit(1);
}

// status.checks: SystemPrerequisiteCheck[]
// status.issues: SystemPrerequisiteIssue[]  — only failing tools

```

--------------------------------

### runCli(argv, cwd)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Executes the full WPoo Toolkit CLI programmatically, simulating terminal invocation with specified arguments and current working directory.

```APIDOC
## runCli(argv, cwd)

### Description
Runs the full CLI programmatically, as if invoked from the terminal. Accepts an array of arguments and an optional current working directory.

### Usage Examples

```typescript
import { runCli } from '@wpmoo/toolkit';

// Run as if invoked from the terminal
await runCli(['status', '--json'], '/workspace/my_product_dev');

// Non-interactive create
await runCli([
  'create',
  '--product', 'my_product',
  '--odoo-version', '18.0',
  '--dev-repo-url', 'https://github.com/example-org/my_product_dev.git',
  '--source-repo-url', 'https://github.com/example-org/my_product.git',
  '--dry-run',
]);

// Run a daily action from a CI pipeline (inside environment root)
await runCli(['update', 'sale,crm'], '/workspace/my_product_dev');
```
```

--------------------------------

### Run Focused Tests for Task 2

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Command to execute focused tests for update-check, GitHub, and repository preflight modules.

```bash
npx vitest run test/update-check.test.ts test/github.test.ts test/repository-preflight.test.ts
```

--------------------------------

### Manage Module Source Repositories

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Add or remove modules from specified source repositories. Use `--source-type` to specify 'oca' or 'external' for non-private repositories.

```bash
npx @wpmoo/toolkit add-module --repo sale-workflow --module sale_order_line_no_discount --source-type oca
```

```bash
npx @wpmoo/toolkit remove-module --repo sale-workflow --module sale_order_line_no_discount --source-type oca
```

--------------------------------

### WPMoo Toolkit Source Commands (JSON Output)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

The --json flag is available on 'source list' and 'source sync' commands, providing a versioned payload suitable for parsing by external tooling.

```bash
npx @wpmoo/toolkit source list --json
```

```bash
npx @wpmoo/toolkit source sync --json
```

--------------------------------

### Delegate Daily Compose Actions

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Execute daily local compose actions by delegating to scripts within a generated environment.

```bash
./moo <action> ...
```

--------------------------------

### Synchronize Source Manifest

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Run this command after manual submodule or metadata repairs to regenerate the manifest and normalize source entries in `.wpmoo/odoo.json`.

```bash
npx @wpmoo/toolkit source sync
```

--------------------------------

### Non-Interactive WPMoo Toolkit Project Creation

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Create a new Odoo project environment non-interactively using command-line arguments. This is useful for automation and scripting.

```bash
npx @wpmoo/toolkit create \
  --product odoo_sample_module \
  --odoo-version 19.0 \
  --dev-repo-url https://github.com/example-org/odoo_sample_module_dev.git \
  --source-repo-url https://github.com/example-org/odoo_sample_module.git \
  --init-empty-repos
```

--------------------------------

### Run Focused Tests for Task 3

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Command to execute focused tests for safe-reset, daily-actions, and external-assets modules.

```bash
npx vitest run test/safe-reset.test.ts test/daily-actions.test.ts test/external-assets.test.ts
```

--------------------------------

### addModuleToSourceRepo(options)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Scaffolds a new Odoo module skeleton in a source repository. It creates the standard Odoo module directory structure within a specified path.

```APIDOC
## addModuleToSourceRepo(options)

### Description
Creates the standard Odoo module directory structure (`__manifest__.py`, `__init__.py`, `models/`, `security/`, `views/`) inside `odoo/custom/src/<sourceType>/<repoPath>/<moduleName>`.

### Usage Examples

**Add a module interactively (cockpit or prompt):**
```bash
npx @wpmoo/toolkit add-module
```

**Add a module directly (private repo, default):**
```bash
npx @wpmoo/toolkit add-module \
  --repo my_product \
  --module my_new_feature
```

**Add a module to an OCA repo:**
```bash
npx @wpmoo/toolkit add-module \
  --repo sale-workflow \
  --module sale_order_line_no_discount \
  --source-type oca
```

**Generated module structure:**
```
odoo/custom/src/private/my_product/my_new_feature/
  __init__.py
  __manifest__.py          ← version set to <odooVersion>.1.0.0
  models/__init__.py
  security/ir.model.access.csv
  views/.gitkeep
```
```

--------------------------------

### Add Repository Preflight Branch Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Tests for finding inaccessible GitHub repositories and creating repositories with specified visibility.

```typescript
findInaccessibleGitHubRepositories(options, runner) returns only inaccessible repositories
```

```typescript
createGitHubRepositories(missingRepos, 'public', runner) calls create for each repo with public visibility
```

```typescript
repositoryPreflightAvailable(runnerWithUnavailableGh) === false
```

```typescript
repositoryPreflightAvailable(runnerWithUnauthenticatedGh) === false
```

--------------------------------

### Run Doc Sanity Check

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-generated-environment-verification-matrix.md

Perform a sanity check on the documentation for the generated environment verification. This command uses ripgrep to find specific phrases in the relevant README and documentation files.

```bash
rg -n "Generated environment verification|generated-environment-verification" README.md docs/generated-environment-verification.md
```

--------------------------------

### Run the Full CLI Programmatically

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Executes the WPmoo Toolkit CLI with specified arguments and a working directory. This is useful for integrating CLI functionality into scripts or other applications.

```typescript
import { runCli } from '@wpmoo/toolkit';

// Run as if invoked from the terminal
await runCli(['status', '--json'], '/workspace/my_product_dev');

// Non-interactive create
await runCli([
  'create',
  '--product', 'my_product',
  '--odoo-version', '18.0',
  '--dev-repo-url', 'https://github.com/example-org/my_product_dev.git',
  '--source-repo-url', 'https://github.com/example-org/my_product.git',
  '--dry-run',
]);

// Run a daily action from a CI pipeline (inside environment root)
await runCli(['update', 'sale,crm'], '/workspace/my_product_dev');

```

--------------------------------

### WPMoo Toolkit Daily Actions: Database Management

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Commands for interacting with the PostgreSQL database in your WPMoo environment. Includes opening a PSQL shell, resetting databases, and managing snapshots.

```bash
# ── Database ──────────────────────────────────────────────────────────────────
./moo psql                           # open psql in the postgres container
./moo psql devel                     # connect to a specific database
./moo resetdb                        # reset the default database
./moo resetdb devel sale,crm         # reset with specific modules installed
./moo snapshot devel before-update   # dump database to backups/
./moo restore-snapshot before-update devel   # restore a snapshot
./moo restore-snapshot --dry-run before-update devel   # preview only
```

--------------------------------

### Synchronize Source Manifests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/generated-environment-verification.md

Ensure alignment between source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml`.

```bash
npx @wpmoo/toolkit source list
```

```bash
npx @wpmoo/toolkit source sync
```

--------------------------------

### Write Local Compose Fixture - TypeScript

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-generated-environment-verification-matrix.md

Helper function to create a local compose fixture for testing. It sets up necessary directories and writes placeholder files for docker-compose, odoo.conf, README, and shell scripts.

```typescript
async function writeComposeFixture(root: string): Promise<string> {
  const fixture = join(root, "compose-fixture");
  await mkdir(join(fixture, "scripts"), { recursive: true });
  await mkdir(join(fixture, "etc"), { recursive: true });
  await writeFile(join(fixture, "docker-compose_19.0.yml"), "services:\n  odoo:\n    image: odoo:19\n", "utf8");
  await writeFile(join(fixture, "etc/odoo.conf"), "[options]\naddons_path = /mnt/wpmoo-addons\n", "utf8");
  await writeFile(join(fixture, "README.md"), "# Compose Fixture\n", "utf8");
  for (const script of scriptNames) {
    await writeFile(join(fixture, "scripts", script), "#!/usr/bin/env bash\nexit 0\n", "utf8");
  }
  return fixture;
}
```

--------------------------------

### WPMoo Cockpit - Main Menu Structure

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Overview of the WPMoo Cockpit's main menu, showing available commands for services, modules, database, diagnostics, and repositories.

```text
WPMoo Cockpit
|-- Command palette /
|   |-- search commands such as /test, /logs, /doctor, /safe-reset
|-- Services
|   |-- start
|   |-- stop
|   |-- restart
|   |-- logs
|   `-- shell
|-- Modules
|   |-- install
|   |-- update
|   |-- test
|   |-- lint
|   |-- pot
|   |-- add-module
|   `-- remove-module
|-- Database
|   |-- psql
|   |-- snapshot
|   |-- restore-snapshot
|   `-- resetdb
|-- Diagnostics
|   |-- status
|   `-- doctor
|-- Repositories
|   |-- add-repo
|   `-- remove-repo
|-- Maintenance
|   `-- safe-reset
`-- Exit
```

--------------------------------

### WPMoo Toolkit Short Aliases

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Use these shorter aliases for common WPMoo Toolkit commands. Legacy paths are also available for compatibility.

```bash
npx wpmoo
```

```bash
npx @wpmoo/odoo
```

```bash
npx @wpmoo/odoo-dev
```

--------------------------------

### Run Focused Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/AGENTS.md

Execute specific tests for a given file using Vitest.

```bash
npx vitest run test/<file>.test.ts
```

--------------------------------

### Test CLI Command Variations

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Write behavior tests for various CLI commands by mocking dependencies and dynamically importing the CLI function. Assert calls into mocked helpers and console output.

```typescript
await runCli(['--help'], '/tmp/example');
await runCli(['--version'], '/tmp/example');
await runCli(['doctor'], '/tmp/example');
await runCli(['start'], '/tmp/example');
await runCli(['reset', '--target', '/tmp/example', '--stage=false'], '/tmp/example');
await runCli([
  'create',
  '--product', 'odoo_sample_module',
  '--dev-repo-url', 'https://github.com/example-org/odoo_sample_module_dev.git',
  '--source-repo-url', 'https://github.com/example-org/odoo_sample_module.git',
  '--dry-run',
], '/tmp/example');
```

--------------------------------

### Commit Generated Environment Verification Files

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-generated-environment-verification-matrix.md

Stage and commit specific files related to the generated environment verification matrix and documentation.

```bash
git add test/generated-environment-scaffold.test.ts test/generated-environment-moo.test.ts test/generated-environment-doctor-matrix.test.ts test/generated-environment-lifecycle.test.ts docs/generated-environment-verification.md README.md
git commit -m "test: add generated environment verification matrix"
```

--------------------------------

### Safe Reset (`reset`)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Re-generates WPMoo-managed environment files based on the current `.wpmoo/odoo.json` metadata without altering source code or critical data.

```APIDOC
## Safe Reset (`reset`)

### `safeResetEnvironment(options)` — regenerate environment files without touching source code

Re-generates all WPMoo-managed files (moo script, .gitignore, README.md, AGENTS.md, .env.example, docker-compose assets, etc.) from the current `.wpmoo/odoo.json` metadata. Never deletes source repo folders, .env, data, backups, or Git history.

```bash
# Preview what will be refreshed (no changes made)
npx @wpmoo/toolkit reset --dry-run

# Perform the safe reset and stage changes
npx @wpmoo/toolkit reset

# Reset without staging
npx @wpmoo/toolkit reset --stage false

# Reset a specific target folder
npx @wpmoo/toolkit reset --target /workspace/my_product_dev

# Inside an environment via the cockpit alias
./moo safe-reset
```

**Files regenerated by safe-reset:**

- `.wpmoo/odoo.json` (metadata, merged with existing values)
- `moo` (delegation script, executable)
- `.gitignore`
- `.env.example`
- `README.md`
- `AGENTS.md`
- `docs/appstore-release.md`
- External compose template assets (fetched from configured template URL)
- External agent skill assets (when `agentSkillsTemplateUrl` is configured)

**Files explicitly protected (never touched):**

- `odoo/custom/src/private/`, `oca/`, `external/` (source repos)
- `.env`, `data/`, `backups/`
- `.gitmodules`, Git history
```

--------------------------------

### ScaffoldOptions Type Reference

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Defines the structure for configuring project scaffolding options. Includes details like product slug, Odoo version, repository information, and initialization settings.

```typescript
import type { ScaffoldOptions, SourceRepo } from '@wpmoo/toolkit';

const options: ScaffoldOptions = {
  product: 'my_product',           // product slug, used as folder/repo base name
  odooVersion: '18.0',             // '19.0' | '18.0' | '17.0' | '16.0'
  devRepo: 'my_product_dev',       // dev environment repo name
  devRepoUrl: 'https://github.com/example-org/my_product_dev.git',
  sourceRepos: [
    {
      url: 'https://github.com/example-org/my_product.git',
      path: 'my_product',          // submodule folder name
      addons: ['my_product'],       // Odoo addon folder names inside the repo
      sourceType: 'private',        // 'private' | 'oca' | 'external'
    },
  ],
  target: '/workspace/my_product_dev',
  dryRun: false,
  initEmptyRepos: true,            // initialise empty Git repos before submodule add
  stage: true,                     // run `git add .` when done
  createMissingRepos: false,
  repoVisibility: 'private',       // 'private' | 'public'
};
```

--------------------------------

### Source Repository Management (`source`, `add-repo`, `remove-repo`)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Manages Git submodules as source repositories, allowing addition, removal, listing, and synchronization of repository information with environment metadata.

```APIDOC
## Source Repository Management (`source`, `add-repo`, `remove-repo`)

### `addModuleRepo(options)` — add a Git submodule as a source repo

Adds a repository as a Git submodule under `odoo/custom/src/<sourceType>/<repoPath>`, branched to the environment's Odoo version, then updates `.wpmoo/odoo.json` and `odoo/custom/manifests/sources.yaml`.

```bash
# Add a private source repo (interactive)
npx @wpmoo/toolkit add-repo

# Add a private repo directly
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/example-org/my_product.git

# Add an OCA repo
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/OCA/server-tools.git \
  --source-type oca

# Add an external repo with explicit path
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/vendor/vendor-addons.git \
  --source-type external \
  --repo vendor-addons

# Remove a source repo
npx @wpmoo/toolkit remove-repo --repo my_product

# List all source repos (human-readable)
npx @wpmoo/toolkit source list

# List source repos as JSON
npx @wpmoo/toolkit source list --json

# Sync source manifest and metadata from .gitmodules state
npx @wpmoo/toolkit source sync

# Sync and emit JSON
npx @wpmoo/toolkit source sync --json
```
```

--------------------------------

### Copy Compose Assets Locally

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/external-resources.md

Use this command to copy compact generated environment payloads from a cloned odoo-docker-compose repository to a local development directory.

```bash
git clone https://github.com/wpmoo-org/odoo-docker-compose
cd odoo-docker-compose
mkdir -p ../my_product_dev
cp -R resources/generated-env/. ../my_product_dev/
cp .env.example ../my_product_dev/.env
cd ../my_product_dev
./scripts/up.sh
```

--------------------------------

### Execute WPMoo Cockpit Commands Directly

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Run common cockpit actions directly from the command line. This allows for scripting and automation of workflows.

```bash
./moo start
```

```bash
./moo logs odoo
```

```bash
./moo update sale
```

```bash
./moo test sale
```

```bash
./moo snapshot devel before-update
```

```bash
./moo restore-snapshot --dry-run before-update devel
```

--------------------------------

### Export Testable CLI Function

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Refactor the CLI entrypoint to export a testable function, preserving direct CLI execution. Requires importing `pathToFileURL` from `node:url`.

```typescript
export async function runCli(argv = process.argv.slice(2), cwd = process.cwd()): Promise<void> {
  // Move the current main body here.
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  runCli().catch((error: unknown) => {
    const message = error instanceof Error ? error.message : String(error);
    console.error(message);
    process.exit(1);
  });
}
```

--------------------------------

### WPMoo Toolkit Commands with JSON Output

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/README.md

Execute WPMoo Toolkit commands and receive output in JSON format, which is useful for integration with other tools and VS Code.

```bash
npx @wpmoo/toolkit status --json
```

```bash
npx @wpmoo/toolkit source list --json
```

```bash
npx @wpmoo/toolkit source sync --json
```

```bash
npx @wpmoo/toolkit doctor --json
```

--------------------------------

### Add Module Repo: Add Git submodule as source repo

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Adds a Git repository as a submodule, branching to the environment's Odoo version. Updates metadata and source manifests. Use `--source-type` for OCA or external repos.

```bash
# Add a private source repo (interactive)
npx @wpmoo/toolkit add-repo
```

```bash
# Add a private repo directly
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/example-org/my_product.git
```

```bash
# Add an OCA repo
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/OCA/server-tools.git \
  --source-type oca
```

```bash
# Add an external repo with explicit path
npx @wpmoo/toolkit add-repo \
  --repo-url https://github.com/vendor/vendor-addons.git \
  --source-type external \
  --repo vendor-addons
```

```bash
# Remove a source repo
npx @wpmoo/toolkit remove-repo --repo my_product
```

```bash
# List all source repos (human-readable)
npx @wpmoo/toolkit source list
```

```bash
# List source repos as JSON
npx @wpmoo/toolkit source list --json
```

```json
{
  "schemaVersion": 1,
  "command": "source list",
  "ok": true,
  "sources": [
    {
      "type": "private",
      "path": "my_product",
      "url": "https://github.com/example-org/my_product.git",
      "branch": "18.0",
      "addons": ["my_product"]
    }
  ]
}
```

```bash
# Sync source manifest and metadata from .gitmodules state
npx @wpmoo/toolkit source sync
```

```bash
# Sync and emit JSON
npx @wpmoo/toolkit source sync --json
```

--------------------------------

### Run Focused Unit and Source Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Execute Vitest to run specific unit and source tests. This command is used after refactoring and writing new tests.

```bash
npx vitest run test/cli.test.ts test/cli-source.test.ts
```

--------------------------------

### commandFromArgs(argv)

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Parses raw command-line arguments into a structured `CommandRoute` object, identifying the command and its associated arguments.

```APIDOC
## commandFromArgs(argv)

### Description
Parses raw argv into a `CommandRoute` object, which includes the command name and its arguments.

### Usage Examples

```typescript
import { commandFromArgs } from '@wpmoo/toolkit';

// Returns { command: 'menu', argv: [] } when no args given
commandFromArgs([]);

// Returns { command: 'status', argv: ['--json'] }
commandFromArgs(['status', '--json']);

// Returns { command: 'create', argv: ['--product', 'acme', ...] }
commandFromArgs(['create', '--product', 'acme', '--odoo-version', '18.0']);

// Throws for unknown commands
// commandFromArgs(['unknown-command']); // Error: Unknown command: unknown-command
```
```

--------------------------------

### Run Generated Environment Moo Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-generated-environment-verification-matrix.md

Execute the generated moo script tests using Vitest. This command runs the specific test file for the generated environment moo delegation matrix.

```bash
npx vitest run test/generated-environment-moo.test.ts
```

--------------------------------

### Add GitHub Branch Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Tests for GitHub CLI availability, authentication status, authenticated login retrieval, and repository status checks.

```typescript
isGitHubCliAvailable(runnerThatThrows) === false
```

```typescript
isGitHubAuthenticated(runnerThatThrows) === false
```

```typescript
getAuthenticatedGitHubLogin(runnerReturningWhitespace) rejects with 'GitHub CLI is not authenticated'
```

```typescript
getGitHubRepositoryStatus(runner, 'https://not-github.example/repo.git') returns { status: 'unsupported' }
```

```typescript
createGitHubRepository(runner, 'https://not-github.example/repo.git', 'private') rejects
```

--------------------------------

### Add Daily-Actions Branch Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Tests for daily actions, including delegation of service arguments and rendering of script arguments for various actions.

```typescript
runDailyAction('logs', ['web']) delegates service argument
```

```typescript
runDailyAction('test', ['module_a', '--db', 'custom', '--mode', 'update', '--tags', 'tag']) renders expected script args
```

```typescript
runDailyAction('restore-snapshot', ['snapshot-name', 'customdb']) renders expected script args
```

```typescript
invalid/missing daily action arguments reject with existing error wording
```

--------------------------------

### Add Safe-Reset Branch Tests

Source: https://github.com/wpmoo-org/wpmoo-toolkit/blob/main/docs/superpowers/plans/2026-05-14-coverage-improvement.md

Tests for safe reset functionality, including preview rendering and environment reset behavior with different configurations.

```typescript
renderSafeResetPreview('/tmp/env', false) contains 'Generated changes will not be staged.'
```

```typescript
safeResetEnvironment({ target, stage: false }) does not call git add
```

```typescript
safeResetEnvironment infers repo URLs from .gitmodules when metadata omits a URL
```

```typescript
safeResetEnvironment falls back to source path when .gitmodules is missing
```

--------------------------------

### Parse Raw CLI Arguments into Command Routes

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Converts raw command-line arguments into a structured command route object. It handles basic commands and their arguments, throwing an error for unknown commands.

```typescript
import { commandFromArgs, parseArgs } from '@wpmoo/toolkit';

// Returns { command: 'menu', argv: [] } when no args given
commandFromArgs([]);

// Returns { command: 'status', argv: ['--json'] }
commandFromArgs(['status', '--json']);

// Returns { command: 'create', argv: ['--product', 'acme', ...] }
commandFromArgs(['create', '--product', 'acme', '--odoo-version', '18.0']);

// Throws for unknown commands
// commandFromArgs(['unknown-command']); // Error: Unknown command: unknown-command

```

--------------------------------

### Add/Remove Odoo Module Skeleton

Source: https://context7.com/wpmoo-org/wpmoo-toolkit/llms.txt

Use these commands to scaffold new Odoo modules or remove existing ones from a source repository. Interactive mode prompts for details, while direct mode allows specifying repository and module names.

```bash
npx @wpmoo/toolkit add-module
```

```bash
npx @wpmoo/toolkit add-module \
  --repo my_product \
  --module my_new_feature
```

```bash
npx @wpmoo/toolkit add-module \
  --repo sale-workflow \
  --module sale_order_line_no_discount \
  --source-type oca
```

```bash
npx @wpmoo/toolkit remove-module \
  --repo my_product \
  --module my_old_feature
```

```bash
npx @wpmoo/toolkit remove-module \
  --repo my_product \
  --module my_old_feature \
  --delete-files
```