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

package/lib/types/standalone-cli.js

@@ -10,18 +10,22 @@
 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 { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { newerVersion } from "./registry-versions.js";
+import { CAPABILITIES, CAPABILITY_ENV_FILE, CAPABILITY_MARKER, CAPABILITY_RECORD, DEFAULT_MINERU_ENDPOINT, capabilityEnvironment, capabilityPatchLayer, detectEnabledCapabilities, editCapabilityPatchLayer, installCapabilityServices, interviewCapabilities, readCapabilityRecord, } from "./standalone-capabilities.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;
+/** 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;
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === '--port' || token === '-p') {
@@ -48,9 +52,47 @@ function parseStartOptions(argv) {
             foreground = true;
             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 };
+    return { port, host, open, foreground, capabilities };
+}
+/**
+ * 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.
@@ -84,13 +126,32 @@ function installationRoot() {
 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() {
+    const invoked = process.argv[1];
+    return invoked === undefined || invoked === '' ? fileURLToPath(import.meta.url) : resolve(invoked);
+}
 /** 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];
+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' });
@@ -99,7 +160,9 @@ function runForeground(entry, port, host, open) {
 async function start(argv) {
     const options = parseStartOptions(argv);
     const anchor = installationAnchor();
-    const paths = resolvePaths(anchor);
+    // 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());
     // 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.
@@ -141,26 +204,47 @@ async function start(argv) {
     }
     const created = ensureProfile(paths, installationRoot());
     console.log(created
-        ? 'Created the ' + STANDALONE_PROFILE + ' profile at ' + paths.profileDirectory
-        : 'Using the existing ' + STANDALONE_PROFILE + ' profile');
+        ? '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 = await 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(anchor);
     if (options.foreground)
-        return runForeground(entry, options.port, options.host, options.open);
+        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.home, entry, options);
+    return startDetached(paths, entry, options);
 }
-async function startDetached(home, 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) + '.');
@@ -169,9 +253,9 @@ async function startDetached(home, entry, options) {
     }
     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 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);
@@ -282,6 +366,47 @@ async function update(argv) {
     }
     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) => {
@@ -292,6 +417,140 @@ function confirm(question) {
         });
     });
 }
+/**
+ * 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);
@@ -307,6 +566,21 @@ async function doctor() {
     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;
 }
@@ -314,11 +588,12 @@ 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         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',
     '',
     'start options:',
     '  --port <n>     port to prefer (default ' + String(DEFAULT_PORT) + '; a taken port moves to the next free one)',
@@ -326,6 +601,11 @@ const USAGE = [
     '  --no-open      do not open a browser',
     '  --foreground   run in this terminal instead of in the background',
     '',
+    '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',
@@ -348,6 +628,8 @@ export async function runStandaloneCli(argv) {
         return stop();
     if (command === 'status')
         return status();
+    if (command === 'capabilities')
+        return capabilities(rest);
     if (command === 'update')
         return await update(rest);
     if (command === 'doctor')

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

@@ -8,12 +8,56 @@
  * the launcher mounts exactly the bundles the profile names and nothing expands a
  * bundle's own list.
  */
-/** Profile name a standalone installation owns. */
+/** Profile name a standalone installation owns when its package declares none. */
 export declare const STANDALONE_PROFILE = "plus";
+/**
+ * Read the profile name the installing package declares.
+ *
+ * A standalone package describes the profile it materializes, so a reduced variant can
+ * own a differently named profile beside the full one instead of overwriting it. The
+ * declaration travels with the package because npm resolves the tree long before any
+ * command of ours runs, and the distribution cannot name a profile for a package it
+ * does not own.
+ *
+ * @param anchor - path inside the installing package's tree.
+ * @param fallback - profile name to use when the declaration is absent.
+ * @returns the declared profile name, or the fallback.
+ */
+export declare function resolveStandaloneProfile(anchor: string, fallback?: string): string;
+/** What the installing package declares about the deployment it owns. */
+export interface StandaloneDeclaration {
+    /** Profile name the launcher materializes. */
+    readonly profileName: string;
+    /**
+     * Capabilities the deployment must not install, as package name to override spec.
+     *
+     * npm substitutes rather than deletes, so each entry names the placeholder the
+     * capability is replaced with. The profile workspace applies these as overrides,
+     * which is where pnpm reads them.
+     */
+    readonly omittedPackages: Readonly<Record<string, string>>;
+}
+/**
+ * Read the deployment facts the installing package declares.
+ *
+ * A standalone package describes the profile it materializes and the capabilities it
+ * omits, so a reduced variant owns a differently named profile and a reduced install
+ * without the distribution naming either. The declaration travels with the package
+ * because npm resolves the tree long before any command of ours runs.
+ *
+ * @param anchor - path inside the installing package's tree.
+ * @param fallback - profile name to use when the declaration is absent.
+ * @returns the declared profile name and omitted capabilities.
+ */
+export declare function readStandaloneDeclaration(anchor: string, fallback?: string): StandaloneDeclaration;
 /** Resolved locations for one standalone installation. */
 export interface StandalonePaths {
     /** DSH home holding profiles, credentials, and session data. */
     readonly home: string;
+    /** Profile name the launcher boots, as the installing package declares it. */
+    readonly profileName: string;
+    /** Capabilities the deployment omits, as package name to override spec. */
+    readonly omittedPackages: Readonly<Record<string, string>>;
     /** Profile directory the launcher boots. */
     readonly profileDirectory: string;
     /** Installed Plus distribution directory. */

package/lib/types/standalone-profile.js

@@ -14,8 +14,79 @@ import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join, posix, resolve, win32 } from 'node:path';
 import { parseDocument } from 'yaml';
-/** Profile name a standalone installation owns. */
+/** Profile name a standalone installation owns when its package declares none. */
 export const STANDALONE_PROFILE = 'plus';
+/**
+ * Read the profile name the installing package declares.
+ *
+ * A standalone package describes the profile it materializes, so a reduced variant can
+ * own a differently named profile beside the full one instead of overwriting it. The
+ * declaration travels with the package because npm resolves the tree long before any
+ * command of ours runs, and the distribution cannot name a profile for a package it
+ * does not own.
+ *
+ * @param anchor - path inside the installing package's tree.
+ * @param fallback - profile name to use when the declaration is absent.
+ * @returns the declared profile name, or the fallback.
+ */
+export function resolveStandaloneProfile(anchor, fallback = STANDALONE_PROFILE) {
+    return readStandaloneDeclaration(anchor, fallback).profileName;
+}
+/**
+ * Read the deployment facts the installing package declares.
+ *
+ * A standalone package describes the profile it materializes and the capabilities it
+ * omits, so a reduced variant owns a differently named profile and a reduced install
+ * without the distribution naming either. The declaration travels with the package
+ * because npm resolves the tree long before any command of ours runs.
+ *
+ * @param anchor - path inside the installing package's tree.
+ * @param fallback - profile name to use when the declaration is absent.
+ * @returns the declared profile name and omitted capabilities.
+ */
+export function readStandaloneDeclaration(anchor, fallback = STANDALONE_PROFILE) {
+    // The anchor is the CLI file; walk out to the package that declares the forwarder.
+    let current = resolve(anchor);
+    for (;;) {
+        const manifestPath = join(current, 'package.json');
+        const declared = readStandaloneFacts(manifestPath);
+        if (declared !== undefined)
+            return declared;
+        const parent = dirname(current);
+        if (parent === current)
+            return { profileName: fallback, omittedPackages: {} };
+        current = parent;
+    }
+}
+/** Read one manifest's standalone declaration, or undefined when it carries none. */
+function readStandaloneFacts(manifestPath) {
+    if (!existsSync(manifestPath))
+        return undefined;
+    let standalone;
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        standalone = manifest.dshPlusStandalone;
+    }
+    catch {
+        // A package whose manifest cannot be read declares nothing; the caller keeps walking
+        // because the declaring package may sit above it.
+        return undefined;
+    }
+    const profile = standalone?.profile;
+    if (standalone === undefined || typeof profile !== 'string' || profile === '')
+        return undefined;
+    const rawOmitted = standalone.omittedPackages;
+    const omittedPackages = {};
+    if (rawOmitted !== undefined && typeof rawOmitted === 'object' && !Array.isArray(rawOmitted)) {
+        for (const [name, spec] of Object.entries(rawOmitted)) {
+            if (typeof spec !== 'string' || spec === '') {
+                throw new Error('dshPlusStandalone.omittedPackages.' + name + ' must be a non-empty string');
+            }
+            omittedPackages[name] = spec;
+        }
+    }
+    return { profileName: profile, omittedPackages };
+}
 function requireRecord(value, label) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         throw new Error(label + ' must be an object');
