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

package/lib/types/standalone-cli.js

@@ -10,12 +10,15 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+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 "./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";
+import { STANDALONE_PROFILE, applyProfileNpmPatches, ensureProfile, pnpmAvailable, pnpmInstallCommand, pnpmInstallCommands, registryOrder, readDistributionProfile, resolveDistributionDirectory, resolveInvocationAnchor, resolvePaths, } from "./standalone-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). */
@@ -25,8 +28,9 @@ function parseStartOptions(argv) {
     let host = '127.0.0.1';
     let open = true;
     let foreground = false;
-    let edition;
     let capabilities;
+    let edition;
+    const exclude = [];
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === '--port' || token === '-p') {
@@ -61,6 +65,14 @@ function parseStartOptions(argv) {
             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)
@@ -82,7 +94,7 @@ function parseStartOptions(argv) {
         }
         throw new Error('unknown option: ' + String(token));
     }
-    return { port, host, open, foreground, edition, capabilities };
+    return { port, host, open, foreground, capabilities, edition, exclude };
 }
 /**
  * Resolve a stated capability selection.
@@ -151,12 +163,23 @@ function installationAnchor() {
  * @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);
+    // 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. */
-function launcherEntry(anchor) {
-    return createRequire(anchor).resolve('@deepseek-ai/dsh/lib/bin.js');
+/**
+ * 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) {
@@ -166,60 +189,11 @@ function runForeground(entry, profileName, port, host, open) {
     const result = spawnSync(process.execPath, args, { stdio: 'inherit' });
     return result.status ?? 1;
 }
-/** Parse the install command's edition selection. */
-function parseInstallOptions(argv) {
-    let edition;
-    let profile;
-    for (let index = 0; index < argv.length; index += 1) {
-        const token = argv[index];
-        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 === '--profile') {
-            const value = argv[index + 1];
-            if (value === undefined || value === '')
-                throw new Error('--profile requires a value');
-            profile = value;
-            index += 1;
-            continue;
-        }
-        throw new Error('unknown option: ' + String(token));
-    }
-    if (edition === undefined)
-        throw new Error('install requires --edition personal or --edition team');
-    return { edition, profile };
-}
-/**
- * Install one edition's package manifest into the profile.
- *
- * The profile's `package.json` is the install artifact; there is no separate standalone
- * package. A later `start` uses the same manifest, so changing the edition is a new
- * install rather than a second product.
- *
- * @param argv - arguments after `install`.
- * @returns the process exit code.
- */
-function install(argv) {
-    const { edition, profile } = parseInstallOptions(argv);
-    const base = resolvePaths(declarationAnchor());
-    const paths = profile === undefined
-        ? base
-        : { ...base, profileName: profile, profileDirectory: join(base.home, 'profiles', profile) };
-    ensureProfile(paths, installationRoot(), edition);
-    console.log('Installed the ' + edition + ' edition into ' + paths.profileDirectory);
-    return 0;
-}
 async function start(argv) {
     const options = parseStartOptions(argv);
-    const anchor = installationAnchor();
     // 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());
+    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.
@@ -259,12 +233,10 @@ async function start(argv) {
         }
         console.log('pnpm installed.');
     }
-    const created = ensureProfile(paths, installationRoot(), options.edition);
+    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');
-    if (options.edition !== undefined)
-        console.log('Edition: ' + options.edition);
     // 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.
@@ -291,7 +263,7 @@ async function start(argv) {
             console.log('  Exa: add EXA_API_KEY to ' + join(paths.home, CAPABILITY_ENV_FILE) + ' when you have a key.');
         }
     }
-    const entry = launcherEntry(anchor);
+    const entry = launcherEntry(paths.profileDirectory);
     if (options.foreground)
         return runForeground(entry, paths.profileName, options.port, options.host, options.open);
     const existing = readState(paths.home);
@@ -640,38 +612,233 @@ async function doctor() {
         ? '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)');
