@wpmoo/toolkit 0.9.2 → 0.9.3

package/README.md

@@ -23,25 +23,26 @@ WPMoo Toolkit is an independent project and is not affiliated with, endorsed by,
 - Optionally copy project-local Agent Skills from `wpmoo-org/odoo-skills` into generated environments.
 - Use either a guided terminal cockpit or direct CLI commands for the same lifecycle tasks.
 
-## Requirements
+## Prerequisites
 
-- Node.js `>=20.17`
+- Node.js `20.17+`
 - Git
-- Docker and Docker Compose for generated environment runtime commands
-- GitHub CLI (`gh`) is optional. Use it for repository discovery, repository creation, and deeper diagnostics.
+- Docker + Docker Compose for generated environment runtime commands
+- For GitHub-connected setup, install and authenticate GitHub CLI:
+
+  ```bash
+  brew install gh
+  gh auth login
+  ```
+
+GitHub CLI (`gh`) is optional.
+WPMoo uses `gh` to inspect source/dev repositories and to create missing repos during setup. It also uses repository inspection to detect existing non-empty dev repositories and avoid overwriting them; if you do not want GitHub checks, keep setup local-only.
 
 The wizard currently offers Odoo `19.0`, `18.0`, `17.0`, and `16.0`. Generated
 environments now use the compact compose layout (`compose.yaml` with
 `compose/<env>.yaml` overlays). Legacy root-level
 `docker-compose_<version>.yml` layouts are still supported for compatibility.
 
-Set up GitHub CLI only when you want WPMoo to discover your personal account and organizations or create missing repositories from the interactive wizard:
-
-```bash
-brew install gh
-gh auth login
-```
-
 ## Quick Start
 
 Run the guided wizard from a workspace directory:

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { realpathSync } from 'node:fs';
+import { rm, rename } from 'node:fs/promises';
 import { basename, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { commandFromArgs, isHelpRequested, isVersionRequested, optionsFromArgs, parseArgs, stripInternalFlags, } from './args.js';
@@ -21,7 +22,9 @@ import { inferGitHubOwner, inferRepoPath, normalizeRepositoryUrl } from './repo-
 import { addModuleRepo, listModuleRepos, removeModuleRepo } from './repo-actions.js';
 import { renderSafeResetPreview, safeResetEnvironment } from './safe-reset.js';
 import { listSources, renderSourceList, sourceListJson, sourceSyncJson, syncSources, } from './source-actions.js';
-import { checkGitHubRepositories, createGitHubRepositories, manualCreateCommands, repositoryPreflightAvailable, } from './repository-preflight.js';
+import { backupTargetPath, expectedTargetConfirmation, inspectEnvironmentTarget, renderExistingEnvironmentSummary, renderForeignEnvironmentTargetWarning, } from './environment-target-preflight.js';
+import { getGitHubPrerequisiteStatus, renderGitHubPrerequisiteGuidance, } from './github-prerequisites.js';
+import { checkGitHubRepositories, createGitHubRepositories, manualCreateCommands, } from './repository-preflight.js';
 import { scaffold } from './scaffold.js';
 import { confirmPrompt, introPrompt, isPromptCancel, notePrompt, outroPrompt, selectPrompt, textPrompt } from './prompts/index.js';
 import { renderBanner } from './templates.js';
@@ -223,6 +226,99 @@ async function selectCockpitCommandFromMenu() {
     }
     return selection.command;
 }
