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

package/lib/types/profile.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Runtime paths and profile composition for a standalone Plus installation.
+ *
+ * A standalone consumer installs the distribution from the registry and owns its
+ * profile, so this module answers the two questions every command shares: where the
+ * DSH home and profile live, and what the profile manifest must contain. The bundle
+ * order comes from the installed distribution rather than from a copy here, because
+ * the launcher mounts exactly the bundles the profile names and nothing expands a
+ * bundle's own list.
+ */
+import { readDistributionFacts } from './manifest.ts';
+/** Profile name the launcher materializes when no edition is selected. */
+export declare const DEFAULT_PROFILE = "plus";
+/** 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. */
+    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;
+/**
+ * Whether one absolute path is the other or sits beneath it.
+ *
+ * A path outside the parent has a relative form starting with `..`, which every
+ * platform answers the same way. Comparing the text against a literal separator is
+ * not: Windows separates with a backslash, so a nested path never matched its own
+ * ancestor and every Windows installation reported the distribution as sitting
+ * outside its own tree.
+ *
+ * @param candidate - absolute path to test.
+ * @param parent - absolute path that may contain it.
+ * @param platform - separating convention, injectable so the Windows answer is
+ * testable where the suite runs on a POSIX host.
+ * @returns true when the candidate is the parent or inside it.
+ */
+export declare function isWithin(candidate: string, parent: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Resolve the installed distribution directory from one requiring anchor.
+ *
+ * The anchor must be a path inside the consumer's own tree. Resolving from this
+ * module instead would find the distribution the module itself was loaded from,
+ * which is the repository during development and the consumer's install otherwise.
+ *
+ * @param anchor - `package.json` path or directory in the consumer tree.
+ * @returns absolute path to the installed distribution.
+ */
+export declare function resolveDistributionDirectory(anchor: string): 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 omittedPackages: Readonly<Record<string, string>>;
+    readonly editions: ReturnType<typeof readDistributionFacts>['editions'];
+};
+/**
+ * Give the profile its own installed tree, built from the distribution's declarations.
+ *
+ * The launcher resolves a bundle from the profile directory, so the profile needs its
+ * own `node_modules`. Pointing it at the consumer's tree was cheaper, but it made the
+ * profile inherit whatever npm had already installed — including the official packages
+ * the distribution's `overrides` exist to replace. npm applies `overrides` only from a
+ * project's own root, so a profile without its own tree cannot receive them at all, and
+ * a patch delivered that way silently never arrives.
+ *
+ * Installing here makes the profile that root: pnpm reads `overrides` from the
+ * profile's own `pnpm-workspace.yaml`, which `writeProfileOverrides` writes before this
+ * runs. The install is skipped once the tree exists so a start does not pay for it
+ * twice; `dsh-plus apply` remains the command that reinstalls after a change.
+ *
+ * @param paths - resolved standalone paths.
+ */
+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.
+ *
+ * \`overrides\` installs our build at the official path, but the manifest inside still
+ * names our scope. The client module system resolves a loader entry's declared name and
+ * then requires the manifest it finds to declare that same name
+ * (\`client/modules\`: \`name === expectedPackageName\`); a mismatch makes the package own no
+ * browser module at all. The symptom is silent — the packages install, the server starts,
+ * and the panels those packages render simply never appear.
+ *
+ * The rewrite replaces the file rather than writing through it: pnpm hard-links a package
+ * manifest into its content-addressed store, so an in-place write would edit every
+ * profile sharing that store entry.
+ *
+ * @param profileModules - the profile's \`node_modules\` directory.
+ */
+export declare function alignReplacedPackageNames(profileModules: string, omitted?: ReadonlySet<string>): void;
+/**
+ * The registries to try, in order, for this machine.
+ *
+ * A mainland locale reaches the mirror faster than the origin, which is why the Desktop
+ * installer already prefers it there. The same choice belongs to the profile install: it
+ * fetches a full dependency closure, so the delay is the first thing a consumer notices.
+ * `DSH_PLUS_INSTALL_REGISTRY` overrides the choice, and a failure falls back once.
+ *
+ * @returns registries to try in order.
+ */
+export declare function registryOrder(): readonly string[];
+/**
+ * Report whether pnpm can run.
+ *
+ * The profile installs its own tree so its \`overrides\` apply, and only pnpm reads those
+ * from a workspace, so pnpm is a prerequisite the distribution cannot supply. Probing
+ * first turns a cryptic failure from the install into a message naming what is missing.
+ *
+ * @returns \`true\` when pnpm answers with a version.
+ */
+export declare function pnpmAvailable(): boolean;
+/**
+ * The commands that install pnpm, in the order worth trying.
+ *
+ * Corepack ships with Node and needs no download, so it comes first; npm is the fallback
+ * for an installation whose Corepack is absent or disabled. Both are the consumer's own
+ * toolchain, which is what lets the first start offer to install rather than only report.
+ *
+ * @returns commands to try in order, stopping at the first that works.
+ */
+export declare function pnpmInstallCommands(): readonly string[];
+/**
+ * The command to show a consumer who declines the automatic install.
+ *
+ * @returns the preferred command, which is the one the offer runs first.
+ */
+export declare function pnpmInstallCommand(): string;
+/** Resolve every path a command needs, without creating anything. */
+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.
+ *
+ * The distribution's own plugin dependencies are seeded here so the launcher can
+ * resolve every bundle from the profile directory: a bundle the profile cannot
+ * resolve fails activation with a module-resolution error, and no step in the
+ * launcher expands the distribution's bundle list on its own.
+ *
+ * The profile also links the consumer's installed packages, because the launcher
+ * resolves each bundle from the profile directory rather than from the directory
+ * that installed them.
+ *
+ * @param paths - resolved standalone paths.
+ * @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, editionId?: string, extraExcludes?: readonly string[], dryRun?: boolean): boolean;
+/**
+ * Apply the reviewed npm-target patches to the profile's installed packages.
+ *
+ * A standalone installation runs no `apply` step: it installs the distribution from
+ * the registry, links the consumer's packages, and starts. The npm patches a
+ * distribution declares therefore need an owner that does not require an official
+ * source checkout — the source half of the apply step needs one, this does not.
+ *
+ * The work is idempotent: a patch whose reverse already applies is left alone, so a
+ * second start neither re-applies nor fails. A reinstall restores the published bytes,
+ * which is why this runs on every start rather than once.
+ *
+ * @param distributionDirectory - the installed `@sparkelf/dsh-plus` directory.
+ * @param profileDirectory - the standalone profile directory.
+ * @returns the labels of the patches that were applied.
+ */
+export declare function applyProfileNpmPatches(distributionDirectory: string, profileDirectory: string): string[];
+//# sourceMappingURL=profile.d.ts.map