sitevision-cli 1.0.0-beta.9 → 1.0.1

package/dist/utils/tasks.js

@@ -0,0 +1,510 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { EventEmitter } from 'node:events';
+import { stripVTControlCharacters } from 'node:util';
+import { useSyncExternalStore } from 'react';
+import { WebpackRunner, hasLocalWebpackConfig } from './webpack-runner.js';
+import { hasSitevisionScripts, runSitevisionScriptsBuild, getDelegatedZipPath, checkSitevisionScriptsCompatibility, } from './sitevision-scripts-runner.js';
+import { copyStaticToBuild, copySrcToBuild, cleanBuild, createBuildZip, formatFileSize, getZipSize, zipExists, } from './zip.js';
+import { deleteSessionCookie } from './keychain.js';
+import { isBundledApp, getAppType, getFullAppId, getZipPath, getSignedZipPath, getDeployZipPath, localizedText, } from './project-detection.js';
+import { signApp, deployApp, deployProduction, activateApp, createAddon, listAddons, classifyAddon, } from './sitevision-api.js';
+import { ProcessRunner } from './process-runner.js';
+import { debug } from './debug.js';
+const MAX_LINES = 2000;
+const emitter = new EventEmitter();
+let tasks = [];
+let nextId = 1;
+function notify() {
+    tasks = [...tasks];
+    emitter.emit('change');
+}
+export function getTasks() {
+    return tasks;
+}
+export function useTasks() {
+    return useSyncExternalStore(callback => {
+        emitter.on('change', callback);
+        return () => emitter.off('change', callback);
+    }, () => tasks);
+}
+export function runningTasks(appRoot) {
+    return tasks.filter(t => t.status === 'running' && (!appRoot || t.appRoot === appRoot));
+}
+/** A scaffold belongs to no listed app yet, so it counts for every one. */
+export function scaffoldRunning() {
+    return runningTasks().some(t => t.kind === 'create');
+}
+/** What "stop" means for the selected app: its own tasks and any scaffold. */
+export function stoppableTasks(appRoot) {
+    return runningTasks().filter(t => t.kind === 'create' || t.appRoot === appRoot);
+}
+export function clearFinished() {
+    tasks = tasks.filter(t => t.status === 'running');
+    notify();
+}
+export function createTask(kind, project, label, stop = () => { }) {
+    const task = {
+        id: nextId++,
+        kind,
+        appRoot: project.root,
+        appName: localizedText(project.manifest.name) || project.manifest.id,
+        label,
+        status: 'running',
+        phase: 'starting',
+        startedAt: Date.now(),
+        lines: [],
+        stop,
+    };
+    tasks.push(task);
+    debug('task', `#${task.id} ${kind} ${label} (${task.appName})`);
+    notify();
+    const log = (tag, text, level = 'info') => {
+        for (const line of logLines(text)) {
+            task.lines.push({ time: Date.now(), tag, level, text: line });
+            debug('task', `#${task.id} ${tag} ${level === 'info' ? '' : level + ' '}${line}`);
+        }
+        if (task.lines.length > MAX_LINES) {
+            task.lines.splice(0, task.lines.length - MAX_LINES);
+        }
+        notify();
+    };
+    const finish = (status, error) => {
+        if (task.status !== 'running')
+            return;
+        task.status = status;
+        task.error = error;
+        task.endedAt = Date.now();
+        task.phase = status;
+        debug('task', `#${task.id} ${status} after ${task.endedAt - task.startedAt}ms`);
+        if (error)
+            log('svc', error, 'error');
+        notify();
+    };
+    return { task, log, finish };
+}
+export function setPhase(task, phase) {
+    task.phase = phase;
+    debug('task', `#${task.id} phase ${phase}`);
+    notify();
+}
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+// ---------------------------------------------------------------------------
+// One-shot steps shared by the tasks below.
+// ---------------------------------------------------------------------------
+/** Build the app to dist/<appId>.zip. Returns the zip path or throws. */
+async function buildOnce(project, task, log, mode, signal, 
+// False (`svc build --no-zip`): leave build/ and no zip.
+zip = true) {
+    const { root, manifest } = project;
+    cleanBuild(root);
+    if (isBundledApp(manifest) && !hasLocalWebpackConfig(root)) {
+        if (!hasSitevisionScripts(root)) {
+            throw new Error('No webpack.config.js found and @sitevision/sitevision-scripts is not installed. Run npm install.');
+        }
+        const { warning } = checkSitevisionScriptsCompatibility(root);
+        if (warning)
+            log('bld', warning, 'warn');
+        setPhase(task, 'building');
+        log('bld', 'building via sitevision-scripts');
+        const result = await runSitevisionScriptsBuild(root, chunk => log('bld', chunk), signal);
+        if (!result.success)
+            throw new Error(result.error ?? 'Build failed');
+        const zipPath = getDelegatedZipPath(root, manifest.id);
+        if (!zipExists(zipPath)) {
+            throw new Error(`Build reported success but no zip was found at ${zipPath}.`);
+        }
+        // sitevision-scripts always zips; without a zip means taking it away.
+        if (!zip)
+            fs.rmSync(zipPath);
+        return zip ? zipPath : undefined;
+    }
+    if (isBundledApp(manifest)) {
+        if (!WebpackRunner.isWebpackAvailable(root)) {
+            throw new Error('webpack not found. Run npm install.');
+        }
+        setPhase(task, 'building');
+        log('bld', 'compiling with webpack');
+        const runner = new WebpackRunner(root, {
+            mode,
+            cssPrefix: manifest.id,
+            restApp: getAppType(manifest) !== 'web' && getAppType(manifest) !== 'widget',
+        });
+        const result = await runner.run();
+        await runner.close();
+        reportBuild(result, log);
+        if (!result.success)
+            throw new Error(result.errors?.join('\n') || 'Build failed');
+        copyStaticToBuild(root);
+    }
+    else {
+        setPhase(task, 'copying');
+        log('bld', 'copying source files');
+        copySrcToBuild(root);
+        copyStaticToBuild(root);
+    }
+    if (!zip)
+        return undefined;
+    setPhase(task, 'zipping');
+    return createBuildZip(root, getFullAppId(manifest.id));
+}
+function reportBuild(result, log) {
+    for (const warning of result.warnings ?? [])
+        log('bld', warning, 'warn');
+    for (const error of result.errors ?? [])
+        log('bld', error, 'error');
+    if (result.success) {
+        log('bld', `compiled in ${result.stats?.time ?? 0}ms${result.stats?.assets?.length ? ` · ${result.stats.assets.join(', ')}` : ''}`, 'ok');
+    }
+}
+async function signOnce(project, task, log, zipPath, credentials) {
+    setPhase(task, 'signing');
+    log('sgn', `signing via developer.sitevision.se${credentials.certificateName ? ` · cert ${credentials.certificateName}` : ''}`);
+    const signedPath = getSignedZipPath(project.root, project.manifest);
+    const result = await signApp(zipPath, credentials, signedPath);
+    if (!result.success)
+        throw new Error(result.error ?? 'Signing failed');
+    log('sgn', `signed ${path.basename(signedPath)}`, 'ok');
+    return signedPath;
+}
+async function deployOnce(project, task, log, zipPath, config, options) {
+    setPhase(task, 'deploying');
+    const appType = getAppType(project.manifest);
+    log('dep', `POST multipart → ${options.production ? 'production' : 'dev'} import · ${config.addonName} · ${path.basename(zipPath)}`);
+    const upload = async () => options.production
+        ? deployProduction(zipPath, { ...config, activate: options.activate }, appType)
+        : deployApp(zipPath, config, appType, options.force);
+    let result = await upload();
+    if (!result.success && result.contextNodeMissing) {
+        const addon = classifyAddon(await listAddons(config), config.addonName);
+        if (addon === 'unknown') {
+            throw new Error(`${result.error}\nCould not list the site's addons either, so the session may have expired. Press l to log in again.`);
+        }
+        if (addon === 'missing' && options.onAddonMissing) {
+            log('dep', `addon ${config.addonName} does not exist`, 'warn');
+            if (await options.onAddonMissing(config.addonName)) {
+                const created = await createAddon(config, appType);
+                if (!created.success) {
+                    throw new Error(created.error ?? 'Create addon failed');
+                }
+                log('dep', `created addon ${config.addonName}`, 'ok');
+                result = await upload();
+            }
+        }
+    }
+    // A stale session must not be replayed by the next run. Not when it came
+    // from SITEVISION_SESSION_COOKIE: that one would just be read again.
+    if (!result.success &&
+        result.authExpired &&
+        config.sessionCookie &&
+        !process.env['SITEVISION_SESSION_COOKIE']) {
+        deleteSessionCookie(config.domain, config.username);
+    }
+    if (!result.success)
+        throw new Error(result.error ?? 'Deployment failed');
+    if (options.production && options.activate && !result.activated) {
+        throw new Error(result.message ?? 'Deployed, but not activated');
+    }
+    log('dep', `${result.message ?? 'deployed'}${result.executableId ? ` · exec ${result.executableId}` : ''}`, 'ok');
+    return result.executableId;
+}
+// ---------------------------------------------------------------------------
+// Tasks
+// ---------------------------------------------------------------------------
+export function startBuild(project, { zip = true } = {}) {
+    const controller = new AbortController();
+    const { task, log, finish } = createTask('build', project, 'build', () => {
+        controller.abort();
+        finish('stopped');
+    });
+    void (async () => {
+        try {
+            const built = await buildOnce(project, task, log, 'production', controller.signal, zip);
+            log('bld', built
+                ? `created ${built} · ${formatFileSize(getZipSize(built))}`
+                : 'built, zip skipped', 'ok');
+            finish('success');
+        }
+        catch (error) {
+            finish('error', errorText(error));
+        }
+    })();
+    return task;
+}
+export function startSign(project, credentials) {
+    const { task, log, finish } = createTask('sign', project, 'sign');
+    void (async () => {
+        try {
+            const zipPath = getZipPath(project.root, project.manifest);
+            if (!zipExists(zipPath)) {
+                throw new Error(`Zip file not found: ${zipPath}. Run build first.`);
+            }
+            await signOnce(project, task, log, zipPath, credentials);
+            finish('success');
+        }
+        catch (error) {
+            finish('error', errorText(error));
+        }
+    })();
+    return task;
+}
+export function startDeploy(project, config, options) {
+    const { task, log, finish } = createTask('deploy', project, options.production ? 'deploy production' : 'deploy');
+    void (async () => {
+        try {
+            const zipPath = options.production
+                ? getSignedZipPath(project.root, project.manifest)
+                : getDeployZipPath(project.root, project.manifest);
+            if (!zipExists(zipPath)) {
+                throw new Error(`${options.production ? 'Signed zip' : 'Zip'} not found: ${zipPath}. Run ${options.production ? 'sign' : 'build'} first.`);
+            }
+            await deployOnce(project, task, log, zipPath, config, options);
+            finish('success');
+        }
+        catch (error) {
+            finish('error', errorText(error));
+        }
+    })();
+    return task;
+}
+export function startActivate(project, config, executableId, versionLabel) {
+    const { task, log, finish } = createTask('activate', project, `activate ${versionLabel}`);
+    void (async () => {
+        try {
+            setPhase(task, 'activating');
+            log('act', `PUT activateCustomModuleExecutable · ${versionLabel}`);
+            const result = await activateApp(executableId, config, getAppType(project.manifest));
+            if (!result.success)
+                throw new Error(result.error ?? 'Activation failed');
+            log('act', `${versionLabel} is now active`, 'ok');
+            finish('success');
+        }
+        catch (error) {
+            finish('error', errorText(error));
+        }
+    })();
+    return task;
+}
+export function startInstall(project) {
+    const runner = new ProcessRunner('npm', ['install'], project.root);
+    const { task, log, finish } = createTask('install', project, 'npm install', () => {
+        runner.kill();
+        finish('stopped');
+    });
+    setPhase(task, 'installing');
+    runner.on('output', (output) => log('npm', output.data, output.type === 'stderr' ? 'warn' : 'info'));
+    runner
+        .run()
+        .then(result => finish(result.exitCode === 0 ? 'success' : 'error', result.exitCode === 0
+        ? undefined
+        : `npm install exited with ${result.exitCode}`))
+        .catch(error => finish('error', errorText(error)));
+    return task;
+}
+const WEBPACK_UNSEEN_TARGETS = ['static', 'manifest.json'];
+const WATCH_TARGETS = [
+    'src',
+    'static',
+    'i18n',
+    'resource',
+    'config',
+    'manifest.json',
+];
+/**
+ * Dev / watch loop: build on every source change, then optionally sign and
+ * deploy. Runs until `task.stop()`; the task stays in the registry meanwhile.
+ */
+export function startDev(project, options) {
+    const { root, manifest } = project;
+    const watchers = [];
+    let webpack = null;
+    let debounce;
+    const controller = new AbortController();
+    const stop = () => {
+        controller.abort();
+        clearTimeout(debounce);
+        for (const watcher of watchers)
+            watcher.close();
+        void webpack?.close().catch(() => { });
+        finish('stopped');
+    };
+    const { task, log, finish } = createTask(options.deploy ? 'dev' : 'watch', project, options.deploy ? 'dev' : 'watch', stop);
+    const afterBuild = async (zipPath) => {
+        // Stopped mid-build: never sign or deploy what is left.
+        if (controller.signal.aborted)
+            return;
+        let deployZip = zipPath;
+        if (options.signingCredentials) {
+            deployZip = await signOnce(project, task, log, zipPath, options.signingCredentials);
+        }
+        if (options.deploy && options.deployConfig) {
+            await deployOnce(project, task, log, deployZip, options.deployConfig, {
+                force: true,
+                onAddonMissing: options.onAddonMissing,
+            });
+        }
+        setPhase(task, 'watching');
+        log('svc', 'watching for changes');
+    };
+    const fail = (error) => {
+        if (controller.signal.aborted)
+            return;
+        log('svc', errorText(error), 'error');
+        setPhase(task, 'error');
+    };
+    const rebuild = serialized(async () => {
+        if (controller.signal.aborted)
+            return;
+        try {
+            const zip = await buildOnce(project, task, log, 'development', controller.signal);
+            if (zip)
+                await afterBuild(zip);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    // Size + mtime of every watched file. An event that leaves this unchanged
+    // (editor metadata, xattrs, identical re-save) is noise and must not
+    // rebuild, or a stray event during sign/deploy loops forever.
+    const snapshot = (targets) => {
+        const entries = [];
+        for (const name of targets) {
+            const target = path.join(root, name);
+            const stat = fs.statSync(target, { throwIfNoEntry: false });
+            if (!stat)
+                continue;
+            const files = (stat.isDirectory()
+                ? fs
+                    .readdirSync(target, { recursive: true, withFileTypes: true })
+                    .filter(entry => entry.isFile())
+                    .map(entry => path.join(entry.parentPath, entry.name))
+                : [target]).filter(file => !path.basename(file).startsWith('.'));
+            for (const file of files) {
+                const info = fs.statSync(file, { throwIfNoEntry: false });
+                if (info)
+                    entries.push(`${file}:${info.size}:${info.mtimeMs}`);
+            }
+        }
+        return entries.toSorted().join('\n');
+    };
+    let fingerprint = '';
+    const watchFiles = (targets, changed) => {
+        const onChange = (name, event, file) => {
+            const where = file ? path.join(name, file) : name;
+            clearTimeout(debounce);
+            debounce = setTimeout(() => {
+                const next = snapshot(targets);
+                if (next === fingerprint) {
+                    log('fs', `${event} ${where} · no file changed, ignored`, 'warn');
+                    return;
+                }
+                fingerprint = next;
+                log('fs', `${event} ${where}`);
+                changed();
+            }, 300);
+        };
+        for (const name of targets) {
+            const target = path.join(root, name);
+            if (!fs.existsSync(target))
+                continue;
+            const isDir = fs.statSync(target).isDirectory();
+            watchers.push(fs.watch(target, { recursive: isDir }, (event, file) => {
+                onChange(name, event, file);
+            }));
+        }
+        fingerprint = snapshot(targets);
+        log('svc', `watching ${targets.join(', ')}`);
+    };
+    void (async () => {
+        try {
+            cleanBuild(root);
+            if (isBundledApp(manifest) && hasLocalWebpackConfig(root)) {
+                // Project ships its own webpack config: incremental in-process watch.
+                if (!WebpackRunner.isWebpackAvailable(root)) {
+                    throw new Error('webpack not found. Run npm install.');
+                }
+                setPhase(task, 'building');
+                webpack = new WebpackRunner(root, {
+                    mode: 'development',
+                    watch: true,
+                    cssPrefix: manifest.id,
+                    restApp: getAppType(manifest) !== 'web' && getAppType(manifest) !== 'widget',
+                });
+                // Zip, sign and deploy what is in build/ now. Webpack compiles and
+                // static edits both end here, one at a time, the latest one last.
+                let compiled = false;
+                const repackage = serialized(async () => {
+                    if (!compiled || controller.signal.aborted)
+                        return;
+                    try {
+                        copyStaticToBuild(root);
+                        await afterBuild(await createBuildZip(root, getFullAppId(manifest.id)));
+                    }
+                    catch (error) {
+                        fail(error);
+                    }
+                });
+                await webpack.watch(result => {
+                    reportBuild(result, log);
+                    compiled = result.success;
+                    if (result.success)
+                        void repackage();
+                    else
+                        setPhase(task, 'error');
+                });
+                // Webpack watches what it bundles; what is copied in as-is it never sees.
+                watchFiles(WEBPACK_UNSEEN_TARGETS, () => {
+                    void repackage();
+                });
+            }
+            else {
+                watchFiles(WATCH_TARGETS, () => {
+                    void rebuild();
+                });
+                await rebuild();
+            }
+        }
+        catch (error) {
+            finish('error', errorText(error));
+        }
+    })();
+    return task;
+}
+/**
+ * Run `run` one call at a time. Calls made meanwhile collapse into one run with
+ * the latest value, so of several quick saves the last is what gets deployed
+ * last, never an older one that happened to upload slower.
+ */
+export function serialized(run) {
+    let running = false;
+    let waiting;
+    return async (value) => {
+        waiting = { value };
+        if (running)
+            return;
+        running = true;
+        try {
+            while (waiting) {
+                const { value: current } = waiting;
+                waiting = undefined;
+                // eslint-disable-next-line no-await-in-loop
+                await run(current);
+            }
+        }
+        finally {
+            running = false;
+        }
+    };
+}
+/**
+ * Child output as log rows: split on LF or CRLF, no colour or cursor codes, and
+ * of a line redrawn with bare CRs (progress bars) only the final state. Any of
+ * those left in would move the cursor inside Ink's frame.
+ */
+export function logLines(text) {
+    return stripVTControlCharacters(text)
+        .trimEnd()
+        .split(/\r?\n/)
+        .map(line => line.slice(line.lastIndexOf('\r') + 1));
+}

package/dist/utils/version-check.js

@@ -1,9 +1,9 @@
 import https from 'node:https';
 /**
  * True if version `a` is strictly greater than `b`, comparing the numeric
- * MAJOR.MINOR.PATCH core. Pre-release suffixes (e.g. `-beta.1`) are ignored.
+ * MAJOR.MINOR.PATCH core. With equal cores, a stable `a` beats a pre-release `b`.
  */
-function isNewer(a, b) {
+export function isNewer(a, b) {
     const core = (v) => (v.split('-')[0] ?? '').split('.');
     const pa = core(a);
     const pb = core(b);
@@ -15,7 +15,7 @@ function isNewer(a, b) {
         if (da < db)
             return false;
     }
-    return false;
+    return !a.includes('-') && b.includes('-');
 }
 /**
  * Check the npm registry for a newer published version of `packageName`.

package/dist/utils/webpack-runner.js

@@ -7,7 +7,10 @@
 import path from 'path';
 import fs from 'fs';
 import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
 import { copyChunksToResources } from './zip.js';
+import { findInstalledPackage } from './sitevision-scripts-runner.js';
+import { debug, errorText } from './debug.js';
 // =============================================================================
 // LOCAL CONFIG DETECTION
 // =============================================================================
@@ -56,8 +59,7 @@ export class WebpackRunner {
             return;
         }
         // Load webpack from project's node_modules
-        const webpackPath = path.join(this.projectRoot, 'node_modules', 'webpack');
-        if (!fs.existsSync(webpackPath)) {
+        if (!WebpackRunner.isWebpackAvailable(this.projectRoot)) {
             throw new Error('webpack not found in project. Make sure webpack is installed: npm install webpack');
         }
         try {
@@ -83,7 +85,8 @@ export class WebpackRunner {
             throw new Error('webpack.config.js not found. Make sure your project has a webpack configuration.');
         }
         try {
-            const configModule = await import(configPath);
+            // A bare Windows path (C:\\...) is not a valid import specifier.
+            const configModule = await import(pathToFileURL(configPath).href);
             const configFactory = configModule.default || configModule;
             // If it's a function, call it with options
             if (typeof configFactory === 'function') {
@@ -149,6 +152,7 @@ export class WebpackRunner {
                     }
                     catch (chunkError) {
                         // Non-fatal, just log
+                        debug('bld', `Failed to copy chunks: ${errorText(chunkError)}`);
                         console.warn('Warning: Failed to copy chunks:', chunkError);
                     }
                 }
@@ -189,6 +193,7 @@ export class WebpackRunner {
                         copyChunksToResources(this.config.output.path);
                     }
                     catch (chunkError) {
+                        debug('bld', `Failed to copy chunks: ${errorText(chunkError)}`);
                         console.warn('Warning: Failed to copy chunks:', chunkError);
                     }
                 }
@@ -225,8 +230,7 @@ export class WebpackRunner {
      * Check if webpack is available in the project
      */
     static isWebpackAvailable(projectRoot) {
-        const webpackPath = path.join(projectRoot, 'node_modules', 'webpack');
-        return fs.existsSync(webpackPath);
+        return findInstalledPackage(projectRoot, 'webpack') !== null;
     }
     /**
      * Get the webpack version from the project

package/dist/utils/workspace.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectProject, readWorkspaceDevProperties, } from './project-detection.js';
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+const MAX_DEPTH = 3;
+/**
+ * Find every Sitevision app below `root` (e.g. root/webapps/x, root/restapps/y).
+ * Depth-limited walk that skips dependency and output folders.
+ */
+export function discoverApps(root, 
+// Filled with why each app that was left out is broken.
+skipped = []) {
+    const found = [];
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || SKIP_DIRS.has(entry.name))
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            let project = null;
+            try {
+                project = detectProject(full);
+            }
+            catch (error) {
+                // A broken app is left out, said out loud, and not searched for more.
+                skipped.push(error instanceof Error ? error.message : String(error));
+                continue;
+            }
+            if (project) {
+                found.push(project);
+            }
+            else if (depth < MAX_DEPTH) {
+                walk(full, depth + 1);
+            }
+        }
+    };
+    walk(root, 1);
+    // Group first, then path: a deeper folder (webapps/nested) must not split
+    // its parent's run of apps, or the same group heading renders twice.
+    return found.toSorted((a, b) => path.dirname(a.root).localeCompare(path.dirname(b.root)) ||
+        a.root.localeCompare(b.root));
+}
+/** Group label for an app: its parent folder relative to the workspace root. */
+export function appGroup(root, appRoot) {
+    const relative = path.relative(root, path.dirname(appRoot));
+    return relative === '' ? '.' : relative;
+}
+/** Missing something nothing can deploy without. */
+export function configIncomplete(dev) {
+    if (!dev?.domain || !dev.siteName)
+        return true;
+    return (dev.authMethod ?? 'basic') === 'basic' && !dev.username;
+}
+/**
+ * What a deploy is sent with, or which required value is missing. The one place
+ * dev properties become a DeployConfig, so nothing ever posts to "undefined".
+ */
+export function toDeployConfig(dev, 
+// False for what talks to the site rather than an addon: listing its addons
+// (how an empty addon name gets picked) and logging in.
+{ addon = true } = {}) {
+    const required = {
+        domain: dev?.domain,
+        siteName: dev?.siteName,
+        ...(addon && { addonName: dev?.addonName }),
+        // A token or cookie login has no use for a username.
+        ...((dev?.authMethod ?? 'basic') === 'basic' && { username: dev?.username }),
+    };
+    const missing = Object.entries(required).find(([, value]) => !value)?.[0];
+    if (!dev || missing) {
+        return {
+            error: `Deploy config is missing "${missing ?? 'domain'}". Run svc and press e to set it, or add it to .dev_properties.json.`,
+        };
+    }
+    return {
+        config: {
+            domain: dev.domain,
+            siteName: dev.siteName,
+            addonName: dev.addonName ?? '',
+            username: dev.username ?? '',
+            password: dev.password,
+            accessToken: dev.accessToken,
+            sessionCookie: dev.sessionCookie,
+            useHTTP: dev.useHTTPForDevDeploy,
+        },
+    };
+}
+/**
+ * True when a workspace has apps but nothing usable to deploy with: neither the
+ * shared root config nor the apps themselves carry domain/site/username. The
+ * shell then opens on Workspace settings instead of the first app.
+ */
+export function needsOnboarding(root, apps) {
+    return (apps.length > 0 &&
+        configIncomplete(readWorkspaceDevProperties(root)) &&
+        apps.some(app => configIncomplete(app.devProperties)));
+}