@sparkelf/dsh-plus 0.1.0-rc.9 → 0.2.0-rc.2

package/lib/types/bin.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { runApply } from "./apply.js";
+import { runStandaloneCli } from "./standalone-cli.js";
+/**
+ * Dispatch the command line.
+ *
+ * `apply` remains the materialization command a source-based installation runs; every
+ * other word is a standalone lifecycle command. Reaching the dispatcher first keeps
+ * one executable for both, so a user who installed the distribution from the registry
+ * never needs to know which half owns a command.
+ *
+ * @returns the process exit code.
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    const first = argv[0];
+    if (first === 'apply') {
+        // `runApply` parses the command word itself, so it receives the arguments this
+        // dispatcher already inspected rather than a slice that dropped it.
+        runApply(argv);
+        return 0;
+    }
+    return await runStandaloneCli(argv);
+}
+try {
+    process.exitCode = await main();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=bin.js.map

package/lib/types/index.js

@@ -0,0 +1,9 @@
+/**
+ * @sparkelf/dsh-plus carries the Plus Web profile composition, ranged
+ * compatibility declarations, and independent patch-package references. The
+ * profile composer resolves its Cordis patch through the package manifest; the
+ * root module exposes no runtime API, while the explicit CLI lives at ./apply.
+ * @module @sparkelf/dsh-plus
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/lib/types/registry-versions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Registry queries behind the `update` command.
+ *
+ * A standalone installation pins one exact distribution version, so it needs two
+ * facts npm's own updater cannot give it: which versions exist, and which of them is
+ * newer than the one installed. `pnpm update` treats an exact pin as a range of one
+ * and always reports "already up to date".
+ */
+/** One published version with the time the registry recorded for it. */
+export interface PublishedVersion {
+    /** Published version. */
+    readonly version: string;
+    /** Publication time in ISO form, when the registry reports one. */
+    readonly publishedAt?: string;
+}
+/** Every published version of one package, oldest first, with publication times. */
+export declare function publishedVersions(name: string, registry?: string): PublishedVersion[];
+/**
+ * The highest published version that is newer than the installed one.
+ *
+ * Prerelease ordering matters here: an installation on a release candidate must not
+ * be told that an older stable release is an upgrade, and must be told about a newer
+ * candidate.
+ *
+ * @param name - package to query.
+ * @param installed - version currently installed.
+ * @param registry - registry to query.
+ * @returns the newer version, or undefined when the installation is current.
+ */
+export declare function newerVersion(name: string, installed: string, registry?: string): PublishedVersion | undefined;
+//# sourceMappingURL=registry-versions.d.ts.map

package/lib/types/registry-versions.js

