@wpmoo/toolkit 0.9.24 → 0.9.25

package/dist/cli.js

@@ -271,7 +271,17 @@ async function showStartup(argv, skipUpdateCheck, details) {
     console.log();
 }
 async function selectCockpitCommandFromMenu(serviceStatus, moduleCount, sourceRepoCount) {
-    const selection = await selectCockpitTopLevelMenu({ serviceStatus, moduleCount, sourceRepoCount });
+    const legacyServiceStatus = serviceStatus.kind === 'services-running' ||
+        serviceStatus.kind === 'db-ready' ||
+        serviceStatus.kind === 'odoo-not-ready' ||
+        serviceStatus.kind === 'fully-ready'
+        ? { kind: 'running' }
+        : serviceStatus;
+    const selection = await selectCockpitTopLevelMenu({
+        serviceStatus: legacyServiceStatus,
+        moduleCount,
+        sourceRepoCount,
+    });
     if (selection.kind === 'exit') {
         return 'exit';
     }

package/dist/cockpit/daily-prompts.js

@@ -83,6 +83,18 @@ async function optionalTextArg(deps, message, fallback) {
         placeholder: fallback,
     }), fallback, deps);
 }
+async function optionalTextArgOrUndefined(deps, message, placeholder) {
+    const value = await deps.text({
+        message: menuPromptMessage(message, 'back'),
+        placeholder,
+    });
+    deps.handleCancel(value, 'back');
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
 async function databaseArg(cwd, deps, message, fallback, options = {}) {
     const databaseResult = normalizeDatabaseListResult(await deps.databases(cwd, options));
     const databases = databaseResult.databases;
@@ -139,7 +151,9 @@ export async function collectDailyActionArgs(command, cwd, promptDepsArg = {}) {
         return [];
     }
     if (command === 'logs') {
-        return [await optionalTextArg(deps, 'Service', 'odoo')];
+        const service = await optionalTextArg(deps, 'Service', 'odoo');
+        const tail = await optionalTextArgOrUndefined(deps, 'Tail line count (optional)', '100');
+        return tail ? [service, tail] : [service];
     }
     if (command === 'psql') {
         return [await databaseArg(cwd, deps, 'Database', 'postgres', { includeMaintenance: true })];

package/dist/daily-actions.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readEnvFile, selectedComposeEnvironment } from './compose-layout.js';
+import { normalizeDatabaseName } from './databases.js';
 import { markerPath } from './environment.js';
 export const dailyActionCommands = [
     'start',
@@ -49,7 +50,7 @@ function usage(command) {
     if (command === 'stop')
         return 'Usage: wpmoo stop';
     if (command === 'logs')
-        return 'Usage: wpmoo logs [service]';
+        return 'Usage: wpmoo logs [service] [tail-lines]';
     if (command === 'restart')
         return 'Usage: wpmoo restart';
     if (command === 'shell')
@@ -86,7 +87,7 @@ function moduleArgs(command, argv) {
     const [modules, db, ...rest] = argv;
     if (!modules || modules.startsWith('-') || rest.length > 0)
         throw new Error(usage(command));
-    return db ? [modules, db] : [modules];
+    return db ? [modules, normalizeDatabaseName(db)] : [modules];
 }
 function positionalArgs(command, argv, min, max) {
     if (argv.length < min || argv.length > max || argv.some((arg) => arg.startsWith('-'))) {
@@ -94,6 +95,32 @@ function positionalArgs(command, argv, min, max) {
     }
     return argv;
 }
+function logsArgs(argv) {
+    if (argv.length > 2 || argv.some((arg) => arg.startsWith('-'))) {
+        throw new Error(usage('logs'));
+    }
+    const [service = 'odoo', tail] = argv;
+    if (tail === undefined) {
+        return [service];
+    }
+    if (!/^[1-9][0-9]*$/u.test(tail)) {
+        throw new Error('Invalid logs tail count: expected a positive integer.');
+    }
+    return [service, tail];
+}
+function validateDatabaseArg(args, index) {
+    if (args[index] === undefined) {
+        return args;
+    }
+    const nextArgs = [...args];
+    nextArgs[index] = normalizeDatabaseName(nextArgs[index]);
+    return nextArgs;
+}
+function rejectLeadingHyphenDatabaseArg(args) {
+    if (args[0]?.startsWith('-')) {
+        normalizeDatabaseName(args[0]);
+    }
+}
 function restoreSnapshotArgs(argv) {
     const args = [...argv];
     const dryRun = args[0] === '--dry-run';
@@ -103,7 +130,8 @@ function restoreSnapshotArgs(argv) {
     if (args.length < 1 || args.length > 2 || args.some((arg) => arg.startsWith('-'))) {
         throw new Error(usage('restore-snapshot'));
     }
-    return dryRun ? ['--dry-run', ...args] : args;
+    const validatedArgs = args.length === 2 ? validateDatabaseArg(args, 1) : args;
+    return dryRun ? ['--dry-run', ...validatedArgs] : validatedArgs;
 }
 function testArgs(argv) {
     const [modules, ...rest] = argv;
@@ -119,6 +147,9 @@ function testArgs(argv) {
         if (option === '--mode' && value !== 'auto' && value !== 'init' && value !== 'update') {
             throw new Error('Invalid value for --mode: expected auto, init, or update');
         }
+        if (option === '--db') {
+            normalizeDatabaseName(value);
+        }
         index += 1;
     }
     return argv;
@@ -129,26 +160,30 @@ function scriptArgs(command, argv) {
     if (command === 'stop')
         return ensureNoArgs(command, argv);
     if (command === 'logs')
-        return optionalSingleArg(command, argv, 'odoo');
+        return logsArgs(argv);
     if (command === 'restart')
         return ensureNoArgs(command, argv);
     if (command === 'shell')
         return ensureNoArgs(command, argv);
     if (command === 'psql')
-        return optionalSingleArg(command, argv, 'postgres');
+        return optionalSingleArg(command, argv, 'postgres').map(normalizeDatabaseName);
     if (command === 'install' || command === 'update')
         return moduleArgs(command, argv);
     if (command === 'test')
         return testArgs(argv);
-    if (command === 'resetdb')
-        return positionalArgs(command, argv, 0, 2);
-    if (command === 'snapshot')
-        return positionalArgs(command, argv, 0, 2);
+    if (command === 'resetdb') {
+        rejectLeadingHyphenDatabaseArg(argv);
+        return validateDatabaseArg(positionalArgs(command, argv, 0, 2), 0);
+    }
+    if (command === 'snapshot') {
+        rejectLeadingHyphenDatabaseArg(argv);
+        return validateDatabaseArg(positionalArgs(command, argv, 0, 2), 0);
+    }
     if (command === 'restore-snapshot')
         return restoreSnapshotArgs(argv);
     if (command === 'lint')
         return ensureNoArgs(command, argv);
-    return positionalArgs(command, argv, 1, 3);
+    return validateDatabaseArg(positionalArgs(command, argv, 1, 3), 1);
 }
 function isDestructiveCommand(command, args) {
     if (command === 'resetdb')
@@ -263,6 +298,12 @@ function renderDailyActionOutputLine(line) {
     if (line === "Running as user 'root' is a security risk.") {
         return `${ANSI_DIM_INFO}${line}${ANSI_RESET}`;
     }
+    if (line.includes('psycopg2.OperationalError')) {
+        return [
+            line,
+            `${ANSI_DIM_INFO}NOTE: PostgreSQL connection failed. Check ./moo status, database service readiness, and credentials before retrying.${ANSI_RESET}`,
+        ].join('\n');
+    }
     return line;
 }
 export function renderDailyActionOutput(output) {

package/dist/databases.js

@@ -1,5 +1,29 @@
 import { spawn } from 'node:child_process';
 const maintenanceDatabases = new Set(['postgres']);
+const databaseNamePattern = /^[A-Za-z0-9_.-]+$/u;
+export function isValidDatabaseName(value) {
+    const normalized = value.trim();
+    return (normalized.length > 0 &&
+        !normalized.startsWith('-') &&
+        databaseNamePattern.test(normalized) &&
+        !/\s/u.test(value));
+}
+export function normalizeDatabaseName(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error('Invalid database name: value is required.');
+    }
+    if (/\s/u.test(value)) {
+        throw new Error('Invalid database name: whitespace is not allowed.');
+    }
+    if (normalized.startsWith('-')) {
+        throw new Error('Invalid database name: leading hyphens are not allowed.');
+    }
+    if (!databaseNamePattern.test(normalized)) {
+        throw new Error('Invalid database name: use letters, digits, underscores, dots, or hyphens without shell metacharacters or path characters.');
+    }
+    return normalized;
+}
 const listDatabasesQuery = [
     'SELECT datname',
     'FROM pg_database',

package/dist/help.js

@@ -24,7 +24,7 @@ Usage:
   npx @wpmoo/toolkit doctor --json [--postgres]
   npx @wpmoo/toolkit start
   npx @wpmoo/toolkit stop
-  npx @wpmoo/toolkit logs [service]
+  npx @wpmoo/toolkit logs [service] [tail-lines]
   npx @wpmoo/toolkit restart
   npx @wpmoo/toolkit shell
   npx @wpmoo/toolkit psql [db]
@@ -148,7 +148,7 @@ Task recipes:
     npx @wpmoo/toolkit status
     npx @wpmoo/toolkit doctor
     npx @wpmoo/toolkit doctor --fix
-    npx @wpmoo/toolkit logs [service]
+    npx @wpmoo/toolkit logs [service] [tail-lines]
     npx @wpmoo/toolkit restart
 
 Machine-readable JSON output:

package/dist/safe-reset.js

@@ -1,3 +1,5 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { environmentMetadata, readEnvironmentMetadata } from './environment.js';
@@ -29,35 +31,258 @@ const safeResetProtectedGeneratedReadmes = new Set([
 function isProtectedGeneratedFile(filePath) {
     return safeResetProtectedGeneratedReadmes.has(filePath);
 }
-function mergeEnvironmentMetadata(target, options) {
+function mergeEnvironmentMetadataSync(target, options) {
     const generated = environmentMetadata(options);
-    return readFile(join(target, '.wpmoo/odoo.json'), 'utf8')
-        .then((content) => JSON.parse(content))
-        .then((existing) => {
+    try {
+        const existing = parseMetadataFromPath(target);
         if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
             return `${JSON.stringify(generated, null, 2)}\n`;
         }
         return `${JSON.stringify({ ...existing, ...generated, sourceRepos: generated.sourceRepos }, null, 2)}\n`;
+    }
+    catch {
+        return `${JSON.stringify(generated, null, 2)}\n`;
+    }
+}
+function parseMetadataFromPath(target) {
+    try {
+        const raw = readFileSync(join(target, '.wpmoo/odoo.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseAddonsFile(target) {
+    try {
+        return readFileSync(join(target, 'odoo/custom/src/addons.yaml'), 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function parseGitmodules(target) {
+    try {
+        const gitmodules = readFileSync(join(target, '.gitmodules'), 'utf8');
+        const sections = gitmodules.split(/\n(?=\[submodule )/);
+        return sections.flatMap((section) => {
+            const pathMatch = section.match(/^\s*path\s*=\s*odoo\/custom\/src\/(private|oca|external)\/([^\s]+)\s*$/m);
+            if (!pathMatch) {
+                return [];
+            }
+            const source = section.match(/^\s*url\s*=\s*(.+)\s*$/m)?.[1]?.trim();
+            if (!source) {
+                return [];
+            }
+            const sourceType = pathMatch[1];
+            return [{ path: pathMatch[2], sourceType, url: source }];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function inferOptionsForPreviewSync(target) {
+    const metadata = parseMetadataFromPath(target);
+    const addonsYaml = parseAddonsFile(target);
+    const gitmoduleSources = parseGitmodules(target);
+    const addonRepos = parseRepoPathsFromAddonsYaml(addonsYaml);
+    const sourceByKey = new Map();
+    const sourceReposFromMetadata = Array.isArray(metadata?.sourceRepos)
+        ? metadata.sourceRepos
+        : [];
+    for (const repo of sourceReposFromMetadata) {
+        if (!repo?.path || !isValidPathSegment(repo.path)) {
+            continue;
+        }
+        sourceByKey.set(`${repo.sourceType ?? 'private'}:${repo.path}`, {
+            sourceType: repo.sourceType ?? 'private',
+            path: validateRepoPath(repo.path),
+        });
+    }
+    for (const repo of gitmoduleSources) {
+        sourceByKey.set(`${repo.sourceType}:${repo.path}`, repo);
+    }
+    for (const repoPath of addonRepos) {
+        sourceByKey.set(`private:${repoPath}`, {
+            sourceType: 'private',
+            path: repoPath,
+        });
+    }
+    const sourceLocations = [...sourceByKey.values()].sort((left, right) => {
+        if (left.sourceType !== right.sourceType) {
+            return left.sourceType.localeCompare(right.sourceType);
+        }
+        return left.path.localeCompare(right.path);
+    });
+    const productFromMetadata = typeof metadata?.product === 'string' ? metadata.product : undefined;
+    const composeTemplateUrl = typeof metadata?.composeTemplateUrl === 'string' ? metadata.composeTemplateUrl : undefined;
+    const composeTemplateRef = typeof metadata?.composeTemplateRef === 'string' ? metadata.composeTemplateRef : undefined;
+    const agentSkillsTemplateUrl = typeof metadata?.agentSkillsTemplateUrl === 'string'
+        ? metadata.agentSkillsTemplateUrl
+        : undefined;
+    const agentSkillsTemplateRef = typeof metadata?.agentSkillsTemplateRef === 'string'
+        ? metadata.agentSkillsTemplateRef
+        : undefined;
+    const odooVersion = typeof metadata?.odooVersion === 'string' ? metadata.odooVersion : undefined;
+    const devRepo = typeof metadata?.devRepo === 'string' ? metadata.devRepo : undefined;
+    const devRepoUrl = typeof metadata?.devRepoUrl === 'string' ? metadata.devRepoUrl : undefined;
+    const postgresVersion = typeof metadata?.postgresVersion === 'string' ? metadata.postgresVersion : undefined;
+    const httpPort = typeof metadata?.httpPort === 'string' ? metadata.httpPort : undefined;
+    const geventPort = typeof metadata?.geventPort === 'string' ? metadata.geventPort : undefined;
+    const product = productFromMetadata && isValidPathSegment(productFromMetadata) ? productFromMetadata
+        : sourceLocations[0]?.path ?? titleFromTarget(target);
+    return {
+        product,
+        odooVersion: odooVersion ?? '19.0',
+        devRepo: devRepo ?? basename(target),
+        devRepoUrl: devRepoUrl ?? target,
+        sourceRepos: sourceLocations.map(({ sourceType, path }) => {
+            const metadataMatch = sourceReposFromMetadata.find((repo) => isValidPathSegment(repo.path ?? '') && validateRepoPath(repo.path ?? '') === path && (repo.sourceType ?? 'private') === sourceType);
+            const gitmoduleMatch = gitmoduleSources.find((repo) => repo.path === path && repo.sourceType === sourceType);
+            return {
+                sourceType,
+                path,
+                url: metadataMatch?.url?.trim() ||
+                    gitmoduleMatch?.url ||
+                    readSubmoduleUrlFromPath(target, path, sourceType),
+                addons: parseAddonsForRepo(addonsYaml, path),
+            };
+        }),
+        engine: 'compose',
+        composeTemplateUrl,
+        composeTemplateRef,
+        agentSkillsTemplateUrl,
+        agentSkillsTemplateRef,
+        postgresVersion,
+        httpPort,
+        geventPort,
+        target,
+        dryRun: false,
+        initEmptyRepos: false,
+        stage: false,
+        skipSubmodules: true,
+    };
+}
+function readSubmoduleUrlFromPath(target, repoPath, sourceType) {
+    try {
+        const gitmodules = readFileSync(join(target, '.gitmodules'), 'utf8');
+        const escapedPath = `odoo/custom/src/${sourceType}/${repoPath}`;
+        const sections = gitmodules.split(/\n(?=\[submodule )/);
+        const section = sections.find((value) => value.includes(`path = ${escapedPath}`));
+        const url = section?.match(/^\s*url\s*=\s*(.+)$/m)?.[1]?.trim();
+        return url || `odoo/custom/src/${sourceType}/${repoPath}`;
+    }
+    catch {
+        return `odoo/custom/src/${sourceType}/${repoPath}`;
+    }
+}
+function safeResetTargetFileDiffs(scaffoldOptions, target) {
+    const files = generatedFiles(scaffoldOptions);
+    const candidates = [
+        ...files,
+        { path: '.env.example', content: renderComposeEnvExample(scaffoldOptions) },
+        { path: '.wpmoo/odoo.json', content: mergeEnvironmentMetadataSync(target, scaffoldOptions) },
+    ];
+    const changedPaths = candidates
+        .filter((file) => {
+        if (file.path === 'odoo/custom/src/addons.yaml' || isProtectedGeneratedFile(file.path)) {
+            return false;
+        }
+        const existing = readTextForPreview(target, file.path);
+        if (existing === undefined) {
+            return true;
+        }
+        return existing !== file.content;
     })
-        .catch(() => `${JSON.stringify(generated, null, 2)}\n`);
+        .map((file) => file.path);
+    return [...new Set(changedPaths)].sort();
+}
+function buildSafeResetSourceRepoLines(sourceRepos) {
+    const lines = [...new Set(sourceRepos.map((repo) => `${repo.sourceType ?? 'private'}/${repo.path}`))].sort();
+    if (lines.length === 0) {
+        return ['- (none detected)'];
+    }
+    return lines.map((repo) => `- ${repo}`);
+}
+function detectDirtyGeneratedFiles(target, candidatePaths) {
+    try {
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd: target,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        if (!status.trim()) {
+            return [];
+        }
+        const dirty = new Set();
+        const trackedCandidates = [...candidatePaths];
+        for (const entry of status.split(/\r?\n/)) {
+            if (!entry.trim()) {
+                continue;
+            }
+            const pathSection = entry.slice(3).trim();
+            const normalized = pathSection.includes(' -> ') ? pathSection.split(' -> ')[1] ?? '' : pathSection;
+            if (!normalized) {
+                continue;
+            }
+            if (trackedCandidates.some((candidate) => normalized === candidate || normalized.startsWith(`${candidate}/`))) {
+                dirty.add(normalized);
+            }
+        }
+        return [...dirty].sort();
+    }
+    catch {
+        return [];
+    }
+}
+function describeDirtyWarning(target, candidatePaths) {
+    const dirtyFiles = detectDirtyGeneratedFiles(target, candidatePaths);
+    if (dirtyFiles.length === 0) {
+        return [];
+    }
+    return [
+        'Warning: the following generated files are dirty and may be overwritten by safe reset:',
+        ...dirtyFiles.map((path) => `- ${path}`),
+    ];
+}
+function readTextForPreview(target, path) {
+    try {
+        return readFileSync(join(target, path), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
 }
 export function renderSafeResetPreview(target, stage) {
+    const options = inferOptionsForPreviewSync(target);
+    const externalAssets = safeResetExternalAssetOptions(options);
+    const changedPaths = safeResetTargetFileDiffs(options, target);
+    const externalAssetLines = [];
+    if (externalAssets.some((asset) => asset.label === 'compose')) {
+        externalAssetLines.push('- External compose template assets');
+    }
+    if (externalAssets.some((asset) => asset.label === 'agent-skills')) {
+        externalAssetLines.push('- External agent skill assets when configured');
+    }
+    const generatedSection = changedPaths.length
+        ? ['Generated files that would change:', ...changedPaths.map((file) => `- ${file}`)]
+        : ['Generated files that would change:', '- No generated files differ from the rendered safe-reset output.'];
     return [
-        'Safe reset will refresh generated WPMoo environment files.',
+        'Safe reset preview (dry-run): generated WPMoo files and source repo protections are listed.',
         '',
         'Target:',
         target,
         '',
-        'Will update:',
-        '- .wpmoo/odoo.json',
-        '- moo',
-        '- .gitignore',
-        '- .env.example',
-        '- README.md',
-        '- AGENTS.md',
-        '- docs/appstore-release.md',
-        '- External compose template assets',
-        '- External agent skill assets when configured',
+        ...generatedSection,
+        ...externalAssetLines,
+        '',
+        'Source repositories that will remain untouched:',
+        ...buildSafeResetSourceRepoLines(options.sourceRepos),
         '',
         'Will not touch:',
         '- source repo folders under odoo/custom/src/private',
@@ -67,6 +292,8 @@ export function renderSafeResetPreview(target, stage) {
         '- custom source layout directories (oca, external, patches, manifests)',
         '- Legacy compose template files may remain until manually removed: docs/assets/, test/, .github/',
         '',
+        ...describeDirtyWarning(target, changedPaths),
+        '',
         'Preview-only output; files are not changed until reset is executed.',
         '',
         stage ? 'Generated changes will be staged with git add .' : 'Generated changes will not be staged.',
@@ -209,7 +436,7 @@ export async function safeResetEnvironment(options, git = realGit) {
     for (const assetOptions of externalAssets) {
         await applyExternalAsset(assetOptions, git);
     }
-    await writeTextFile(join(options.target, '.wpmoo/odoo.json'), await mergeEnvironmentMetadata(options.target, scaffoldOptions));
+    await writeTextFile(join(options.target, '.wpmoo/odoo.json'), mergeEnvironmentMetadataSync(options.target, scaffoldOptions));
     await writeTextFile(join(options.target, '.env.example'), renderComposeEnvExample(scaffoldOptions));
     if (options.stage) {
         await stageAll(git, options.target);

package/dist/scaffold.js

@@ -4,7 +4,7 @@ import { applyExternalAsset, renderExternalAssetCommand, writeTextFile } from '.
 import { markerPath, renderEnvironmentMetadata } from './environment.js';
 import { plannedExternalAssetOptions, renderComposeEnvExample } from './external-templates.js';
 import { cloneRepository, ensureSubmodule, ensureRemoteHasBranch, realGit, stageAll, syncSubmodules, } from './git.js';
-import { renderAgents, renderAppstoreRelease, renderGitignore, renderMooDelegationScript, renderPlaceholder, renderReadme, renderStatusScript, } from './templates.js';
+import { renderAgents, renderAppstoreRelease, renderDoctorScript, renderGitignore, renderMooDelegationScript, renderPlaceholder, renderReadme, renderStatusScript, } from './templates.js';
 import { validateAddonName, validateRepoPath } from './path-validation.js';
 import { renderSourceManifest, sourceManifestEntriesFromMetadata } from './source-manifest.js';
 function validateSourceRepo(repo) {
@@ -58,6 +58,7 @@ export function generatedFiles(options) {
         { path: markerPath, content: renderEnvironmentMetadata(safeOptions) },
         { path: 'moo', content: renderMooDelegationScript(), mode: 0o755 },
         { path: 'scripts/status.sh', content: renderStatusScript(), mode: 0o755 },
+        { path: 'scripts/doctor.sh', content: renderDoctorScript(), mode: 0o755 },
         { path: '.gitignore', content: renderGitignore() },
         { path: 'README.md', content: renderReadme(safeOptions) },
         { path: 'AGENTS.md', content: renderAgents(safeOptions) },

package/dist/service-runtime-status.js

@@ -1,4 +1,6 @@
 import { execFile } from 'node:child_process';
+const odooHttpReadyUrl = 'http://127.0.0.1:8069';
+const odooHttpProbeTimeoutMs = 1_000;
 function run(command, args, options) {
     return new Promise((resolve, reject) => {
         execFile(command, args, { cwd: options.cwd }, (error, stdout) => {
@@ -10,11 +12,36 @@ function run(command, args, options) {
         });
     });
 }
+async function fetchOdooHttpReady() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), odooHttpProbeTimeoutMs);
+    try {
+        return await fetch(odooHttpReadyUrl, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 export function renderServiceRuntimeStatusLine(status) {
-    if (status.kind === 'running')
+    if (status.kind === 'running' ||
+        status.kind === 'services-running' ||
+        status.kind === 'odoo-not-ready' ||
+        status.kind === 'fully-ready' ||
+        status.kind === 'db-ready') {
+        if (status.kind === 'db-ready') {
+            return 'Status: ● DB ready';
+        }
+        if (status.kind === 'odoo-not-ready') {
+            return 'Status: ● Odoo not ready';
+        }
+        if (status.kind === 'fully-ready') {
+            return 'Status: ● Fully ready';
+        }
         return 'Status: ● Services running';
-    if (status.kind === 'docker-not-running')
+    }
+    if (status.kind === 'docker-not-running') {
         return 'Status: ● Docker not running';
+    }
     return 'Status: ● Services stopped';
 }
 export async function getServiceRuntimeStatus(target, environmentStatus, runner = run) {
@@ -44,5 +71,40 @@ export async function getServiceRuntimeStatus(target, environmentStatus, runner
     catch {
         return { kind: 'stopped' };
     }
-    return result.stdout.trim() ? { kind: 'running' } : { kind: 'stopped' };
+    if (!result.stdout.trim()) {
+        return { kind: 'stopped' };
+    }
+    const runningServices = result.stdout
+        .trim()
+        .split('\n')
+        .map((service) => service.trim())
+        .filter(Boolean);
+    if (!runningServices.includes('db')) {
+        return { kind: 'services-running' };
+    }
+    const dbProbeArgs = [
+        'compose',
+        ...environmentStatus.composeFiles.flatMap((file) => ['-f', file]),
+        'exec',
+        '-T',
+        'db',
+        'pg_isready',
+        '-U',
+        'odoo',
+        '-d',
+        'postgres',
+    ];
+    try {
+        await runner('docker', dbProbeArgs, { cwd: target });
+    }
+    catch {
+        return { kind: 'services-running' };
+    }
+    try {
+        const response = await fetchOdooHttpReady();
+        return response.ok ? { kind: 'fully-ready' } : { kind: 'odoo-not-ready' };
+    }
+    catch {
+        return { kind: 'db-ready' };
+    }
 }

package/dist/templates.js

@@ -226,8 +226,8 @@ exposes them through \`/mnt/wpmoo-addons\`.
 \`./moo\` routes day-to-day service and module workflows to local scripts in
 \`./scripts/\` (for example \`start\`, \`logs\`, \`update\`, \`test\`, \`snapshot\`).
 \`./moo status\` runs local offline metadata checks without needing network access.
-\`./moo doctor\` remains the package fallback command and runs via
-\`npx --yes ${fallbackPackageSpec()} doctor\`.
+\`./moo doctor\` runs local checks first and uses the package fallback only for
+advanced usage (for example \`--help\`) via \`npx --yes ${fallbackPackageSpec()} doctor\`.
 
 ### Start And Inspect Services
 
@@ -449,7 +449,7 @@ usage() {
   case "$1" in
     "start") echo "Usage: ./moo start" ;;
     "stop") echo "Usage: ./moo stop" ;;
-    "logs") echo "Usage: ./moo logs [service]" ;;
+    "logs") echo "Usage: ./moo logs [service] [tail-lines]" ;;
     "restart") echo "Usage: ./moo restart" ;;
     "shell") echo "Usage: ./moo shell" ;;
     "psql") echo "Usage: ./moo psql [db]" ;;
@@ -657,7 +657,14 @@ case "$command" in
     fi
     run_package_command "$command" "$@"
     ;;
-  "create"|"add-repo"|"remove-repo"|"add-module"|"remove-module"|"source"|"reset"|"doctor")
+  "doctor")
+    shift
+    if [[ "$#" -eq 0 && -x ./scripts/doctor.sh ]]; then
+      run_script ./scripts/doctor.sh
+    fi
+    run_package_command "$command" "$@"
+    ;;
+  "create"|"add-repo"|"remove-repo"|"add-module"|"remove-module"|"source"|"reset")
     run_package_command "$@"
     ;;
   "start")
@@ -672,7 +679,17 @@ case "$command" in
     ;;
   "logs")
     shift
-    service="$(optional_single_arg "$command" "odoo" "$@")"
+    if [[ "$#" -gt 2 || "\${1:-}" == -* || "\${2:-}" == -* ]]; then
+      fail_usage "$command"
+    fi
+    service="\${1:-odoo}"
+    if [[ "$#" -eq 2 ]]; then
+      if [[ ! "$2" =~ ^[1-9][0-9]*$ ]]; then
+        echo "Invalid logs tail count: expected a positive integer." >&2
+        exit 2
+      fi
+      run_script ./scripts/logs.sh "$service" "$2"
+    fi
     run_script ./scripts/logs.sh "$service"
     ;;
   "restart")
@@ -753,6 +770,91 @@ case "$command" in
 esac
 `;
 }
+export function renderDoctorScript() {
+    return `#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "\${BASH_SOURCE[0]}")" && pwd)"
+root_dir="$(cd -- "$script_dir/.." && pwd)"
+cd "$root_dir"
+
+echo "WPMoo doctor"
+
+issues=()
+warnings=()
+
+required_files=(
+  "moo"
+)
+
+required_scripts=(
+  "up.sh"
+  "down.sh"
+  "logs.sh"
+  "restart.sh"
+  "shell.sh"
+  "psql.sh"
+  "install.sh"
+  "update.sh"
+  "test.sh"
+  "resetdb.sh"
+  "snapshot.sh"
+  "restore-snapshot.sh"
+  "lint.sh"
+  "pot.sh"
+  "status.sh"
+)
+
+for file in "\${required_files[@]}"; do
+  if [[ ! -f "$file" ]]; then
+    issues+=("missing required file: $file")
+  fi
+done
+
+for script in "\${required_scripts[@]}"; do
+  script_path="scripts/$script"
+  if [[ ! -f "$script_path" ]]; then
+    issues+=("missing required script: $script_path")
+    continue
+  fi
+  if [[ ! -x "$script_path" ]]; then
+    issues+=("not executable: $script_path")
+  fi
+done
+
+if [[ ! -d scripts ]]; then
+  issues+=("missing scripts directory")
+fi
+
+if [[ ! -d odoo/custom/src ]]; then
+  warnings+=("odoo/custom/src is missing; add source repositories before running module workflows.")
+fi
+
+if [[ ! -f .wpmoo/odoo.json ]]; then
+  warnings+=("missing .wpmoo/odoo.json; run ./moo reset to initialize environment metadata.")
+fi
+
+if (( \${#issues[@]} > 0 )); then
+  echo "Doctor checks found issues."
+  for issue in "\${issues[@]}"; do
+    echo " - $issue"
+  done
+  if (( \${#warnings[@]} > 0 )); then
+    for warning in "\${warnings[@]}"; do
+      echo " - warning: $warning"
+    done
+  fi
+  exit 1
+fi
+
+echo "Doctor checks passed."
+if (( \${#warnings[@]} > 0 )); then
+  for warning in "\${warnings[@]}"; do
+    echo " - warning: $warning"
+  done
+fi
+`;
+}
 export function renderStatusScript() {
     return `#!/usr/bin/env bash
 set -euo pipefail
@@ -1360,7 +1462,7 @@ Useful maintenance commands:
 Daily script delegation vs package fallback:
 - \`./moo start\`, \`logs\`, \`install\`, \`update\`, \`test\`, \`snapshot\`, and related runtime tasks delegate to local \`./scripts/*.sh\`.
 - \`./moo status\` runs local offline metadata checks through \`./scripts/status.sh\`.
-- \`./moo doctor\` remains a package fallback command routed to \`npx --yes ${fallbackPackageSpec()} doctor\`.
+- \`./moo doctor\` runs local checks first and uses package fallback for advanced usage, routed via \`npx --yes ${fallbackPackageSpec()} doctor\`.
 
 Only report completion after the relevant update/test/lint command exits cleanly.
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpmoo/toolkit",
-  "version": "0.9.24",
+  "version": "0.9.25",
   "description": "WPMoo Toolkit for development, staging, and production lifecycle workflows.",
   "type": "module",
   "repository": {