@wpmoo/odoo 0.8.45 → 0.8.47

package/README.md

@@ -178,10 +178,19 @@ npx @wpmoo/odoo remove-module \
 
 Check that a generated environment is structurally ready:
 
+```bash
+npx @wpmoo/odoo status
+```
+
+Run the deeper environment health check:
+
 ```bash
 npx @wpmoo/odoo doctor
 ```
 
+`status` is fast and offline, and reads local metadata/files only.
+`doctor` is a deeper health check and may check Docker CLI access and GitHub workflows.
+
 Refresh generated environment files without deleting module source code:
 
 ```bash
@@ -216,10 +225,38 @@ Daily actions require `.wpmoo/odoo.json` in the current directory and delegate t
 fixed scripts under `./scripts`; they do not search parent directories or accept
 arbitrary script names.
 
+Task-oriented quick recipes:
+
+```bash
+# create environment
+npx @wpmoo/odoo create --product odoo_sample_module --dev-repo-url <dev-repo-url> --source-repo-url <source-repo-url>
+
+# add source repo
+npx @wpmoo/odoo add-repo --repo-url https://github.com/example-org/odoo_sample_module_reports.git
+
+# add module
+npx @wpmoo/odoo add-module --repo odoo_sample_module --module odoo_sample_module_base
+
+# run tests
+npx @wpmoo/odoo test sale --db devel --mode update --tags /sale
+
+# safe reset / recover
+npx @wpmoo/odoo snapshot devel before-reset
+npx @wpmoo/odoo reset
+npx @wpmoo/odoo restore-snapshot before-reset devel
+
+# daily checks
+npx @wpmoo/odoo status
+npx @wpmoo/odoo doctor
+./moo logs odoo
+```
+
 Use `npx @wpmoo/odoo ...` for package/operator commands such as create,
 add/remove repo, add/remove module, `doctor`, and `reset`. Generated
 environments include `./moo` for local daily commands; it also falls back to
 `npx @wpmoo/odoo@latest` for package commands such as `./moo doctor`.
+For the operator-facing verification matrix, see
+[`docs/generated-environment-verification.md`](docs/generated-environment-verification.md).
 
 ## Defaults
 

package/dist/args.js

@@ -6,6 +6,7 @@ import { dailyActionCommands } from './daily-actions.js';
 import { validateAddonName, validateRepoPath } from './path-validation.js';
 import { inferGitHubOwner, inferRepoPath, normalizeRepositoryUrl } from './repo-url.js';
 const commandNames = new Set([
+    'status',
     'create',
     'add-repo',
     'remove-repo',

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { confirm, intro, isCancel, note, outro, select, text } from '@clack/prompts';
+import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { commandFromArgs, defaultTargetForProduct, isHelpRequested, isVersionRequested, optionsFromArgs, parseArgs, stripInternalFlags, } from './args.js';
 import { detectDevelopmentEnvironment } from './environment.js';
 import { commandOdooVersion } from './environment-version.js';
@@ -22,6 +23,7 @@ import { scaffold } from './scaffold.js';
 import { renderBanner } from './templates.js';
 import { checkForUpdate, installLatestPackage, isUpdateCheckSkipped, restartCli } from './update-check.js';
 import { packageName, packageVersion, renderVersion, renderVersionTag } from './version.js';
+import { getEnvironmentStatus, renderEnvironmentStatusForTarget, renderEnvironmentStatusSummary, } from './status.js';
 import { getGitHubAccounts, getGitHubRepositoryStatus, githubRepositoryUrl, realGitHub, createGitHubRepository, } from './github.js';
 import { environmentGitHubOwner } from './environment-context.js';
 import { handlePromptCancel, handleUnavailableMenuChoice, installPromptCancelKeyTracker, isMenuBackSignal, MenuBackSignal, menuIntroTitle, menuPromptMessage, } from './menu-navigation.js';
@@ -321,7 +323,7 @@ async function selectSourceRepo(target, cancelAction = 'exit') {
     const repos = await listModuleRepos(target);
     if (repos.length === 0) {
         if (cancelAction === 'back') {
-            note(`No source repos found under ${target}/odoo/custom/src/private.`, 'Nothing to select');
+            note(`No source repos found under ${target}/odoo/custom/src/private.\nNext: choose "Add source repo" first.`, 'Nothing to select');
             handleUnavailableMenuChoice(cancelAction);
         }
         throw new Error(`No source repos found under ${target}/odoo/custom/src/private`);
@@ -409,7 +411,7 @@ async function removeRepoOptionsFromPrompts(argv, showIntro = true, cancelAction
     const repos = await listModuleRepos(target);
     if (repos.length === 0) {
         if (cancelAction === 'back') {
-            note(`No module submodules found under ${target}/odoo/custom/src/private.`, 'Nothing to remove');
+            note(`No module submodules found under ${target}/odoo/custom/src/private.\nNext: choose "Add source repo" first.`, 'Nothing to remove');
             handleUnavailableMenuChoice(cancelAction);
         }
         throw new Error(`No module submodules found under ${target}/odoo/custom/src/private`);
@@ -448,7 +450,7 @@ async function removeModuleOptionsFromPrompts(showIntro = true, cancelAction = '
     const modules = await listModulesInSourceRepo(target, repoPath);
     if (modules.length === 0) {
         if (cancelAction === 'back') {
-            note(`No Odoo modules found under ${target}/odoo/custom/src/private/${repoPath}.`, 'Nothing to remove');
+            note(`No Odoo modules found under ${target}/odoo/custom/src/private/${repoPath}.\nNext: choose "Add module to source repo" first.`, 'Nothing to remove');
             handleUnavailableMenuChoice(cancelAction);
         }
         throw new Error(`No Odoo modules found under ${target}/odoo/custom/src/private/${repoPath}`);
@@ -571,6 +573,8 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         }
         while (true) {
             try {
+                const status = await getEnvironmentStatus(cwd);
+                note(renderEnvironmentStatusSummary(status), 'Environment status');
                 const action = await selectEnvironmentActionFromMenu();
                 if (action === 'exit') {
                     return;
@@ -686,6 +690,14 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         console.log(await runDoctor(cwd));
         return;
     }
+    if (route.command === 'status') {
+        if (route.argv.length > 0) {
+            throw new Error('Usage: wpmoo status');
+        }
+        console.log(renderBanner());
+        console.log(await renderEnvironmentStatusForTarget(cwd));
+        return;
+    }
     if (isDailyActionCommand(route.command)) {
         console.log(renderBanner());
         await runDailyAction(route.command, route.argv, cwd);
@@ -712,7 +724,19 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
     }
     outro(`Created Odoo dev overlay in ${resolvedOptions.target}. Review staged changes, then commit.`);
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+export function isCliEntrypoint(metaUrl, argvPath = process.argv[1]) {
+    if (!argvPath)
+        return false;
+    try {
+        const entrypointUrl = pathToFileURL(realpathSync(fileURLToPath(metaUrl))).href;
+        const argvUrl = pathToFileURL(realpathSync(argvPath)).href;
+        return entrypointUrl === argvUrl;
+    }
+    catch {
+        return metaUrl === pathToFileURL(argvPath).href;
+    }
+}
+if (isCliEntrypoint(import.meta.url)) {
     runCli().catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
         console.error(message);

package/dist/help.js

@@ -6,6 +6,7 @@ WPMoo Odoo lifecycle tooling.
 Usage:
   npx @wpmoo/odoo
   npx @wpmoo/odoo create --product <slug> --dev-repo-url <url> --source-repo-url <url>
+  npx @wpmoo/odoo status
   npx @wpmoo/odoo add-repo --repo-url <url>
   npx @wpmoo/odoo remove-repo --repo <name>
   npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
@@ -66,9 +67,28 @@ Daily actions:
   Generated environments also include ./moo for local compose commands such as ./moo start.
   Use ./moo or npx @wpmoo/odoo with the same daily action arguments.
 
-Doctor:
-  Run npx @wpmoo/odoo doctor from a generated environment root to check metadata,
-  compose files, daily scripts, source repo paths, .env ports, and Docker CLI access.
+Status and doctor:
+  status: fast and offline. Reads local environment metadata and files only.
+  doctor: deeper health check. May check Docker CLI access and GitHub workflows.
+
+Task recipes:
+  Create environment:
+    npx @wpmoo/odoo create --product <slug> --dev-repo-url <url> --source-repo-url <url>
+  Add source repo:
+    npx @wpmoo/odoo add-repo --repo-url <url>
+  Add module:
+    npx @wpmoo/odoo add-module --repo <source-repo> --module <module-name>
+  Run tests:
+    npx @wpmoo/odoo test <module[,module]> [--db <db>] [--mode init|update] [--tags <tags>]
+  Safe reset and recover:
+    npx @wpmoo/odoo snapshot [db] [snapshot-name]
+    npx @wpmoo/odoo reset
+    npx @wpmoo/odoo restore-snapshot <snapshot-name> [db]
+  Daily command checks:
+    npx @wpmoo/odoo status
+    npx @wpmoo/odoo doctor
+    npx @wpmoo/odoo logs [service]
+    npx @wpmoo/odoo restart
 
 Example:
   npx @wpmoo/odoo create \\

package/dist/status.js

@@ -0,0 +1,193 @@
+import { access, readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { defaultOdooVersion, markerPath } from './environment.js';
+import { isValidPathSegment, validateRepoPath } from './path-validation.js';
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseMetadata(content) {
+    const parsed = JSON.parse(content);
+    if (!isRecord(parsed)) {
+        throw new Error('metadata is not an object');
+    }
+    return parsed;
+}
+function sourceRepoPathsFromMetadata(metadata) {
+    const sourceRepoPaths = [];
+    const invalidSourceRepoPaths = [];
+    if (!Array.isArray(metadata.sourceRepos))
+        return { sourceRepoPaths, invalidSourceRepoPaths };
+    for (const repo of metadata.sourceRepos) {
+        const path = repo && typeof repo.path === 'string' ? repo.path.trim() : '';
+        if (!path)
+            continue;
+        if (!isValidPathSegment(path)) {
+            invalidSourceRepoPaths.push(path);
+            continue;
+        }
+        sourceRepoPaths.push(validateRepoPath(path));
+    }
+    return { sourceRepoPaths, invalidSourceRepoPaths };
+}
+async function missingCoreFiles(target, odooVersion) {
+    const missing = [];
+    const composeFile = `docker-compose_${odooVersion}.yml`;
+    const checks = [
+        { label: 'moo', path: join(target, 'moo') },
+        { label: 'README.md', path: join(target, 'README.md') },
+        { label: 'AGENTS.md', path: join(target, 'AGENTS.md') },
+        { label: composeFile, path: join(target, composeFile) },
+        { label: 'scripts/', path: join(target, 'scripts'), mustBeDirectory: true },
+    ];
+    for (const check of checks) {
+        if (!(await pathExists(check.path))) {
+            missing.push(check.label);
+            continue;
+        }
+        if (check.mustBeDirectory) {
+            const fileStat = await stat(check.path);
+            if (!fileStat.isDirectory())
+                missing.push(check.label);
+        }
+    }
+    return missing;
+}
+async function countModuleCandidatesInRepoPath(path) {
+    if (!(await pathExists(path)))
+        return 0;
+    const rootStat = await stat(path);
+    if (!rootStat.isDirectory())
+        return 0;
+    let count = 0;
+    const stack = [path];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const entries = await readdir(current, { withFileTypes: true });
+        let hasManifest = false;
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === '__manifest__.py') {
+                hasManifest = true;
+            }
+            else if (entry.isDirectory()) {
+                stack.push(join(current, entry.name));
+            }
+        }
+        if (hasManifest)
+            count += 1;
+    }
+    return count;
+}
+function summaryText(status) {
+    if (status.kind === 'no_environment')
+        return 'No WPMoo environment detected.';
+    if (status.kind === 'invalid_metadata')
+        return 'Environment metadata is invalid.';
+    const prefix = status.missingCoreFiles.length > 0 || status.invalidSourceRepoPaths.length > 0
+        ? 'Environment needs attention'
+        : 'Environment ready';
+    return `${prefix}: Odoo ${status.odooVersion}, source repos ${status.sourceRepoCount}, module candidates ${status.moduleCandidateCount}.`;
+}
+export async function getEnvironmentStatus(target) {
+    const metadataFullPath = join(target, markerPath);
+    if (!(await pathExists(metadataFullPath))) {
+        return {
+            kind: 'no_environment',
+            target,
+            metadataPath: markerPath,
+            recommendedNextAction: 'Run npx @wpmoo/odoo create ...',
+        };
+    }
+    let metadata;
+    try {
+        const content = await readFile(metadataFullPath, 'utf8');
+        metadata = parseMetadata(content);
+    }
+    catch (error) {
+        return {
+            kind: 'invalid_metadata',
+            target,
+            metadataPath: markerPath,
+            metadataError: errorMessage(error),
+            recommendedNextAction: 'Fix .wpmoo/odoo.json or run npx @wpmoo/odoo reset from a valid environment.',
+        };
+    }
+    const odooVersion = typeof metadata.odooVersion === 'string' && metadata.odooVersion.trim()
+        ? metadata.odooVersion.trim()
+        : defaultOdooVersion;
+    const { sourceRepoPaths, invalidSourceRepoPaths } = sourceRepoPathsFromMetadata(metadata);
+    const repoRoots = sourceRepoPaths.map((path) => join(target, 'odoo/custom/src/private', path));
+    let moduleCandidateCount = 0;
+    for (const repoRoot of repoRoots) {
+        moduleCandidateCount += await countModuleCandidatesInRepoPath(repoRoot);
+    }
+    const missingFiles = await missingCoreFiles(target, odooVersion);
+    let recommendedNextAction = 'Run npx @wpmoo/odoo doctor for deep checks or ./moo start.';
+    if (invalidSourceRepoPaths.length > 0) {
+        recommendedNextAction =
+            'Fix invalid source repo paths in .wpmoo/odoo.json, then run npx @wpmoo/odoo doctor.';
+    }
+    else if (missingFiles.length > 0) {
+        recommendedNextAction = 'Run npx @wpmoo/odoo reset, then npx @wpmoo/odoo doctor.';
+    }
+    else if (sourceRepoPaths.length === 0) {
+        recommendedNextAction = 'Run npx @wpmoo/odoo add-repo ...';
+    }
+    return {
+        kind: 'environment',
+        target,
+        metadataPath: markerPath,
+        odooVersion,
+        sourceRepoCount: sourceRepoPaths.length,
+        sourceRepoPaths,
+        invalidSourceRepoPaths,
+        moduleCandidateCount,
+        missingCoreFiles: missingFiles,
+        recommendedNextAction,
+    };
+}
+export function renderEnvironmentStatusSummary(status) {
+    return summaryText(status);
+}
+export function renderEnvironmentStatus(status) {
+    const lines = [`Status: ${summaryText(status)}`];
+    if (status.kind === 'no_environment') {
+        lines.push(`Metadata: missing ${status.metadataPath}`);
+        lines.push(`Next: ${status.recommendedNextAction}`);
+        return lines.join('\n');
+    }
+    if (status.kind === 'invalid_metadata') {
+        lines.push(`Metadata: invalid ${status.metadataPath}`);
+        lines.push(`Error: ${status.metadataError}`);
+        lines.push(`Next: ${status.recommendedNextAction}`);
+        return lines.join('\n');
+    }
+    lines.push(`Metadata: ${status.metadataPath}`);
+    lines.push(`Odoo: ${status.odooVersion}`);
+    lines.push(`Source repos: ${status.sourceRepoCount}`);
+    lines.push(`Source repo paths: ${status.sourceRepoPaths.length > 0 ? status.sourceRepoPaths.join(', ') : '(none configured)'}`);
+    if (status.invalidSourceRepoPaths.length > 0) {
+        lines.push(`Invalid source repo paths: ${status.invalidSourceRepoPaths.join(', ')}`);
+    }
+    lines.push(`Module candidates: ${status.moduleCandidateCount}`);
+    lines.push(`Missing core files: ${status.missingCoreFiles.length > 0 ? status.missingCoreFiles.join(', ') : '(none)'}`);
+    lines.push(`Next: ${status.recommendedNextAction}`);
+    return lines.join('\n');
+}
+export async function renderEnvironmentStatusForTarget(target) {
+    const status = await getEnvironmentStatus(target);
+    return renderEnvironmentStatus(status);
+}

package/dist/templates.js

@@ -122,26 +122,57 @@ Source repositories stay under \`odoo/custom/src/private\`. At container startup
 \`entrypoint.sh\` scans those repositories for addons and exposes them through
 \`/mnt/wpmoo-addons\`.
 
-## Common Commands
+## Daily Command Hub (\`./moo\`)
+
+\`./moo\` routes day-to-day service and module workflows to local scripts in
+\`./scripts/\` (for example \`start\`, \`logs\`, \`update\`, \`test\`, \`snapshot\`).
+\`./moo status\` and \`./moo doctor\` are package fallback commands that run via
+\`npx --yes @wpmoo/odoo@latest ...\`.
+
+### Start And Inspect Services
 
 \`\`\`bash
 cp .env.example .env
 ./moo start
-./moo logs
+./moo logs odoo
 ./moo shell
+./moo psql postgres
 ./moo stop
-./moo doctor
-./moo resetdb devel sale
+\`\`\`
+
+### Run, Update, And Test Modules
+
+\`\`\`bash
+./moo install ${allAddons(options)[0] ?? options.product}
+./moo update ${allAddons(options)[0] ?? options.product}
+./moo test ${allAddons(options)[0] ?? options.product}
+\`\`\`
+
+### Snapshot And Restore
+
+\`\`\`bash
 ./moo snapshot devel before-update
 ./moo restore-snapshot before-update devel
+\`\`\`
+
+### Lint
+
+\`\`\`bash
 ./moo lint
-./moo pot sale devel i18n/sale.pot
 \`\`\`
 
-Run tests for one planned product addon:
+### Export Translations
 
 \`\`\`bash
-./moo test ${allAddons(options)[0] ?? options.product}
+./moo pot ${allAddons(options)[0] ?? options.product} devel i18n/${allAddons(options)[0] ?? options.product}.pot
+\`\`\`
+
+### Recover / Reset
+
+\`\`\`bash
+./moo doctor
+./moo status
+./moo resetdb devel ${allAddons(options)[0] ?? options.product}
 \`\`\`
 `;
 }
@@ -576,6 +607,10 @@ Useful maintenance commands:
 ./moo pot <module[,module]> [db] [output]
 \`\`\`
 
+Daily script delegation vs package fallback:
+- \`./moo start\`, \`logs\`, \`install\`, \`update\`, \`test\`, \`snapshot\`, and related runtime tasks delegate to local \`./scripts/*.sh\`.
+- \`./moo status\` and \`./moo doctor\` are package fallback commands routed to \`npx --yes @wpmoo/odoo@latest ...\`.
+
 Only report completion after the relevant update/test/lint command exits cleanly.
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/odoo",
-  "version": "0.8.45",
+  "version": "0.8.47",
   "description": "WPMoo Odoo lifecycle tooling for development, staging, and production workflows.",
   "type": "module",
   "repository": {