-    const profileManifestPath = join(paths.profileDirectory, 'package.json');
-    if (existsSync(profileManifestPath)) {
-        const profileManifest = JSON.parse(readFileSync(profileManifestPath, 'utf8'));
-        const editionId = profileManifest.dsh?.profile?.plusEdition;
-        if (editionId !== undefined) {
-            const distribution = readDistributionProfile(paths.distributionDirectory);
-            const edition = distribution.editions[editionId];
-            if (edition === undefined) {
-                check(false, 'edition "' + editionId + '" is not declared by this distribution');
-            }
-            else {
-                const bundles = new Set(profileManifest.dsh?.profile?.bundles ?? []);
-                const missingBundles = edition.bundles.filter(bundle => !bundles.has(bundle));
-                const packageNames = Object.keys(edition.packages);
-                const missingPackages = packageNames.filter(name => !existsSync(join(paths.profileDirectory, 'node_modules', ...name.split('/'), 'package.json')));
-                check(missingBundles.length === 0, 'edition ' + editionId + ': ' + String(edition.bundles.length - missingBundles.length) + '/'
-                    + String(edition.bundles.length) + ' bundles mounted'
-                    + (missingBundles.length === 0 ? '' : ' (missing ' + missingBundles.join(', ') + ')'));
-                check(missingPackages.length === 0, 'edition ' + editionId + ': ' + String(packageNames.length - missingPackages.length) + '/'
-                    + String(packageNames.length) + ' packages installed'
-                    + (missingPackages.length === 0 ? '' : ' (missing ' + missingPackages.join(', ') + ')'));
-            }
-        }
-    }
     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       install an edition package manifest into the profile',
+    '  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',
@@ -679,16 +846,26 @@ const USAGE = [
     '  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> install the named edition manifest (personal or team)',
-    '',
-    'install options:',
-    '  --edition <id>  package manifest to install (personal or team)',
-    '  --profile <n>   profile name to install into (default: this installation)',
+    '  --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',
@@ -713,6 +890,10 @@ export async function runStandaloneCli(argv) {
     }
     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')

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

@@ -8,6 +8,7 @@
  * the launcher mounts exactly the bundles the profile names and nothing expands a
  * bundle's own list.
  */
+import { readDistributionFacts } from './manifest.ts';
 /** Profile name a standalone installation owns when its package declares none. */
 export declare const STANDALONE_PROFILE = "plus";
 /**
@@ -63,6 +64,19 @@ export interface StandalonePaths {
     /** Installed Plus distribution directory. */
     readonly distributionDirectory: string;
 }
+/**
+ * Resolve the file that was actually invoked from the path the shell was handed.
+ *
+ * A global npm install links `<prefix>/bin/dsh-plus` to the package entry. Resolving
+ * `@sparkelf/dsh-plus` from that link starts at the bin directory, which has no
+ * `node_modules`, so every globally installed command reported the distribution as
+ * missing. The real path is the package file, and the package resolves its own name.
+ *
+ * @param invoked - `process.argv[1]`, or undefined when node ran without a script.
+ * @param fallback - this module's own file, used when there is no script path.
+ * @returns an absolute path that exists, or the input when it cannot be resolved.
+ */
+export declare function resolveInvocationAnchor(invoked: string | undefined, fallback: string): string;
 /** Resolve the DSH home, honouring the environment override the launcher itself reads. */
 export declare function resolveHome(env?: NodeJS.ProcessEnv): string;
 /**
@@ -92,21 +106,18 @@ export declare function isWithin(candidate: string, parent: string, platform?: N
  * @returns absolute path to the installed distribution.
  */
 export declare function resolveDistributionDirectory(anchor: string): string;
