@wpmoo/toolkit 0.9.0

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/update-check.js

@@ -0,0 +1,106 @@
+import { spawn } from 'node:child_process';
+import { execa } from 'execa';
+export const realNpm = {
+    async run(args) {
+        const result = await execa('npm', args, args[0] === 'view' ? { timeout: 5000 } : {});
+        return { stdout: result.stdout, stderr: result.stderr };
+    },
+};
+function truthyEnv(value) {
+    return value !== undefined && ['1', 'true', 'yes', 'y'].includes(value.toLowerCase().trim());
+}
+export function isUpdateCheckSkipped(argv, env = process.env) {
+    if (argv.includes('--no-update-check'))
+        return true;
+    if (truthyEnv(env.WPMOO_SKIP_UPDATE_CHECK))
+        return true;
+    return false;
+}
+function numericParts(version) {
+    return version
+        .replace(/^v/, '')
+        .split('-', 1)[0]
+        .split('.')
+        .map((part) => Number.parseInt(part, 10) || 0);
+}
+export function compareVersions(currentVersion, latestVersion) {
+    const current = numericParts(currentVersion);
+    const latest = numericParts(latestVersion);
+    const length = Math.max(current.length, latest.length);
+    for (let index = 0; index < length; index += 1) {
+        const currentPart = current[index] ?? 0;
+        const latestPart = latest[index] ?? 0;
+        if (currentPart !== latestPart) {
+            return currentPart - latestPart;
+        }
+    }
+    return 0;
+}
+function parseNpmPackageInfo(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        throw new Error('npm did not return package metadata');
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === 'object' && parsed !== null) {
+            const record = parsed;
+            const version = typeof record.version === 'string' ? record.version.trim() : '';
+            const dist = record.dist;
+            const nestedTarball = typeof dist === 'object' && dist !== null && typeof dist.tarball === 'string'
+                ? String(dist.tarball).trim()
+                : '';
+            const dottedTarball = typeof record['dist.tarball'] === 'string' ? record['dist.tarball'].trim() : '';
+            const tarball = nestedTarball || dottedTarball;
+            if (version && tarball) {
+                return { version, tarball };
+            }
+        }
+    }
+    catch {
+        // Fall through to the validation error below.
+    }
+    throw new Error('npm did not return a package version and tarball');
+}
+async function viewPackageInfo(packageSpecValue, runner) {
+    const result = await runner.run(['view', packageSpecValue, 'version', 'dist.tarball', '--json']);
+    return parseNpmPackageInfo(result.stdout);
+}
+export async function checkForUpdate(packageName, currentVersion, runner = realNpm) {
+    try {
+        const latest = await viewPackageInfo(packageSpec(packageName, 'latest'), runner);
+        if (compareVersions(currentVersion, latest.version) < 0) {
+            const exact = await viewPackageInfo(packageSpec(packageName, latest.version), runner);
+            if (exact.version !== latest.version || !exact.tarball) {
+                throw new Error(`npm metadata for ${packageSpec(packageName, latest.version)} did not validate`);
+            }
+            return { status: 'update-available', currentVersion, latestVersion: exact.version, tarball: exact.tarball };
+        }
+        return { status: 'current', currentVersion, latestVersion: latest.version };
+    }
+    catch {
+        return { status: 'unavailable', currentVersion };
+    }
+}
+export function packageSpec(packageName, version) {
+    return `${packageName}@${version}`;
+}
+export async function installLatestPackage(packageName, version, runner = realNpm) {
+    await runner.run(['install', '-g', packageSpec(packageName, version)]);
+}
+export function restartArgs(packageName, version, argv) {
+    return ['exec', '--yes', '--package', packageSpec(packageName, version), '--', 'wpmoo', ...argv];
+}
+export function restartEnvironment(env = process.env) {
+    return { ...env, WPMOO_SKIP_UPDATE_CHECK: '1' };
+}
+export async function restartCli(packageName, version, argv) {
+    const child = spawn('npm', restartArgs(packageName, version, argv), {
+        env: restartEnvironment(),
+        stdio: 'inherit',
+    });
+    return new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('exit', (code) => resolve(code));
+    });
+}