@@ -0,0 +1,61 @@
+/**
+ * Registry queries behind the `update` command.
+ *
+ * A standalone installation pins one exact distribution version, so it needs two
+ * facts npm's own updater cannot give it: which versions exist, and which of them is
+ * newer than the one installed. `pnpm update` treats an exact pin as a range of one
+ * and always reports "already up to date".
+ */
+import { execFileSync } from 'node:child_process';
+import semver from 'semver';
+/** Every published version of one package, oldest first, with publication times. */
+export function publishedVersions(name, registry = 'https://registry.npmjs.org') {
+    let raw;
+    try {
+        raw = execFileSync('npm', ['view', name, 'time', '--json', '--registry', registry], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return [];
+    const times = parsed;
+    const entries = [];
+    for (const [version, time] of Object.entries(times)) {
+        // `created` and `modified` are registry bookkeeping, not releases.
+        if (version === 'created' || version === 'modified')
+            continue;
+        if (semver.valid(version) === null)
+            continue;
+        entries.push(typeof time === 'string' ? { version, publishedAt: time } : { version });
+    }
+    return entries.sort((left, right) => semver.compare(left.version, right.version));
+}
+/**
+ * The highest published version that is newer than the installed one.
+ *
+ * Prerelease ordering matters here: an installation on a release candidate must not
+ * be told that an older stable release is an upgrade, and must be told about a newer
+ * candidate.
+ *
+ * @param name - package to query.
+ * @param installed - version currently installed.
+ * @param registry - registry to query.
+ * @returns the newer version, or undefined when the installation is current.
+ */
+export function newerVersion(name, installed, registry = 'https://registry.npmjs.org') {
+    const candidates = publishedVersions(name, registry)
+        .filter(entry => semver.gt(entry.version, installed));
+    return candidates.at(-1);
+}
+//# sourceMappingURL=registry-versions.js.map

package/lib/types/standalone-cli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+/**
+ * Dispatch one command line.
+ *
+ * @param argv - arguments after the executable and script name.
+ * @returns the process exit code.
+ */
+export declare function runStandaloneCli(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=standalone-cli.d.ts.map

package/lib/types/standalone-cli.js

@@ -0,0 +1,359 @@
+/**
+ * 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 { DEFAULT_PORT, STOP_GRACE_MILLISECONDS, choosePort, clearState, isRunning, portAvailable, readState, spawnServer, stateDirectory, waitForAuthenticatedUrl, waitForServer, writeState, } from "./standalone-server.js";
+import { STANDALONE_PROFILE, applyProfileNpmPatches, ensureProfile, pnpmAvailable, pnpmInstallCommand, pnpmInstallCommands, registryOrder, readDistributionProfile, resolvePaths, } from "./standalone-profile.js";
+/** Milliseconds a start waits for the server to answer before reporting failure. */
+const READY_TIMEOUT_MILLISECONDS = 90_000;
+function parseStartOptions(argv) {
+    let port = DEFAULT_PORT;
+    let host = '127.0.0.1';
+    let open = true;
+    let foreground = false;
+    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;
+        }
+        throw new Error('unknown option: ' + token);
+    }
+    return { port, host, open, foreground };
+}
+/**
+ * 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');
+}
+/** The launcher entry this installation must drive. */
+function launcherEntry(anchor) {
+    return createRequire(anchor).resolve('@deepseek-ai/dsh/lib/bin.js');
+}
+/** Run the server in this process, inheriting stdio. */
+function runForeground(entry, port, host, open) {
+    const args = [entry, '--profile', STANDALONE_PROFILE, '--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);
+    const anchor = installationAnchor();
+    const paths = resolvePaths(anchor);
+    // 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 ' + STANDALONE_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, installationRoot());
+    console.log(created
+        ? 'Created the ' + STANDALONE_PROFILE + ' profile at ' + paths.profileDirectory
+        : 'Using the existing ' + STANDALONE_PROFILE + ' 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);
+    }
+    const entry = launcherEntry(anchor);
+    if (options.foreground)
+        return runForeground(entry, 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.home, entry, options);
+}
+async function startDetached(home, entry, options) {
+    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(home), 'server.log');
+    const env = { ...process.env, DSH_HOME: home };
+    const args = [entry, '--profile', STANDALONE_PROFILE, '--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;
+}
+/** 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');
+        });
+    });
+}
+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'));
+    console.log(failures === 0 ? 'No problems found.' : String(failures) + ' problem(s) found.');
+    return failures === 0 ? 0 : 1;
+}
+const USAGE = [
+    'Usage: dsh-plus <command> [options]',
+    '',
+    'Commands:',
+    '  start     start the server (first run creates the profile)',
+    '  stop      stop the server',
+    '  status    report whether the server is running',
+    '  update    move to a newer distribution release',
+    '  doctor    check this installation',
+    '',
+    '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',
+    '',
+    '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 === 'start')
+        return await start(rest);
+    if (command === 'stop')
+        return stop();
+    if (command === 'status')
+        return status();
+    if (command === 'update')
+        return await update(rest);
+    if (command === 'doctor')
+        return doctor();
+    console.error('unknown command: ' + command);
+    console.error(USAGE);
+    return 1;
+}
+//# sourceMappingURL=standalone-cli.js.map