+async function resolveEnvironmentTargetFromPrompts(product, cancelAction) {
+    const defaultTarget = `./${product}_dev`;
+    while (true) {
+        const target = resolve(asString(await textPrompt({
+            message: 'Environment folder',
+            placeholder: defaultTarget,
+            defaultValue: defaultTarget,
+            initialValue: defaultTarget,
+        }), defaultTarget, cancelAction));
+        const state = await inspectEnvironmentTarget(target);
+        if (state.kind === 'missing_target') {
+            return { kind: 'create', target };
+        }
+        if (state.kind === 'foreign_target') {
+            notePrompt(renderForeignEnvironmentTargetWarning(state), 'Environment folder exists');
+            const action = await selectPrompt({
+                message: 'What do you want to do?',
+                options: [
+                    { value: 'choose-another-folder', label: 'Choose another folder' },
+                    { value: 'cancel', label: 'Cancel' },
+                ],
+                initialValue: 'choose-another-folder',
+            });
+            handleCancel(action, cancelAction);
+            if (action === 'choose-another-folder') {
+                continue;
+            }
+            return { kind: 'cancelled' };
+        }
+        notePrompt(renderExistingEnvironmentSummary(state), 'Existing environment');
+        const action = await selectPrompt({
+            message: 'This environment folder already exists. What do you want to do?',
+            options: [
+                { value: 'update-existing', label: 'Update existing environment' },
+                { value: 'reinstall-environment', label: 'Reinstall environment from backup' },
+                { value: 'delete-environment', label: 'Delete environment' },
+                { value: 'cancel', label: 'Cancel' },
+            ],
+            initialValue: 'update-existing',
+        });
+        handleCancel(action, cancelAction);
+        if (action === 'update-existing') {
+            await safeResetEnvironment({ target, stage: true });
+            return { kind: 'updated', target };
+        }
+        if (action === 'reinstall-environment') {
+            const backup = backupTargetPath(target);
+            await rename(target, backup);
+            notePrompt(`Existing environment moved to:\n${backup}`, 'Environment backup');
+            return { kind: 'create', target };
+        }
+        if (action === 'delete-environment') {
+            const expectedName = basename(target);
+            const confirmation = await textPrompt({
+                message: `Type ${expectedName} to confirm deletion`,
+                validate: (value) => (expectedTargetConfirmation(target, value) ? undefined : `Type ${expectedName} exactly to confirm.`),
+            });
+            handleCancel(confirmation, cancelAction);
+            if (!expectedTargetConfirmation(target, String(confirmation))) {
+                throw new Error(`Deletion confirmation did not match ${expectedName}.`);
+            }
+            await rm(target, { recursive: true, force: true });
+            return { kind: 'deleted', target };
+        }
+        return { kind: 'cancelled' };
+    }
+}
+async function promptGitHubPrerequisites(cancelAction) {
+    while (true) {
+        const status = await getGitHubPrerequisiteStatus();
+        if (status.status === 'ready') {
+            return true;
+        }
+        notePrompt(renderGitHubPrerequisiteGuidance(status), 'GitHub prerequisites');
+        const action = await selectPrompt({
+            message: 'GitHub repository prerequisites',
+            options: [
+                { value: 'retry', label: 'Retry prerequisite check' },
+                { value: 'continue-local-only', label: 'Continue local-only' },
+                { value: 'cancel', label: 'Cancel' },
+            ],
+            initialValue: 'retry',
+        });
+        handleCancel(action, cancelAction);
+        if (action === 'retry') {
+            continue;
+        }
+        if (action === 'continue-local-only') {
+            return false;
+        }
+        throw new Error('GitHub prerequisites were not completed.');
+    }
+}
 async function optionsFromPrompts(showIntro = true, cancelAction = 'exit') {
     if (showIntro) {
         introPrompt('Create Odoo dev environment');
@@ -232,13 +328,11 @@ async function optionsFromPrompts(showIntro = true, cancelAction = 'exit') {
         placeholder: 'odoo_sample_module',
         validate: (value) => (value.trim() ? undefined : 'Enter a product/module slug.'),
     }), 'odoo_sample_module', cancelAction);