package/dist/version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+function readPackageJson() {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+}
+export function packageVersion() {
+    return readPackageJson().version;
+}
+export function renderVersion() {
+    const packageJson = readPackageJson();
+    return `${packageJson.name} ${packageJson.version}`;
+}
+export function packageName() {
+    return readPackageJson().name;
+}
+export function renderVersionTag(latestVersion) {
+    const current = packageVersion();
+    const updateSuffix = latestVersion ? ` -> v.${latestVersion} available` : '';
+    return `\u001B[33mv.${current}${updateSuffix}\u001B[0m`;
+}

package/docs/external-resources.md

@@ -0,0 +1,136 @@
+# External Resources
+
+WPMoo does not embed large Docker Compose resources or Agent Skill text inside
+the TypeScript CLI. The CLI copies standalone external resources from their own
+repositories/packages into generated environments, while those resources can also
+be used independently.
+
+## Repositories/packages
+
+```text
+gh:wpmoo-org/odoo-docker-compose
+npm:@wpmoo/odoo-skills
+gh:wpmoo-org/odoo-skills
+```
+
+## Compose resource
+
+`wpmoo-org/odoo-docker-compose` now exposes a compact generated-environment payload
+under `resources/generated-env/`:
+
+```text
+compose.yaml
+compose/dev.yaml
+compose/stage.yaml
+compose/prod.yaml
+config/odoo/odoo.conf
+resources/odoo/entrypoint.sh
+```
+
+`@wpmoo/toolkit` prefers that compact payload first when copying compose assets.
+For pinned older refs that do not provide `resources/generated-env/`, the CLI
+falls back to the legacy repository-root layout (`docker-compose_<version>.yml`
+and related files) for compatibility.
+
+Standalone usage with the compact payload:
+
+```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
+```
+
+WPMoo CLI usage with the default remote source:
+
+```bash
+npx @wpmoo/toolkit create \
+  --engine compose \
+  --product my_product \
+  --source-repo-url https://github.com/example-org/my_product.git
+```
+
+During resource development, use a local clone:
+
+```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
+```
+
+## Agent Skills resource
+
+`@wpmoo/odoo-skills` is generic and intentionally not project-specific:
+
+```text
+skills/odoo-oca/SKILL.md
+skills/odoo-open-core/SKILL.md
+skills/odoo-porting/SKILL.md
+```
+
+Standalone Pi package usage:
+
+```bash
+pi install npm:@wpmoo/odoo-skills
+```
+
+Standalone npx project-local install:
+
+```bash
+npx @wpmoo/odoo-skills --target /path/to/project
+```
+
+WPMoo CLI can also copy those skills into generated environments 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
+```
+
+During skill development, use a local clone:
+
+```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
+```
+
+Generated project-local skills are placed under:
+
+```text
+.agents/skills/
+```
+
+Project or module-specific guidance should live in that project/module's own
+`AGENTS.md` or custom skill files.
+
+## References and pins
+
+Remote Git sources can be pinned with 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
+```
+
+The CLI supports local directories and Git-style resource sources such as
+`gh:owner/repo`, HTTPS Git URLs, and SSH Git URLs.

package/docs/generated-environment-verification.md