-/** The reviewed bundle order and pins the installed distribution declares. */
-export interface EditionComposition {
-    readonly label: string;
-    readonly bundles: readonly string[];
-    readonly packages: Readonly<Record<string, string>>;
-}
-export declare function readDistributionProfile(distributionDirectory: string): {
+/** The reviewed bundle order and pins the installed distribution declares, for one variant. */
+export declare function readDistributionProfile(distributionDirectory: string, editionId?: string, extraExcludes?: readonly string[]): {
     readonly name: string;
+    readonly version: string;
+    readonly dshRange: string;
+    readonly runtimeVersion: string;
     readonly bundles: readonly string[];
     readonly dependencies: Readonly<Record<string, string>>;
     readonly allowBuilds: Readonly<Record<string, boolean>>;
     readonly overrides: Readonly<Record<string, string>>;
-    readonly editions: Readonly<Record<string, EditionComposition>>;
-    readonly dshRange: string;
-    readonly version: string;
+    readonly omittedPackages: Readonly<Record<string, string>>;
+    readonly editions: ReturnType<typeof readDistributionFacts>['editions'];
 };
 /**
  * Give the profile its own installed tree, built from the distribution's declarations.
@@ -124,9 +135,34 @@ export declare function readDistributionProfile(distributionDirectory: string):
  * twice; `dsh-plus apply` remains the command that reinstalls after a change.
  *
  * @param paths - resolved standalone paths.
- * @param consumerDirectory - directory whose `node_modules` holds the installation.
  */
-export declare function installProfilePackages(paths: StandalonePaths, consumerDirectory: string): void;
+export declare function installProfilePackages(paths: StandalonePaths, omitted?: ReadonlySet<string>, runtimeVersion?: string, registry?: string): void;
+/**
+ * Move the shared official services onto the runtime's exact version.
+ *
+ * The republished builds were cut against one runtime, and DSH disables a row when the exact
+ * peers a plugin declares disagree with the process it shares. Plugins declare those services as
+ * peers, so the names worth pinning are the peers actually installed -- read from the tree and
+ * checked against the registry. The rest of the official family keeps its resolved versions:
+ * pinning everything traded one mismatch for a tree with holes.
+ *
+ * @param profileDirectory - profile whose tree was just installed.
+ * @param runtimeVersion - exact runtime the profile boots.
+ * @param registry - registry the profile installs from.
+ * @returns how many services were realigned.
+ */
+export declare function alignOfficialVersions(profileDirectory: string, runtimeVersion: string, registry: string): number;
+/**
+ * Assert every bundle row the profile declares resolves in its installed tree.
+ *
+ * A row without an installed package mounts nothing and reports nothing: the client module
+ * system simply never registers it, and every earlier step passes. Reading the rows back from
+ * the manifest on disk rather than from the projection is what makes this cover the tree the
+ * launcher actually boots.
+ *
+ * @param profileDirectory - profile whose node_modules was just installed.
+ */
+export declare function assertProfileBundles(profileDirectory: string): void;
 /**
  * Make each replaced package declare the name of the location it occupies.
  *
@@ -143,7 +179,7 @@ export declare function installProfilePackages(paths: StandalonePaths, consumerD
  *
  * @param profileModules - the profile's \`node_modules\` directory.
  */
-export declare function alignReplacedPackageNames(profileModules: string): void;
+export declare function alignReplacedPackageNames(profileModules: string, omitted?: ReadonlySet<string>): void;
 /**
  * The registries to try, in order, for this machine.
  *
@@ -182,7 +218,7 @@ export declare function pnpmInstallCommands(): readonly string[];
  */
 export declare function pnpmInstallCommand(): string;
 /** Resolve every path a command needs, without creating anything. */
-export declare function resolvePaths(anchor: string, env?: NodeJS.ProcessEnv): StandalonePaths;
+export declare function resolvePaths(anchor: string, env?: NodeJS.ProcessEnv, editionId?: string): StandalonePaths;
 /**
  * Write the profile manifest when it is absent, leaving an existing one untouched.
  *
@@ -196,11 +232,12 @@ export declare function resolvePaths(anchor: string, env?: NodeJS.ProcessEnv): S
  * that installed them.
  *
  * @param paths - resolved standalone paths.
- * @param consumerDirectory - directory whose `node_modules` holds the installed packages.
- * @param edition - edition id whose package list to install, or undefined for the default.
+ * @param editionId - product edition to materialize.
+ * @param extraExcludes - packages the caller drops on top of the edition's own exclusions.
+ * @param dryRun - write the profile files without installing their dependency tree.
  * @returns whether this call created the manifest.
  */
-export declare function ensureProfile(paths: StandalonePaths, consumerDirectory: string, edition?: string): boolean;
+export declare function ensureProfile(paths: StandalonePaths, editionId?: string, extraExcludes?: readonly string[], dryRun?: boolean): boolean;
 /**
  * Apply the reviewed npm-target patches to the profile's installed packages.
  *