-    const defaultTarget = `./${product}_dev`;
-    const target = resolve(asString(await textPrompt({
-        message: 'Environment folder',
-        placeholder: defaultTarget,
-        defaultValue: defaultTarget,
-        initialValue: defaultTarget,
-    }), defaultTarget, cancelAction));
+    const targetResult = await resolveEnvironmentTargetFromPrompts(product, cancelAction);
+    if (targetResult.kind !== 'create') {
+        return targetResult;
+    }
+    const { target } = targetResult;
     const connectGitHub = await selectPrompt({
         message: 'Connect this environment to Git/GitHub now?',
         options: [
@@ -249,7 +343,8 @@ async function optionsFromPrompts(showIntro = true, cancelAction = 'exit') {
     });
     handleCancel(connectGitHub, cancelAction);
     let selectedGitHubOwner;
-    if (connectGitHub) {
+    const useGitHub = Boolean(connectGitHub) && (await promptGitHubPrerequisites(cancelAction));
+    if (useGitHub) {
         notePrompt(renderRepositorySetupNote(product), 'Repository setup');
         selectedGitHubOwner = await selectDefaultGitHubOwner(cancelAction);
     }
@@ -272,23 +367,26 @@ async function optionsFromPrompts(showIntro = true, cancelAction = 'exit') {
         handleCancel(installAgentSkills, cancelAction);
         return Boolean(installAgentSkills);
     }
-    if (!connectGitHub) {
+    if (!useGitHub) {
         const installAgentSkills = await promptInstallAgentSkills();
         return {
-            product,
-            odooVersion,
-            engine: 'compose',
-            devRepo: basename(target),
-            devRepoUrl: target,
-            sourceRepos: [],
-            target,
-            dryRun: false,
-            initEmptyRepos: false,
-            stage: false,
-            agentSkillsTemplateUrl: installAgentSkills ? defaultAgentSkillsTemplateUrl : undefined,
-            createMissingRepos: false,
-            repoVisibility: 'private',
-            skipSubmodules: true,
+            kind: 'create',
+            options: {
+                product,
+                odooVersion,
+                engine: 'compose',
+                devRepo: basename(target),
+                devRepoUrl: target,
+                sourceRepos: [],
+                target,
+                dryRun: false,
+                initEmptyRepos: false,
+                stage: false,
+                agentSkillsTemplateUrl: installAgentSkills ? defaultAgentSkillsTemplateUrl : undefined,
+                createMissingRepos: false,
+                repoVisibility: 'private',
+                skipSubmodules: true,
+            },
         };
     }
     const detectedDevRepoUrl = await getOriginUrl(realGit, target);
@@ -343,19 +441,22 @@ async function optionsFromPrompts(showIntro = true, cancelAction = 'exit') {
     });
     handleCancel(initEmpty, cancelAction);
     return {
-        product,
-        odooVersion,
-        engine: 'compose',
-        devRepo: inferRepoPath(devRepoUrl),
-        devRepoUrl,
-        sourceRepos,
-        target,
-        dryRun: false,
-        initEmptyRepos: Boolean(initEmpty),
-        stage: true,
-        agentSkillsTemplateUrl: Boolean(installAgentSkills) ? defaultAgentSkillsTemplateUrl : undefined,
-        createMissingRepos: false,
-        repoVisibility: 'private',
+        kind: 'create',
+        options: {
+            product,
+            odooVersion,
+            engine: 'compose',
+            devRepo: inferRepoPath(devRepoUrl),
+            devRepoUrl,
+            sourceRepos,
+            target,
+            dryRun: false,
+            initEmptyRepos: Boolean(initEmpty),
+            stage: true,
+            agentSkillsTemplateUrl: Boolean(installAgentSkills) ? defaultAgentSkillsTemplateUrl : undefined,
+            createMissingRepos: false,
+            repoVisibility: 'private',
+        },
     };
 }
 async function addRepoOptionsFromArgs(argv) {
@@ -403,9 +504,10 @@ async function addRepoOptionsFromPrompts(showIntro = true, cancelAction = 'exit'
     };
 }
 async function ensureAddRepoGitHubRepository(options, cancelAction = 'exit') {
-    if (!(await repositoryPreflightAvailable())) {
+    const prerequisiteStatus = await getGitHubPrerequisiteStatus();
+    if (prerequisiteStatus.status !== 'ready') {
         notePrompt([
-            'GitHub CLI (`gh`) is not available or not authenticated.',
+            renderGitHubPrerequisiteGuidance(prerequisiteStatus),
             'The source repo will be used as-is. If it does not exist, create it first or authenticate gh.',
         ].join('\n'), 'Repository check skipped');
         return;
@@ -711,23 +813,29 @@ async function ensureGitHubRepositories(options, interactive) {
     if (!interactive && !options.createMissingRepos) {
         return;
     }
-    if (!(await repositoryPreflightAvailable())) {
-        const message = [
-            'GitHub CLI (`gh`) is not available or not authenticated.',
-            'Install and authenticate it to auto-create missing GitHub repositories:',
-            '',
-            'brew install gh',
-            'gh auth login',
-        ].join('\n');
-        if (options.createMissingRepos) {
+    const prerequisiteStatus = await getGitHubPrerequisiteStatus();
+    if (prerequisiteStatus.status !== 'ready') {
+        const message = renderGitHubPrerequisiteGuidance(prerequisiteStatus);
+        if (options.createMissingRepos || !interactive) {
             throw new Error(message);
         }
-        if (interactive) {
-            notePrompt(message, 'Repository check skipped');
-        }
+        notePrompt(message, 'GitHub prerequisites');
         return;
     }
-    const { accessible, inaccessible: missing } = await checkGitHubRepositories(options);
+    const { accessible, inaccessible: missing, blocked } = await checkGitHubRepositories(options);
+    if (blocked.length > 0) {
+        const blockedList = blocked
+            .map((repository) => `- ${repository.label}: ${repository.slug}`)
+            .join('\n');
+        notePrompt([
+            'These dev environment repositories already contain files and cannot be used automatically:',
+            '',
+            blockedList,
+            '',
+            'Choose another dev repository, empty the existing repository, or cancel and handle it manually.',
+        ].join('\n'), 'Repository check blocked');
+        throw new Error(`Dev environment repository is non-empty or could not be verified: ${blocked.map((repo) => repo.slug).join(', ')}`);
+    }
     if (interactive && accessible.length > 0) {
         notePrompt([
             'These GitHub repositories already exist and are accessible:',
@@ -773,6 +881,50 @@ async function ensureGitHubRepositories(options, interactive) {
     handleCancel(visibility, 'exit');
     await createGitHubRepositories(missing, visibility);
 }
+async function ensureNonInteractiveCreateTarget(options) {
+    if (options.dryRun) {
+        return;
+    }
+    const state = await inspectEnvironmentTarget(options.target);
+    if (state.kind === 'missing_target') {
+        return;
+    }
+    if (state.kind === 'existing_environment') {
+        throw new Error([
+            `Target already contains a WPMoo environment: ${options.target}`,
+            'Run `wpmoo reset` to refresh it, or choose another --target.',
+        ].join('\n'));
+    }
+    throw new Error(renderForeignEnvironmentTargetWarning(state));
+}
+async function finishCreateFlow(result, cwd, interactive) {
+    if (result.kind === 'cancelled') {
+        outroPrompt('Create flow cancelled.');
+        return;
+    }
+    if (result.kind === 'updated') {
+        outroPrompt(`Updated existing Odoo dev overlay in ${result.target}.`);
+        return;
+    }
+    if (result.kind === 'deleted') {
+        outroPrompt(`Deleted Odoo dev overlay in ${result.target}.`);
+        return;
+    }
+    const { options } = result;
+    await ensureGitHubRepositories(options, interactive);
+    const scaffoldResult = await scaffold(options);
+    if (options.dryRun) {
+        console.log('Dry run: planned files');
+        for (const file of scaffoldResult.plannedFiles)
+            console.log(`- ${file}`);
+        console.log('Dry run: planned commands');
+        for (const command of scaffoldResult.plannedCommands)
+            console.log(`- ${command}`);
+        return;
+    }
+    notePrompt(renderPostCreateGuidance(options.target, cwd), 'Next steps');
+    outroPrompt(`Created Odoo dev overlay in ${options.target}. Review staged changes, then commit.`);
+}
 async function runCockpitCommand(command, cwd) {
     if (command.id === 'exit') {
         return 'exit';
@@ -856,11 +1008,7 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
         const detection = await detectDevelopmentEnvironment(cwd);
         if (!detection.isEnvironment) {
             await showStartup(argv, skipUpdateCheck);
-            const resolvedOptions = await optionsFromPrompts();
-            await ensureGitHubRepositories(resolvedOptions, true);
-            await scaffold(resolvedOptions);
-            notePrompt(renderPostCreateGuidance(resolvedOptions.target, cwd), 'Next steps');
-            outroPrompt(`Created Odoo dev overlay in ${resolvedOptions.target}. Review staged changes, then commit.`);
+            await finishCreateFlow(await optionsFromPrompts(), cwd, true);
             return;
         }
         let lastStatus = 'Last: Ready';
@@ -1003,20 +1151,12 @@ export async function runCli(cliArgv = process.argv.slice(2), cwd = process.cwd(
     else {
         await showStartup(argv, skipUpdateCheck);
     }
-    const resolvedOptions = options ?? (await optionsFromPrompts());
-    await ensureGitHubRepositories(resolvedOptions, options === undefined);
-    const result = await scaffold(resolvedOptions);
-    if (resolvedOptions.dryRun) {
-        console.log('Dry run: planned files');
-        for (const file of result.plannedFiles)
-            console.log(`- ${file}`);
-        console.log('Dry run: planned commands');
-        for (const command of result.plannedCommands)
-            console.log(`- ${command}`);
+    if (options) {
+        await ensureNonInteractiveCreateTarget(options);
+        await finishCreateFlow({ kind: 'create', options }, cwd, false);
         return;
     }
-    notePrompt(renderPostCreateGuidance(resolvedOptions.target, cwd), 'Next steps');
-    outroPrompt(`Created Odoo dev overlay in ${resolvedOptions.target}. Review staged changes, then commit.`);
+    await finishCreateFlow(await optionsFromPrompts(), cwd, true);
 }
 export function isCliEntrypoint(metaUrl, argvPath = process.argv[1]) {
     if (!argvPath)

package/dist/environment-target-preflight.js

@@ -0,0 +1,48 @@
+import { access } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { markerPath, readEnvironmentMetadata } from './environment.js';
+function pad2(value) {
+    return value.toString().padStart(2, '0');
+}
+function formatBackupTimestamp(date) {
+    return [
+        `${date.getUTCFullYear()}${pad2(date.getUTCMonth() + 1)}${pad2(date.getUTCDate())}`,
+        `${pad2(date.getUTCHours())}${pad2(date.getUTCMinutes())}${pad2(date.getUTCSeconds())}`,
+    ].join('-');
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function inspectEnvironmentTarget(target) {
+    if (!(await pathExists(target))) {
+        return { kind: 'missing_target', target };
+    }
+    const metadata = await readEnvironmentMetadata(target);
+    if (metadata) {
+        return { kind: 'existing_environment', target, metadata };
+    }
+    return { kind: 'foreign_target', target };
+}
+export function renderExistingEnvironmentSummary(state) {
+    return [
+        `Existing WPMoo environment detected at ${state.target}`,
+        `- Product: ${state.metadata.product}`,
+        `- Odoo version: ${state.metadata.odooVersion}`,
+        `- Source repos: ${state.metadata.sourceRepos.length}`,
+    ].join('\n');
+}
+export function renderForeignEnvironmentTargetWarning(state) {
+    return `Target already exists: ${state.target}\nIt does not contain a WPMoo environment marker at ${markerPath}.`;
+}
+export function expectedTargetConfirmation(target, input) {
+    return basename(target) === input;
+}
+export function backupTargetPath(target, date = new Date()) {
+    return `${target}.backup-${formatBackupTimestamp(date)}`;
+}

package/dist/github-prerequisites.js

@@ -0,0 +1,22 @@
+import { isGitHubAuthenticated, isGitHubCliAvailable, realGitHub } from './github.js';
+export async function getGitHubPrerequisiteStatus(runner = realGitHub) {
+    if (!(await isGitHubCliAvailable(runner))) {
+        return { status: 'missing', reason: 'gh-missing' };
+    }
+    if (!(await isGitHubAuthenticated(runner))) {
+        return { status: 'unauthenticated', reason: 'gh-unauthenticated' };
+    }
+    return { status: 'ready' };
+}
+export function renderGitHubPrerequisiteGuidance(status) {
+    if (status.status === 'ready') {
+        return '';
+    }
+    return [
+        'GitHub CLI (`gh`) is not available or not authenticated.',
+        'Install and authenticate it to auto-create missing GitHub repositories:',
+        '',
+        'brew install gh',
+        'gh auth login',
+    ].join('\n');
+}

package/dist/repository-preflight.js

@@ -16,19 +16,53 @@ export function repositoryRequirements(options) {
 export async function findInaccessibleGitHubRepositories(options, runner = realGitHub) {
     return (await checkGitHubRepositories(options, runner)).inaccessible;
 }
+export async function getGitHubRepositorySize(runner, slug) {
+    const result = await runner.run(['api', `repos/${slug}`, '--jq', '.size']);
+    const rawSize = result.stdout.trim();
+    if (!rawSize) {
+        throw new Error(`Unable to parse repository size for ${slug}`);
+    }
+    const size = Number(rawSize);
+    if (!Number.isFinite(size)) {
+        throw new Error(`Unable to parse repository size for ${slug}`);
+    }
+    return size;
+}
+export async function inspectGitHubRepository(runner, repository) {
+    try {
+        const size = await getGitHubRepositorySize(runner, repository.slug);
+        return { status: size === 0 ? 'empty' : 'non-empty', repository };
+    }
+    catch {
+        return { status: 'unknown', repository };
+    }
+}
 export async function checkGitHubRepositories(options, runner = realGitHub) {
     const accessible = [];
     const inaccessible = [];
+    const blocked = [];
     for (const requirement of repositoryRequirements(options)) {
         const status = await getGitHubRepositoryStatus(runner, requirement.url);
         if (status.status === 'accessible') {
-            accessible.push({ ...requirement, slug: status.slug });
+            const repository = { ...requirement, slug: status.slug };
+            if (requirement.url === options.devRepoUrl) {
+                const inspection = await inspectGitHubRepository(runner, repository);
+                if (inspection.status === 'empty') {
+                    accessible.push(repository);
+                }
+                else {
+                    blocked.push(repository);
+                }
+            }
+            else {
+                accessible.push(repository);
+            }
         }
         if (status.status === 'inaccessible') {
             inaccessible.push({ ...requirement, slug: status.slug });
         }
     }
-    return { accessible, inaccessible };
+    return { accessible, inaccessible, blocked };
 }
 export async function createGitHubRepositories(repositories, visibility, runner = realGitHub) {
     for (const repository of repositories) {

package/package.json

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