@@ -0,0 +1,140 @@
+# Generated Environment Verification
+
+## Scope
+
+This matrix covers disposable generated development environments only. It is for
+local and CI verification of generated artifacts and command behavior. It does
+not validate staging or production deployments.
+
+## Command split
+
+- Use `npx @wpmoo/toolkit ...` for package/operator commands (`create`,
+  `add-repo`, `remove-repo`, `add-module`, `remove-module`, `doctor`, `reset`).
+- Use `./moo ...` inside a generated environment for daily local compose
+  actions delegated to `./scripts/*.sh`.
+
+## Verification matrix
+
+| Area | Contract | Primary command(s) |
+| --- | --- | --- |
+| Scaffold files and metadata | Generated environment includes expected files and `.wpmoo/odoo.json` metadata. | `npx @wpmoo/toolkit create ...` |
+| Compose resource files | Compact compose layout is present (`compose.yaml` + environment overlays under `compose/`), plus config/resources/scripts. | `npx @wpmoo/toolkit create ...` |
+| `./moo` delegation | `./moo` dispatches fixed daily actions to the matching script and preserves argument pass-through. | `./moo <action> ...` |
+| Doctor checks | Metadata, compose files, scripts, source repo paths, and local tooling checks behave as expected. | `npx @wpmoo/toolkit doctor` or `./moo doctor` |
+| Doctor safe fixes | Safe file-level fixes are applied only with `--fix`, then doctor runs again and reports any remaining manual issues. | `npx @wpmoo/toolkit doctor --fix` |
+| Generated Postgres checks | For PostgreSQL 18 environments, doctor validates db mount targets avoid old PG image-specific paths and can normalize safe targets with `--fix`. | `npx @wpmoo/toolkit doctor`, `npx @wpmoo/toolkit doctor --fix` |
+| Source repo add/remove | Source repository registration and submodule lifecycle behave correctly. | `npx @wpmoo/toolkit add-repo ...`, `npx @wpmoo/toolkit remove-repo ...` |
+| Source manifest sync | Source repo metadata, `.gitmodules`, and `odoo/custom/manifests/sources.yaml` stay aligned. | `npx @wpmoo/toolkit source list`, `npx @wpmoo/toolkit source sync` |
+| Module add/remove | Module registration changes are applied to the selected source repo config. | `npx @wpmoo/toolkit add-module ...`, `npx @wpmoo/toolkit remove-module ...` |
+| Safe reset | Generated files are refreshed (including `compose.yaml` overlays and env example) without deleting source module code. Local runtime/data directories and custom source layout content are preserved; legacy user-editable paths from older templates may remain and are reported for manual cleanup. | `npx @wpmoo/toolkit reset --dry-run`, `npx @wpmoo/toolkit reset` |
+| Snapshot/restore and lint/pot | These actions are delegated by `./moo` to compose scripts. Restore preview, snapshot retention, and stage/prod destructive guards are preserved by the package argument layer. | `./moo snapshot ...`, `./moo restore-snapshot --dry-run ...`, `./moo restore-snapshot ...`, `./moo lint`, `./moo pot ...` |
+
+## Compact compose checks
+
+Verify the generated environment includes at least:
+
+```text
+compose.yaml
+compose/dev.yaml
+compose/stage.yaml
+compose/prod.yaml
+config/odoo/odoo.conf
+resources/odoo/entrypoint.sh
+```
+
+Default local development uses `compose.yaml` plus `compose/dev.yaml`.
+`WPMOO_ENV=stage` or `WPMOO_ENV=prod` must only be used after production-grade
+secrets and volumes are configured.
+
+When `WPMOO_ENV=stage` or `WPMOO_ENV=prod`, generated compose scripts refuse
+destructive database actions such as `resetdb` and real `restore-snapshot`
+unless `.env` explicitly sets `WPMOO_ALLOW_DESTRUCTIVE=1`.
+
+For PostgreSQL 18 environments (including `POSTGRES_IMAGE=postgres:18`), ensure db
+volume and tmpfs mount targets use `/var/lib/postgresql` directly:
+
+```text
+- volumes:
+  - db_data:/var/lib/postgresql
+```
+
+Paths such as `/var/lib/postgresql/data` and `/var/lib/postgresql/18/docker` are
+no longer accepted by the package `doctor` check.
+
+`doctor --fix` may rewrite these safe mount targets to `/var/lib/postgresql`.
+It does not upgrade existing database data; if a real PostgreSQL major upgrade
+is involved, use PostgreSQL upgrade tooling first.
+
+## Safe reset policy
+
+Safe reset intentionally avoids deleting user-editable legacy paths from old
+compose templates. Preview output must warn when these paths may remain:
+
+```text
+docs/assets/
+test/
+.github/
+```
+
+In addition, safe reset preserves local runtime and source-data state while refreshing
+generated and compose assets:
+
+```text
+.env
+data/
+backups/
+odoo/custom/src/oca/
+odoo/custom/src/external/
+odoo/custom/patches/
+odoo/custom/manifests/
+```
+
+Run `npx @wpmoo/toolkit reset --dry-run` before writing changes when you need to
+review the generated file refresh plan.
+
+## Snapshot policy
+
+Use restore preview before a destructive restore:
+
+```bash
+./moo restore-snapshot --dry-run <snapshot-name> [db]
+```
+
+`WPMOO_SNAPSHOT_RETENTION_COUNT` may be set to a positive integer to prune old
+snapshot manifests and their matching dump/filestore files after a new snapshot
+is written.
+
+## Source manifest checks
+
+Generated environments include `odoo/custom/manifests/sources.yaml`. The manifest
+records each source repository's type (`private`, `oca`, or `external`), path,
+URL, Odoo branch, and addon boundaries.
+
+Use `source list` to inspect the current manifest view:
+
+```bash
+npx @wpmoo/toolkit source list
+```
+
+Use `source sync` after manual submodule or metadata repair to regenerate the
+manifest and normalize `.wpmoo/odoo.json` source entries:
+
+```bash
+npx @wpmoo/toolkit source sync
+```
+
+`doctor` fails when manifest entries, metadata entries, and registered source
+submodule paths diverge. `doctor --fix` can regenerate
+`odoo/custom/manifests/sources.yaml` from metadata plus `.gitmodules` when the
+manifest is missing, unreadable, or stale.
+
+## Local verification commands
+
+Run from the `wpmoo-toolkit` repository root:
+
+```bash
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+```