@@ -336,9 +407,12 @@ function linkBundle(consumerModules, name, source) {
 /** Resolve every path a command needs, without creating anything. */
 export function resolvePaths(anchor, env = process.env) {
     const home = resolveHome(env);
+    const declaration = readStandaloneDeclaration(anchor);
     return {
         home,
-        profileDirectory: join(home, 'profiles', STANDALONE_PROFILE),
+        profileName: declaration.profileName,
+        omittedPackages: declaration.omittedPackages,
+        profileDirectory: join(home, 'profiles', declaration.profileName),
         distributionDirectory: resolveDistributionDirectory(anchor),
     };
 }
@@ -366,7 +440,7 @@ export function ensureProfile(paths, consumerDirectory) {
         // script allowlist — and a distribution release changes them. Rewriting on every
         // start is what lets an upgraded installation receive the new values; a profile
         // written once keeps whatever its own release decided and can never be corrected.
-        writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds);
+        writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds, paths.omittedPackages);
         installProfilePackages(paths, consumerDirectory);
         return false;
     }
@@ -392,7 +466,7 @@ export function ensureProfile(paths, consumerDirectory) {
     };
     writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
     // The overrides must reach the workspace before the install that reads them.
-    writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds);
+    writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds, paths.omittedPackages);
     installProfilePackages(paths, consumerDirectory);
     return true;
 }
@@ -406,7 +480,7 @@ export function ensureProfile(paths, consumerDirectory) {
  * @param profileDirectory - the standalone profile directory.
  * @param overrides - official package name to published replacement spec.
  */
-function writeProfileOverrides(profileDirectory, overrides, allowBuilds) {
+function writeProfileOverrides(profileDirectory, overrides, allowBuilds, omittedPackages) {
     const workspacePath = join(profileDirectory, 'pnpm-workspace.yaml');
     const document = parseDocument(existsSync(workspacePath) ? readFileSync(workspacePath, 'utf8') : '');
     const [documentError] = document.errors;
@@ -416,6 +490,11 @@ function writeProfileOverrides(profileDirectory, overrides, allowBuilds) {
         document.set('packages', ['.']);
     for (const [name, spec] of Object.entries(overrides))
         document.setIn(['overrides', name], spec);
+    // A capability the deployment omits is substituted rather than deleted, because npm's
+    // override has no removal form. Writing it here keeps the omission in the one place
+    // pnpm reads, so an install never receives the capability the variant excluded.
+    for (const [name, spec] of Object.entries(omittedPackages))
+        document.setIn(['overrides', name], spec);
     // pnpm refuses an install whose packages want to run build scripts until each is
     // decided, so the distribution's reviewed decisions travel with the install rather
     // than waiting for an interactive approval no start can offer.