@sparkelf/dsh-plus 0.2.4-alpha.47 → 0.2.5-alpha.49

package/lib/types/cli.js

@@ -0,0 +1,913 @@
+/**
+ * The `dsh-plus` command line for a standalone installation.
+ *
+ * The commands exist because the launcher underneath is a developer surface: it
+ * refuses an existing profile, reports a taken port as a module-resolution stack
+ * trace, and exits with the terminal. This dispatcher supplies the missing product
+ * layer — a profile created on first start, a free port chosen without asking, a
+ * server that survives the terminal, and one place to read the URL.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newerVersion } from "./registry-versions.js";
+import { assertRedirectsPublished, projectEdition, readDistributionFacts, writeProfileProjection, } from "./manifest.js";
+import { CAPABILITIES, CAPABILITY_ENV_FILE, CAPABILITY_MARKER, CAPABILITY_RECORD, DEFAULT_MINERU_ENDPOINT, capabilityEnvironment, capabilityPatchLayer, detectEnabledCapabilities, editCapabilityPatchLayer, installCapabilityServices, interviewCapabilities, readCapabilityRecord, } from "./capabilities.js";
+import { DEFAULT_PORT, STOP_GRACE_MILLISECONDS, choosePort, clearState, isRunning, portAvailable, readState, spawnServer, stateDirectory, waitForAuthenticatedUrl, waitForServer, writeState, } from "./server.js";
+import { DEFAULT_PROFILE, applyProfileNpmPatches, ensureProfile, pnpmAvailable, pnpmInstallCommand, pnpmInstallCommands, registryOrder, readDistributionProfile, resolveDistributionDirectory, resolveInvocationAnchor, resolvePaths, } from "./profile.js";
+/** Edition the offline build projects when the caller names none. */
+const DEFAULT_EDITION = 'intranet-team';
+/** Milliseconds a start waits for the server to answer before reporting failure. */
+const READY_TIMEOUT_MILLISECONDS = 90_000;
+/** Profile patch file the capability interview rewrites (the profile's user layer). */
+const CAPABILITY_PATCH_FILE = 'cordis.patch.yml';
+function parseStartOptions(argv) {
+    let port = DEFAULT_PORT;
+    let host = '127.0.0.1';
+    let open = true;
+    let foreground = false;
+    let capabilities;
+    let edition;
+    const exclude = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--port' || token === '-p') {
+            const value = argv[index + 1];
+            if (value === undefined || !/^\d+$/u.test(value))
+                throw new Error('--port requires a number');
+            port = Number(value);
+            index += 1;
+            continue;
+        }
+        if (token === '--host') {
+            const value = argv[index + 1];
+            if (value === undefined)
+                throw new Error('--host requires a value');
+            host = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--no-open') {
+            open = false;
+            continue;
+        }
+        if (token === '--foreground') {
+            foreground = true;
+            continue;
+        }
+        if (token === '--edition') {
+            const value = argv[index + 1];
+            if (value === undefined || value === '')
+                throw new Error('--edition requires a value');
+            edition = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--exclude') {
+            const value = argv[index + 1];
+            if (value === undefined || value === '')
+                throw new Error('--exclude requires a package name');
+            exclude.push(value);
+            index += 1;
+            continue;
+        }
+        if (token === '--capabilities') {
+            const value = argv[index + 1];
+            if (value === undefined)
+                throw new Error('--capabilities requires a comma-separated list, or an empty string for none');
+            const stated = value === '' ? [] : value.split(',').map(entry => entry.trim()).filter(entry => entry !== '');
+            // A stated selection is the only way an unattended install chooses capabilities, so
+            // a name this release does not offer fails here: the deployment would otherwise
+            // start without a capability its caller believes it selected. Validating at parse
+            // time also makes the failure independent of what is installed.
+            const offered = new Set(CAPABILITIES.map(capability => capability.id));
+            for (const id of stated) {
+                if (!offered.has(id)) {
+                    throw new Error('unknown capability "' + id + '"; this release offers ' + [...offered].join(', '));
+                }
+            }
+            capabilities = stated;
+            index += 1;
+            continue;
+        }
+        throw new Error('unknown option: ' + String(token));
+    }
+    return { port, host, open, foreground, capabilities, edition, exclude };
+}
+/**
+ * Resolve a stated capability selection.
+ *
+ * An unattended install states what it wants instead of answering the interview, so a
+ * name it does not offer has to fail here rather than silently enable nothing: the
+ * deployment would otherwise start with a capability the caller believes it selected.
+ *
+ * @param ids - capability ids the caller selected.
+ * @returns the answers the interview would have returned.
+ */
+function selectCapabilities(ids) {
+    const selected = [...new Set(ids)];
+    // MinerU is started from an endpoint the interview collects; an unattended install
+    // gets the documented default rather than an unset one.
+    return {
+        enabled: selected,
+        ...selected.includes('mineru') ? { mineruEndpoint: DEFAULT_MINERU_ENDPOINT } : {},
+    };
+}
+/**
+ * Where the installation that owns this command keeps its packages.
+ *
+ * A global install places the command in a shared prefix and a local install places
+ * it in a project; neither has anything to do with the directory the user happens to
+ * be in. The search therefore starts at this module own file and climbs to the tree
+ * npm laid out around it.
+ *
+ * The test is the launcher, not the distribution: inside a workspace the package
+ * resolves its own name, so looking for the distribution would stop at the package
+ * rather than at the tree that owns every dependency.
+ *
+ * @returns absolute path to the installation root.
+ */
+function installationRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    let current = here;
+    for (;;) {
+        if (existsSync(join(current, 'node_modules', '@deepseek-ai', 'dsh')))
+            return current;
+        const parent = dirname(current);
+        // A tree npm did not lay out has no such ancestor; the module own directory
+        // keeps the failure message pointing at the installation that was searched.
+        if (parent === current)
+            return here;
+        current = parent;
+    }
+}
+/** The package.json this installation resolves its dependencies from. */
+function installationAnchor() {
+    return join(installationRoot(), 'package.json');
+}
+/**
+ * Path to the installed command's own file, which is where a declaration lookup starts.
+ *
+ * The declaration belongs to the package the user installed, and that package is a
+ * sibling of this module rather than an ancestor: a variant's forwarder imports this
+ * CLI in-process, so `import.meta.url` names `@sparkelf/dsh-plus` while the installed
+ * command is the variant. `process.argv[1]` is the entry that was actually invoked,
+ * which is the package whose declaration applies.
+ *
+ * Walking out from the installation root cannot reach it either: that root is the
+ * project the user ran the command in, so every variant would fall back to the full
+ * profile and keep the capabilities it excluded.
+ *
+ * @returns absolute path to the invoked command, or this module when argv carries none.
+ */
+function declarationAnchor() {
+    // A global install links the command into a bin directory; the link target is what owning
+    // package resolution must start from.
+    return resolveInvocationAnchor(process.argv[1], fileURLToPath(import.meta.url));
+}
+/**
+ * The launcher entry this installation must drive.
+ *
+ * The profile owns the runtime tree, so the launcher is resolved from the profile rather than
+ * from the directory that installed the command: a global distribution has no launcher of its
+ * own, and one resolved from the consumer would be a second copy of the process the profile
+ * mounts.
+ *
+ * @param profileDirectory - profile whose node_modules carries the launcher.
+ * @returns absolute path to the launcher entry.
+ */
+function launcherEntry(profileDirectory) {
+    return createRequire(join(profileDirectory, 'package.json')).resolve('@deepseek-ai/dsh/lib/bin.js');
+}
+/** Run the server in this process, inheriting stdio. */
+function runForeground(entry, profileName, port, host, open) {
+    const args = [entry, '--profile', profileName, '--port', String(port), '--host', host];
+    if (!open)
+        args.push('--no-open');
+    const result = spawnSync(process.execPath, args, { stdio: 'inherit' });
+    return result.status ?? 1;
+}
+async function start(argv) {
+    const options = parseStartOptions(argv);
+    // The profile's own name and omissions come from the package that installed this
+    // command, which is a different tree position than the dependencies it resolves.
+    const paths = resolvePaths(declarationAnchor(), process.env, options.edition);
+    // The profile installs its own dependency tree, which needs pnpm. Asking here rather
+    // than failing inside the install turns a missing prerequisite into a decision the
+    // consumer makes, and the install it can run is the one command that provides it.
+    if (!pnpmAvailable()) {
+        const command = pnpmInstallCommand();
+        console.log('pnpm is required to install the ' + DEFAULT_PROFILE + ' profile, and was not found.');
+        console.log('Install it with: ' + command);
+        if (!await confirm('Install pnpm now?')) {
+            console.log('Install pnpm and run dsh-plus start again.');
+            return 1;
+        }
+        // Try each installer in turn: Corepack is absent on an installation that disabled it,
+        // and npm succeeds there. A failure reports the commands rather than a stack trace.
+        let installed = false;
+        const preferred = registryOrder()[0];
+        for (const candidate of pnpmInstallCommands()) {
+            // Corepack reads its registry from the environment; npm takes a flag, which the
+            // command already carries. Setting it for both keeps the download on the mirror.
+            const attempt = spawnSync(candidate, {
+                stdio: 'inherit',
+                shell: true,
+                env: preferred === undefined
+                    ? process.env
+                    : { ...process.env, COREPACK_NPM_REGISTRY: preferred },
+            });
+            if (attempt.status === 0 && pnpmAvailable()) {
+                installed = true;
+                break;
+            }
+        }
+        if (!installed) {
+            console.log('Could not install pnpm automatically.');
+            console.log('Run one of these, then run dsh-plus start again:');
+            for (const candidate of pnpmInstallCommands())
+                console.log('  ' + candidate);
+            return 1;
+        }
+        console.log('pnpm installed.');
+    }
+    const created = ensureProfile(paths, options.edition, options.exclude);
+    console.log(created
+        ? 'Created the ' + paths.profileName + ' profile at ' + paths.profileDirectory
+        : 'Using the existing ' + paths.profileName + ' profile');
+    // The profile symlinks the consumer's packages, so a patch lands on the installed
+    // copy the launcher loads. A reinstall restores the published bytes, which is why
+    // this runs on every start rather than only when the profile was created.
+    for (const label of applyProfileNpmPatches(paths.distributionDirectory, paths.profileDirectory)) {
+        console.log('Applied the reviewed patch ' + label);
+    }
+    // The capability interview runs once, when the profile is created: a deployment
+    // that already answered keeps its answers, and a re-run only reports them. Asking
+    // on every start would make a restart look like a first install.
+    const needsInterview = created || !existsSync(join(paths.home, CAPABILITY_RECORD));
+    const answers = needsInterview
+        ? options.capabilities === undefined
+            ? await interviewCapabilities(true)
+            : selectCapabilities(options.capabilities)
+        : undefined;
+    if (answers !== undefined) {
+        const ready = installCapabilityServices(answers, paths.home);
+        writeCapabilityPatch(paths.profileDirectory, answers);
+        writeCapabilityEnvironment(paths.home, answers);
+        console.log('  Enabled: ' + (answers.enabled.length === 0 ? '(none)' : answers.enabled.join(', ')));
+        if (answers.enabled.length > 0)
+            console.log('  Services ready: ' + (ready.length === 0 ? '(none)' : ready.join(', ')));
+        if (answers.enabled.includes('exa') && answers.exaApiKey === undefined) {
+            console.log('  Exa: add EXA_API_KEY to ' + join(paths.home, CAPABILITY_ENV_FILE) + ' when you have a key.');
+        }
+    }
+    const entry = launcherEntry(paths.profileDirectory);
+    if (options.foreground)
+        return runForeground(entry, paths.profileName, options.port, options.host, options.open);
+    const existing = readState(paths.home);
+    if (existing !== undefined) {
+        console.log('Plus is already running at ' + existing.url);
+        console.log('Stop it with: dsh-plus stop');
+        return 0;
+    }
+    return startDetached(paths, entry, options);
+}
+async function startDetached(paths, entry, options) {
+    const home = paths.home;
+    const port = await choosePort(options.port, options.host);
+    if (port === undefined) {
+        console.error('No free port in the range ' + String(options.port) + '-' + String(options.port + 9) + '.');
+        console.error('Pass --port with a free port.');
+        return 1;
+    }
+    if (port !== options.port)
+        console.log('Port ' + String(options.port) + ' is in use; using ' + String(port) + '.');
+    const logPath = join(stateDirectory(paths.home), 'server.log');
+    const env = { ...process.env, DSH_HOME: paths.home };
+    const args = [entry, '--profile', paths.profileName, '--port', String(port), '--host', options.host, '--no-open'];
+    const pid = spawnServer({ command: process.execPath, args, env, logPath });
+    const url = 'http://' + options.host + ':' + String(port) + '/';
+    const ready = await waitForServer(url, READY_TIMEOUT_MILLISECONDS);
+    if (!ready) {
+        console.error('The server did not answer within ' + String(READY_TIMEOUT_MILLISECONDS / 1000) + 's.');
+        console.error('Read ' + logPath + ' for the startup error.');
+        if (isRunning(pid))
+            process.kill(pid, 'SIGTERM');
+        return 1;
+    }
+    // The launcher prints the URL carrying the process launch token, and the server
+    // refuses every request without the cookie that token mints. Reporting the bare
+    // address sends the user to a 401 that tells them to reopen the launcher's URL,
+    // which lives only in the log this command points at.
+    const opened = await waitForAuthenticatedUrl(logPath, READY_TIMEOUT_MILLISECONDS) ?? url;
+    writeState(home, { pid, port, url: opened });
+    console.log('Plus is running at ' + opened);
+    console.log('Logs: ' + logPath);
+    console.log('Stop it with: dsh-plus stop');
+    return 0;
+}
+async function stop() {
+    const anchor = installationAnchor();
+    const { home } = resolvePaths(anchor);
+    const state = readState(home);
+    if (state === undefined) {
+        clearState(home);
+        console.log('Plus is not running.');
+        return 0;
+    }
+    process.kill(state.pid, 'SIGTERM');
+    const deadline = Date.now() + STOP_GRACE_MILLISECONDS;
+    while (Date.now() < deadline && isRunning(state.pid)) {
+        await new Promise((resolveDelay) => { setTimeout(resolveDelay, 200); });
+    }
+    if (isRunning(state.pid)) {
+        console.log('The server did not exit in ' + String(STOP_GRACE_MILLISECONDS / 1000) + 's; forcing it.');
+        process.kill(state.pid, 'SIGKILL');
+    }
+    clearState(home);
+    console.log('Plus has stopped.');
+    return 0;
+}
+function status() {
+    const anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    const state = readState(paths.home);
+    if (state === undefined) {
+        console.log('Plus is not running.');
+        console.log('Start it with: dsh-plus start');
+        return 0;
+    }
+    console.log('Plus is running at ' + state.url);
+    console.log('Process ' + String(state.pid) + ' on port ' + String(state.port));
+    return 0;
+}
+/**
+ * Move the installation to a newer published release.
+ *
+ * The profile pins the distribution exactly, so the new version is written into the
+ * profile manifest and reinstalled there. A running server keeps the version it
+ * started with, so the command reports that a restart is what makes the change take
+ * effect rather than pretending the running process changed underneath the user.
+ */
+async function update(argv) {
+    const checkOnly = argv.includes('--check');
+    const assumeYes = argv.includes('--yes');
+    const anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    const distribution = readDistributionProfile(paths.distributionDirectory);
+    const installed = distribution.version;
+    const newer = newerVersion(distribution.name, installed);
+    if (newer === undefined) {
+        console.log('Plus ' + installed + ' is the newest published release.');
+        return 0;
+    }
+    console.log('Installed: ' + installed);
+    console.log('Available: ' + newer.version + (newer.publishedAt === undefined ? '' : ' (' + newer.publishedAt + ')'));
+    if (checkOnly)
+        return 0;
+    if (!assumeYes && !(await confirm('Install ' + newer.version + '?'))) {
+        console.log('Nothing changed.');
+        return 0;
+    }
+    const profilePath = join(paths.profileDirectory, 'package.json');
+    const profile = JSON.parse(readFileSync(profilePath, 'utf8'));
+    const dependencies = profile.dependencies;
+    if (dependencies === null || typeof dependencies !== 'object' || Array.isArray(dependencies)) {
+        throw new Error('the profile manifest has no dependencies to update');
+    }
+    ;
+    dependencies['@sparkelf/dsh-plus'] = newer.version;
+    writeFileSync(profilePath, JSON.stringify(profile, null, 2) + '\n');
+    console.log('Updated the profile to ' + newer.version + '; installing...');
+    const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], {
+        cwd: paths.profileDirectory,
+        stdio: 'inherit',
+        env: { ...process.env, DSH_HOME: paths.home },
+    });
+    if (result.status !== 0) {
+        console.error('The install failed; the profile still requests ' + newer.version + '.');
+        return 1;
+    }
+    console.log('Plus is now ' + newer.version + '.');
+    const running = readState(paths.home);
+    if (running !== undefined) {
+        console.log('The running server still serves ' + installed + '; run dsh-plus restart to load the new release.');
+    }
+    return 0;
+}
+/**
+ * Write the profile's capability patch layer.
+ *
+ * The profile's loader merges this file, so enabling a capability is a data change
+ * rather than an edit to the deployment. Writing it on every configured run also
+ * turns a capability back off when the interview no longer selects it.
+ *
+ * @param profileDirectory - the profile whose layer is replaced.
+ * @param answers - the interview's answers.
+ */
+function writeCapabilityPatch(profileDirectory, answers) {
+    const path = join(profileDirectory, CAPABILITY_PATCH_FILE);
+    // The profile has exactly one user layer, so the capability rows live in it. A file
+    // this command did not write belongs to the deployment, and replacing it would drop
+    // whatever the operator put there; keep it beside the new layer instead.
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+    // The layer is rewritten whole, so a row this command does not own is carried over
+    // rather than dropped. Backing the file up is not a substitute: the operator's rows
+    // would stop applying until someone restored it by hand.
+    if (existing !== undefined && !existing.includes(CAPABILITY_MARKER)) {
+        writeFileSync(path + '.before-capabilities', existing);
+        console.log('  Kept the existing profile layer at ' + CAPABILITY_PATCH_FILE + '.before-capabilities');
+    }
+    writeFileSync(path, capabilityPatchLayer(answers, existing ?? ''));
+}
+/**
+ * Write the deployment's capability environment file.
+ *
+ * MinerU is switched on by the presence of its endpoint and Exa reads its key from
+ * the launch environment, so the answers reach those two through `$DSH_HOME/.env`
+ * rather than through the profile layer. The file is replaced whole on every
+ * configured start, which is also how a capability the user dropped stops applying.
+ *
+ * @param home - the deployment home whose env file the launcher reads.
+ * @param answers - the interview's answers.
+ */
+function writeCapabilityEnvironment(home, answers) {
+    const path = join(home, CAPABILITY_ENV_FILE);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    writeFileSync(path, capabilityEnvironment(answers, existing));
+}
+/** Ask one yes/no question on the terminal. */
+function confirm(question) {
+    return new Promise((resolveAnswer) => {
+        process.stdout.write(question + ' [y/N] ');
+        process.stdin.once('data', (chunk) => {
+            const answer = String(chunk).trim().toLowerCase();
+            resolveAnswer(answer === 'y' || answer === 'yes');
+        });
+    });
+}
+/**
+ * Report and change which optional capabilities this deployment has enabled.
+ *
+ * The interview runs once, at install time, and a deployment that answered it keeps its
+ * answers — so this is the only way to see what it chose or to change one answer later.
+ * The report is read from the profile layer and the env file rather than from the record,
+ * because those two are what the loader and the launch environment actually consume: a
+ * record deleted, or a layer edited by hand, would otherwise describe a deployment that
+ * does not exist.
+ *
+ * `--enable` and `--disable` edit only the rows this module owns. The profile layer is
+ * shared with rows an operator wrote themselves, so it is never replaced wholesale.
+ *
+ * @param argv - arguments after the command word.
+ * @returns the process exit code.
+ */
+function capabilities(argv) {
+    const anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    const patchPath = join(paths.profileDirectory, CAPABILITY_PATCH_FILE);
+    const envPath = join(paths.home, CAPABILITY_ENV_FILE);
+    const patchText = existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : '';
+    const envText = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+    const actual = detectEnabledCapabilities(patchText, envText);
+    const record = readCapabilityRecord(paths.home);
+    let enable = [];
+    let disable = [];
+    let asJson = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--json') {
+            asJson = true;
+            continue;
+        }
+        if (token === '--enable' || token === '--disable') {
+            const value = argv[index + 1];
+            const ids = (value ?? '').split(',').map(id => id.trim()).filter(id => id !== '');
+            if (value === undefined || ids.length === 0) {
+                console.error(token + ' requires a comma-separated list of capability ids');
+                return 1;
+            }
+            const unknown = ids.filter(id => !CAPABILITIES.some(capability => capability.id === id));
+            if (unknown.length > 0) {
+                console.error('unknown capability: ' + unknown.join(', '));
+                console.error('Known: ' + CAPABILITIES.map(capability => capability.id).join(', '));
+                return 1;
+            }
+            if (token === '--enable')
+                enable = [...new Set([...enable, ...ids])];
+            else
+                disable = [...new Set([...disable, ...ids])];
+            index += 1;
+            continue;
+        }
+        console.error('unknown option: ' + String(token));
+        return 1;
+    }
+    const conflicting = enable.filter(id => disable.includes(id));
+    if (conflicting.length > 0) {
+        console.error('cannot both enable and disable: ' + conflicting.join(', '));
+        return 1;
+    }
+    if (enable.length > 0 || disable.length > 0) {
+        const enabledNow = new Set(actual.mounted);
+        let nextPatch = patchText;
+        for (const id of enable) {
+            nextPatch = editCapabilityPatchLayer(nextPatch, id, true, record?.mineruEndpoint);
+            enabledNow.add(id);
+        }
+        for (const id of disable) {
+            nextPatch = editCapabilityPatchLayer(nextPatch, id, false);
+            enabledNow.delete(id);
+        }
+        if (!existsSync(patchPath) || !patchText.includes(CAPABILITY_MARKER)) {
+            // The layer belongs to the deployment, not to this command. Keep the previous text
+            // beside it so a structural mistake is recoverable without a backup.
+            const backup = patchPath + '.before-capabilities';
+            if (patchText !== '' && !existsSync(backup))
+                writeFileSync(backup, patchText);
+        }
+        writeFileSync(patchPath, nextPatch);
+        // The env file is rewritten from the answers so a disabled capability drops the
+        // assignment that turned it on, and an enabled one keeps a key already in the file.
+        const answers = {
+            enabled: [...enabledNow],
+            ...record?.mineruEndpoint === undefined ? {} : { mineruEndpoint: record.mineruEndpoint },
+        };
+        const nextEnv = capabilityEnvironment(answers, envText);
+        writeFileSync(envPath, nextEnv);
+        const after = detectEnabledCapabilities(nextPatch, nextEnv);
+        console.log('Updated ' + CAPABILITY_PATCH_FILE + ' and ' + CAPABILITY_ENV_FILE + '.');
+        console.log('Run dsh-plus start (or restart the server) to apply the change.');
+        return reportCapabilities(after, record, asJson);
+    }
+    return reportCapabilities(actual, record, asJson);
+}
+/**
+ * Print the capability report.
+ *
+ * @param actual - the capabilities found in the profile layer and env file.
+ * @param record - what the last configured run recorded, when a record exists.
+ * @param asJson - when true, print machine-readable JSON instead of the table.
+ * @returns the process exit code, always 0.
+ */
+function reportCapabilities(actual, record, asJson) {
+    const rows = CAPABILITIES.map((capability) => {
+        const mounted = actual.mounted.includes(capability.id);
+        const recorded = record?.enabled.includes(capability.id);
+        return { id: capability.id, title: capability.title, enabled: mounted, recorded: recorded ?? null };
+    });
+    if (asJson) {
+        console.log(JSON.stringify({
+            capabilities: rows,
+            env: actual.env,
+            recordPresent: record !== undefined,
+        }, null, 2));
+        return 0;
+    }
+    console.log('Optional capabilities:');
+    for (const row of rows) {
+        const state = row.enabled ? 'enabled ' : 'disabled';
+        // A record that disagrees with the files is the one case worth calling out: the two
+        // are supposed to describe the same deployment.
+        const drift = row.recorded !== null && row.recorded !== row.enabled ? '  (record says ' + (row.recorded ? 'enabled' : 'disabled') + ')' : '';
+        console.log('  ' + (row.enabled ? 'ok  ' : '--  ') + row.id.padEnd(14) + state + drift);
+    }
+    if (record === undefined) {
+        console.log('');
+        console.log('No ' + CAPABILITY_RECORD + ' yet; the next dsh-plus start will run the interview.');
+    }
+    console.log('');
+    console.log('Change with: dsh-plus capabilities --enable <id> | --disable <id>');
+    return 0;
+}
+async function doctor() {
+    const anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    let failures = 0;
+    const check = (ok, line) => {
+        console.log((ok ? 'ok   ' : 'FAIL ') + line);
+        if (!ok)
+            failures += 1;
+    };
+    const major = Number(process.versions.node.split('.')[0]);
+    check(major >= 22, 'Node ' + process.versions.node + ' (needs 22 or newer)');
+    check(existsSync(join(paths.distributionDirectory, 'package.json')), 'Plus distribution at ' + paths.distributionDirectory);
+    check(existsSync(join(paths.profileDirectory, 'package.json')), 'profile at ' + paths.profileDirectory + ' (dsh-plus start creates it)');
+    const free = await portAvailable(DEFAULT_PORT);
+    check(true, 'port ' + String(DEFAULT_PORT) + (free ? ' is free' : ' is in use; start will choose the next free one'));
+    // The capability record and the files that actually enable a capability are written by
+    // different runs, so they can disagree: a layer edited by hand, or a record deleted.
+    // Reporting the drift here is what turns the record from a write-only file into
+    // something a user can trust.
+    const patchPath = join(paths.profileDirectory, CAPABILITY_PATCH_FILE);
+    const envPath = join(paths.home, CAPABILITY_ENV_FILE);
+    const actual = detectEnabledCapabilities(existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : '', existsSync(envPath) ? readFileSync(envPath, 'utf8') : '');
+    const record = readCapabilityRecord(paths.home);
+    const drifted = record === undefined
+        ? []
+        : CAPABILITIES.filter(capability => record.enabled.includes(capability.id) !== actual.mounted.includes(capability.id));
+    check(drifted.length === 0, drifted.length === 0
+        ? 'capabilities: ' + (actual.mounted.length === 0 ? '(none enabled)' : actual.mounted.join(', '))
+        : 'capabilities disagree with ' + CAPABILITY_RECORD + ': ' + drifted.map(capability => capability.id).join(', ')
+            + ' (run dsh-plus capabilities)');
+    console.log(failures === 0 ? 'No problems found.' : String(failures) + ' problem(s) found.');
+    return failures === 0 ? 0 : 1;
+}
+function parseInstallOptions(argv) {
+    let edition;
+    const exclude = [];
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const value = argv[index + 1];
+        if (token === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (token === '--edition') {
+            if (value === undefined || value === '')
+                throw new Error('--edition requires a value');
+            edition = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--exclude') {
+            if (value === undefined || value === '')
+                throw new Error('--exclude requires a package name');
+            exclude.push(value);
+            index += 1;
+            continue;
+        }
+        throw new Error('unknown option: ' + String(token));
+    }
+    return { edition, exclude, dryRun };
+}
+/**
+ * Materialize a profile without starting the server.
+ *
+ * The build system installs the distribution once and needs the profile on disk before it
+ * snapshots the image; starting a server to create it would also start a process the image
+ * must then kill.
+ *
+ * @param argv - arguments after the command word.
+ * @returns the process exit code.
+ */
+function install(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+    }
+    const options = parseInstallOptions(argv);
+    // One axis: the edition names the package and bundle set this deployment installs, and its
+    // profile name travels with it. No edition means the full distribution.
+    const paths = resolvePaths(declarationAnchor(), process.env, options.edition);
+    const created = ensureProfile(paths, options.edition, options.exclude, options.dryRun);
+    console.log((created ? 'Created the ' : 'Using the existing ') + paths.profileName + ' profile at ' + paths.profileDirectory);
+    return 0;
+}
+function parseManifestOptions(argv) {
+    let distribution;
+    let out;
+    // The DataOps workspace image is the only build consumer of this command, so its edition is
+    // the default; a generic caller states the edition it wants.
+    let edition = DEFAULT_EDITION;
+    const exclude = [];
+    let runtime;
+    let registry = 'https://registry.npmjs.org';
+    let verify = false;
+    let check = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        const value = argv[index + 1];
+        if (token === '--distribution') {
+            if (value === undefined)
+                throw new Error('--distribution requires a value');
+            distribution = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--out') {
+            if (value === undefined)
+                throw new Error('--out requires a value');
+            out = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--edition') {
+            if (value === undefined)
+                throw new Error('--edition requires a value');
+            edition = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--exclude') {
+            if (value === undefined)
+                throw new Error('--exclude requires a package name');
+            exclude.push(value);
+            index += 1;
+            continue;
+        }
+        if (token === '--runtime') {
+            if (value === undefined)
+                throw new Error('--runtime requires a value');
+            runtime = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--registry') {
+            if (value === undefined)
+                throw new Error('--registry requires a value');
+            registry = value;
+            index += 1;
+            continue;
+        }
+        if (token === '--verify') {
+            verify = true;
+            continue;
+        }
+        if (token === '--check') {
+            check = true;
+            continue;
+        }
+        throw new Error('unknown option: ' + String(token));
+    }
+    return { distribution, out, edition, exclude, runtime, registry, verify, check };
+}
+/**
+ * Write or verify the profile manifest a build installs.
+ *
+ * `--out` names the profile directory. `--check` compares what is there against a fresh
+ * projection instead of writing, so a committed profile cannot drift from the distribution.
+ *
+ * @param argv - arguments after the command word.
+ * @returns the process exit code.
+ */
+async function manifest(argv) {
+    const options = parseManifestOptions(argv);
+    const directory = options.distribution ?? resolveDistributionDirectory(declarationAnchor());
+    const facts = options.runtime === undefined
+        ? readDistributionFacts(directory)
+        : { ...readDistributionFacts(directory), runtimeVersion: options.runtime };
+    const projection = projectEdition(facts, options.edition, options.exclude);
+    if (options.verify)
+        await assertRedirectsPublished({ ...facts.redirects, ...projection.omittedPackages }, options.registry);
+    if (options.out === undefined)
+        throw new Error('manifest requires --out <directory>');
+    if (options.check) {
+        const written = join(options.out, 'package.json');
+        if (!existsSync(written))
+            throw new Error('manifest: ' + written + ' does not exist; run the generator');
+        const actual = JSON.parse(readFileSync(written, 'utf8'));
+        const expectedDependencies = {
+            '@sparkelf/dsh-plus': facts.version,
+            '@deepseek-ai/dsh': '>=' + facts.runtimeVersion,
+            ...projection.dependencies,
+        };
+        const drift = [];
+        for (const [name, spec] of Object.entries(expectedDependencies)) {
+            if (actual.dependencies?.[name] !== spec)
+                drift.push('dependency ' + name);
+        }
+        for (const name of Object.keys(actual.dependencies ?? {})) {
+            if (expectedDependencies[name] === undefined)
+                drift.push('extra dependency ' + name);
+        }
+        for (const bundle of projection.bundles) {
+            if (!(actual.dsh?.profile?.bundles ?? []).includes(bundle))
+                drift.push('bundle ' + bundle);
+        }
+        if (drift.length > 0)
+            throw new Error('manifest: ' + written + ' is stale in ' + drift.join(', '));
+        console.log('manifest: ' + written + ' matches the distribution');
+        return 0;
+    }
+    writeProfileProjection(options.out, facts, options.edition, options.exclude);
+    console.log(JSON.stringify({
+        profile: projection.profileName,
+        runtime: facts.runtimeVersion,
+        bundles: projection.bundles.length,
+        dependencies: Object.keys(projection.dependencies).length,
+        redirects: Object.keys(facts.redirects).length,
+        overrides: Object.keys(projection.overrides).length,
+        omitted: Object.keys(projection.omittedPackages),
+    }));
+    return 0;
+}
+/**
+ * Print the distribution facts a build or a release gate consumes.
+ *
+ * @param argv - accepts `--distribution <dir>` only.
+ * @returns the process exit code.
+ */
+function inspect(argv) {
+    let directory;
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] !== '--distribution')
+            throw new Error('unknown option: ' + String(argv[index]));
+        directory = argv[index + 1];
+        if (directory === undefined)
+            throw new Error('--distribution requires a value');
+        index += 1;
+    }
+    const facts = readDistributionFacts(directory ?? resolveDistributionDirectory(declarationAnchor()));
+    console.log(JSON.stringify({
+        name: facts.name,
+        version: facts.version,
+        runtime: facts.runtimeVersion,
+        profile: facts.name,
+        bundles: facts.bundles,
+        dependencies: facts.dependencies,
+        redirects: facts.redirects,
+        redirectPatch: facts.redirectIds,
+        editions: Object.entries(facts.editions).map(([id, edition]) => ({
+            id,
+            label: edition.label,
+            profile: edition.profile,
+            bundles: edition.bundles.length,
+            packages: edition.packages.length,
+            omit: edition.omit.length,
+        })),
+    }, null, 2));
+    return 0;
+}
+const USAGE = [
+    'Usage: dsh-plus <command> [options]',
+    '',
+    'Commands:',
+    '  install       materialize the profile without starting the server',
+    '  manifest      write or verify the profile manifest a build installs',
+    '  inspect       print the distribution facts as JSON',
+    '  start         start the server (first run creates the profile)',
+    '  stop          stop the server',
+    '  status        report whether the server is running',
+    '  capabilities  report or change the optional capabilities',
+    '  update        move to a newer distribution release',
+    '  doctor        check this installation',
+    '',
+    'install options:',
+    '  --edition <id>  product edition to materialize (personal, team, intranet-team)',
+    '  --exclude <pkg> drop a package and its bundle row (repeatable)',
+    '',
+    'manifest options:',
+    '  --out <dir>          profile directory to write',
+    '  --edition <id>       product edition to project (default: ' + DEFAULT_EDITION + ')',
+    '  --exclude <pkg>      drop a package and its bundle row (repeatable)',
+    '  --runtime <version>  override the runtime version the redirects name',
+    '  --registry <url>     registry checked by --verify',
+    '  --verify             fail unless every redirect target is published',
+    '  --check              compare --out with a fresh projection instead of writing',
+    '',
+    'start options:',
+    '  --port <n>     port to prefer (default ' + String(DEFAULT_PORT) + '; a taken port moves to the next free one)',
+    '  --host <h>     interface to bind (default 127.0.0.1)',
+    '  --no-open      do not open a browser',
+    '  --foreground   run in this terminal instead of in the background',
+    '  --edition <id> product edition to materialize',
+    '  --exclude <pkg> drop a package and its bundle row (repeatable)',
+    '',
+    'capabilities options:',
+    '  --enable <ids>   enable the comma-separated capability ids',
+    '  --disable <ids>  disable the comma-separated capability ids',
+    '  --json           print the report as JSON',
+    '',
+    'update options:',
+    '  --check        report the available release without installing it',
+    '  --yes          install without asking',
+].join('\n');
+/**
+ * Dispatch one command line.
+ *
+ * @param argv - arguments after the executable and script name.
+ * @returns the process exit code.
+ */
+export async function runStandaloneCli(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '--help' || command === '-h' || command === 'help') {
+        console.log(USAGE);
+        return 0;
+    }
+    if (command === 'install')
+        return install(rest);
+    if (command === 'manifest')
+        return await manifest(rest);
+    if (command === 'inspect')
+        return inspect(rest);
+    if (command === 'start')
+        return await start(rest);
+    if (command === 'stop')
+        return stop();
+    if (command === 'status')
+        return status();
+    if (command === 'capabilities')
+        return capabilities(rest);
+    if (command === 'update')
+        return await update(rest);
+    if (command === 'doctor')
+        return doctor();
+    console.error('unknown command: ' + command);
+    console.error(USAGE);
+    return 1;
+}
+//# sourceMappingURL=cli.js.map