package/docs/handoff.md

@@ -0,0 +1,29 @@
+# Historical Handoff Notes
+
+This file is an archive pointer for pre-0.8.37 handoff notes. Those notes
+included a stale direct publish attempt and must not be used as current release
+guidance.
+
+Current release path:
+
+```bash
+npm run release:check
+npm run typecheck
+npm 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"
+```
+
+If `npm run release:check` bumps `package.json` and `package-lock.json`, commit
+and push that version bump first, then rerun the release check before tagging.
+
+Publishing is handled by the `Publish` GitHub Actions workflow through npm
+Trusted Publishing after the tag is pushed. Do not run `npm publish` manually
+unless a coordinator explicitly requests a fallback.
+
+Current command standard:
+
+- Use `npx @wpmoo/toolkit ...` for package/operator commands.
+- Use generated environment `./moo ...` for local compose daily commands.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@wpmoo/toolkit",
+  "version": "0.9.0",
+  "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wpmoo-org/wpmoo-toolkit.git"
+  },
+  "homepage": "https://github.com/wpmoo-org/wpmoo-toolkit",
+  "bugs": {
+    "url": "https://github.com/wpmoo-org/wpmoo-toolkit/issues"
+  },
+  "readmeFilename": "README.md",
+  "main": "./dist/cli.js",
+  "exports": "./dist/cli.js",
+  "keywords": [
+    "odoo",
+    "wpmoo",
+    "wpmoo toolkit",
+    "toolkit",
+    "odoo development",
+    "odoo cli",
+    "odoo lifecycle",
+    "odoo dev workflow",
+    "odoo staging workflow",
+    "odoo production workflow",
+    "odoo docker",
+    "odoo docker compose",
+    "odoo skills"
+  ],
+  "bin": {
+    "wpmoo": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/assets",
+    "docs/*.md"
+  ],
+  "engines": {
+    "node": ">=20.17"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "release:check": "bash scripts/release-check.sh",
+    "smoke:published": "bash scripts/smoke-published.sh",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.3",
+    "@inquirer/search": "^4.1.9",
+    "@inquirer/select": "^5.1.5",
+    "execa": "^9.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT"
+}