@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/core/interactiveProfile.js

@@ -0,0 +1,143 @@
+import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileSecretStore } from "../accounts/secrets.js";
+const fail = () => { throw new Error('Invalid interactive profile configuration.'); };
+const object = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return fail();
+    return value;
+};
+const keys = (value, expected) => {
+    if (Object.keys(value).length !== expected.length || expected.some(key => !Object.hasOwn(value, key)))
+        fail();
+};
+const absolute = (value) => {
+    if (typeof value !== 'string' || value.length > 4096 || value.includes('\0') || !isAbsolute(value))
+        return fail();
+    return value;
+};
+const identifier = (value) => {
+    if (typeof value !== 'string' || value.length > 128 || !/^[A-Za-z0-9_-]+$/.test(value))
+        return fail();
+    return value;
+};
+/** Strict, bounded, credential-free configuration. Unknown fields are errors, not ignored secrets. */
+export function validateInteractiveProfile(value) {
+    const record = object(value);
+    keys(record, ['version', 'dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend']);
+    if (record.version !== 1)
+        return fail();
+    const backend = object(record.secretBackend);
+    let secretBackend;
+    if (backend.kind === 'file') {
+        keys(backend, ['kind', 'path']);
+        secretBackend = { kind: 'file', path: absolute(backend.path) };
+    }
+    else if (backend.kind === 'host') {
+        keys(backend, ['kind', 'id']);
+        secretBackend = { kind: 'host', id: identifier(backend.id) };
+    }
+    else
+        return fail();
+    return {
+        version: 1,
+        dataRoot: absolute(record.dataRoot),
+        stateDir: absolute(record.stateDir),
+        defaultVariantScope: identifier(record.defaultVariantScope),
+        secretBackend
+    };
+}
+export function interactiveProfilePath(home = homedir()) {
+    return join(absolute(home), '.xingular-harness', 'profile.json');
+}
+function selectedConfigPath(location = {}) {
+    return location.configPath === undefined ? interactiveProfilePath(location.home) : absolute(location.configPath);
+}
+/** Read only. Missing is legacy mode; malformed or inaccessible is never silently ignored. */
+export function readInteractiveProfile(location = {}) {
+    const path = selectedConfigPath(location);
+    try {
+        const info = statSync(path);
+        if (!info.isFile() || info.size > 16_384)
+            return fail();
+        return validateInteractiveProfile(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        // Do not include JSON contents, paths, or backend details in diagnostics.
+        throw new Error('Interactive profile could not be read or validated.');
+    }
+}
+function overrides(value) {
+    if (value === undefined)
+        return {};
+    const record = object(value);
+    if (Object.keys(record).some(key => !['dataRoot', 'stateDir', 'defaultVariantScope', 'secretBackend'].includes(key)))
+        return fail();
+    return record;
+}
+/** Explicit roots > selected profile > caller's legacy defaults. Never creates roots or merges data. */
+export function resolveInteractiveProfile(options = {}) {
+    const home = absolute(options.home ?? homedir());
+    const root = join(home, '.xingular-harness');
+    const selected = readInteractiveProfile(options);
+    const legacy = overrides(options.legacyDefaults);
+    const explicit = overrides(options.overrides);
+    const dataRoot = explicit.dataRoot ?? selected?.dataRoot ?? legacy.dataRoot ?? join(root, 'data');
+    const stateDir = explicit.stateDir ?? selected?.stateDir ?? legacy.stateDir ?? join(root, 'state');
+    const defaultVariantScope = explicit.defaultVariantScope ?? selected?.defaultVariantScope ?? legacy.defaultVariantScope ?? 'default';
+    const secretBackend = explicit.secretBackend ?? selected?.secretBackend ?? legacy.secretBackend ?? {
+        kind: 'file',
+        path: join(stateDir, 'secrets.json')
+    };
+    return validateInteractiveProfile({ version: 1, dataRoot, stateDir, defaultVariantScope, secretBackend });
+}
+/**
+ * Explicit adoption only. Creates the profile file, never roots or credentials; it never replaces
+ * an existing profile or merges data. A pre-profile host must supply its selected backend in
+ * `legacyDefaults` so an absent profile cannot silently downgrade it to the file store.
+ */
+export function adoptInteractiveProfile(profile, location = {}) {
+    const validated = validateInteractiveProfile(profile);
+    const path = selectedConfigPath(location);
+    const folder = dirname(path);
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    const temporary = join(folder, `.profile-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, `${JSON.stringify(validated, null, 2)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        linkSync(temporary, path);
+    }
+    catch {
+        throw new Error('Interactive profile adoption failed; existing configuration was not replaced.');
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Every participating process must map this host id to the same credential store. The account
+ * lock serializes access but cannot unify distinct native Keychain identities; no file fallback is
+ * allowed when a selected host adapter is unavailable.
+ */
+export async function interactiveProfileSecretStore(profile, host) {
+    const { secretBackend } = validateInteractiveProfile(profile);
+    if (secretBackend.kind === 'file')
+        return fileSecretStore(secretBackend.path);
+    if (!host)
+        throw new Error('The selected credential backend is unavailable; supply its host SecretStore adapter.');
+    const store = await host(secretBackend);
+    if (!store || !['get', 'set', 'delete'].every(key => typeof store[key] === 'function')) {
+        throw new Error('The selected credential backend did not provide a SecretStore.');
+    }
+    return store;
+}

package/dist/sdk/core/links.d.ts

@@ -0,0 +1,51 @@
+/** What a link names, before anything touches the filesystem. */
+export type LinkTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'path';
+    path: string;
+};
+/** What the operating system is asked to open, after the file it names was checked. */
+export type OpenedTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'directory';
+    path: string;
+};
+/** Hands an opened target to the operating system. Replaced in tests, and by a host that has its own opener. */
+export type LinkOpener = (target: OpenedTarget) => Promise<void>;
+export interface LinkOpenCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export declare function linkTarget(raw: string | null | undefined, options?: {
+    base?: string | null;
+}): LinkTarget | null;
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export declare function openableTarget(target: LinkTarget): OpenedTarget;
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export declare function linkOpenCommand(target: OpenedTarget, platform?: NodeJS.Platform): LinkOpenCommand;
+/** The default opener: the operating system's own handler for this kind of target. */
+export declare function openWithSystem(target: OpenedTarget): Promise<void>;
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export declare function openLink(target: LinkTarget, opener?: LinkOpener): Promise<OpenedTarget>;
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export declare function openLinkTarget(raw: string, options?: {
+    base?: string | null;
+    opener?: LinkOpener;
+}): Promise<OpenedTarget>;

package/dist/sdk/core/links.js

@@ -0,0 +1,155 @@
+// What a link points at, and the one door that hands it to the operating system. Both front ends
+// classify with `linkTarget` and open through `openLink`, so a destination one surface accepts is
+// the destination the other accepts.
+import { spawn } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { HarnessError } from "./errors.js";
+const MAX_LENGTH = 4096;
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/u;
+const WEB_ADDRESS = /^https?:/iu;
+const MAIL_ADDRESS = /^mailto:/iu;
+const FILE_ADDRESS = /^file:/iu;
+const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+const LINE_SUFFIX = /:\d+(?::\d+)?$/u;
+/** A folder the system would launch or install rather than show. */
+const BUNDLE = /\.(?:app|appex|bundle|framework|kext|plugin|prefpane|workflow|xpc)$/iu;
+/** A document whose default application runs it, so a click would execute rather than open. */
+const LAUNCHABLE = /\.(?:action|appimage|bat|cmd|command|desktop|dmg|exe|jar|lnk|mpkg|osax|pkg|ps1|scpt|sh|terminal|tool|url|vb|vbs|webloc|workflow)$/iu;
+const unopenable = (message) => new HarnessError('link_not_openable', message, 'Open the file from the project instead.');
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export function linkTarget(raw, options = {}) {
+    const value = raw?.trim();
+    if (!value || value.length > MAX_LENGTH || CONTROL_CHARACTERS.test(value) || value.startsWith('#'))
+        return null;
+    if (WEB_ADDRESS.test(value)) {
+        try {
+            const url = new URL(value);
+            if ((url.protocol !== 'http:' && url.protocol !== 'https:') || !url.hostname || url.username || url.password)
+                return null;
+            return { kind: 'web', url: url.href };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (MAIL_ADDRESS.test(value)) {
+        const address = value.slice('mailto:'.length).split('?')[0].trim();
+        return address && address.includes('@') && !/\s/u.test(address) ? { kind: 'mail', address } : null;
+    }
+    const path = filePath(value, options.base);
+    return path ? { kind: 'path', path } : null;
+}
+function filePath(value, base) {
+    let raw = value;
+    if (FILE_ADDRESS.test(raw)) {
+        try {
+            const url = new URL(raw);
+            if (url.hostname && url.hostname !== 'localhost')
+                return null;
+            raw = url.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    const address = raw.split('#')[0].split('?')[0].replace(LINE_SUFFIX, '');
+    let decoded;
+    try {
+        decoded = decodeURIComponent(address);
+    }
+    catch {
+        return null;
+    }
+    if (!decoded || decoded.includes('\0') || decoded.startsWith('~') || decoded.startsWith('//'))
+        return null;
+    if (isAbsolute(decoded))
+        return decoded;
+    if (SCHEME.test(decoded))
+        return null;
+    if (!base || !isAbsolute(base))
+        return null;
+    return resolve(base, decoded);
+}
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export function openableTarget(target) {
+    if (target.kind !== 'path')
+        return target;
+    let stats = statsOf(target.path);
+    let path = target.path;
+    if (stats.isSymbolicLink()) {
+        try {
+            path = realpathSync(target.path);
+        }
+        catch {
+            throw unopenable('That link points at a file that is not there.');
+        }
+        stats = statsOf(path);
+    }
+    if (stats.isDirectory()) {
+        if (BUNDLE.test(path))
+            throw unopenable('That link points at an application, not a document.');
+        return { kind: 'directory', path };
+    }
+    if (!stats.isFile())
+        throw unopenable('That link does not point at a file or a folder.');
+    if (LAUNCHABLE.test(path))
+        throw unopenable('That kind of file runs when it is opened, so a link cannot open it.');
+    if ((stats.mode & 0o111) !== 0)
+        throw unopenable('That file is executable, so a link cannot open it.');
+    return { kind: 'file', path };
+}
+function statsOf(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        throw unopenable('That link points at a file that is not there.');
+    }
+}
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export function linkOpenCommand(target, platform = process.platform) {
+    const address = target.kind === 'web' ? target.url : target.kind === 'mail' ? `mailto:${target.address}` : target.path;
+    if (platform === 'darwin')
+        return { command: 'open', args: [address] };
+    if (platform === 'win32')
+        return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', address] };
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd')
+        return { command: 'xdg-open', args: [address] };
+    throw unopenable(`Opening links is not supported on ${platform}.`);
+}
+/** The default opener: the operating system's own handler for this kind of target. */
+export async function openWithSystem(target) {
+    const { command, args } = linkOpenCommand(target);
+    await new Promise((done, fail) => {
+        let child;
+        try {
+            child = spawn(command, args, { detached: process.platform !== 'win32', stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        child.once('error', fail);
+        child.once('spawn', () => {
+            child.unref();
+            done();
+        });
+    });
+}
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export async function openLink(target, opener = openWithSystem) {
+    const opened = openableTarget(target);
+    await opener(opened);
+    return opened;
+}
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export async function openLinkTarget(raw, options = {}) {
+    const target = linkTarget(raw, { base: options.base });
+    if (!target)
+        throw unopenable('This link cannot be opened here.');
+    return openLink(target, options.opener);
+}

package/dist/sdk/core/path.d.ts

@@ -0,0 +1,7 @@
+export declare function searchPath(): string;
+/** The inherited PATH key, preserving Windows' existing capitalization. */
+export declare function pathVariableName(environment: NodeJS.ProcessEnv): string;
+/** A child environment with a directory prepended using the selected platform's PATH rules. */
+export declare function prependSearchPath(directory: string, existing: string, environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Record<string, string>;
+/** The executable `name` resolves to: itself when absolute, else the first match on the search path. */
+export declare function findBinary(name: string): string | null;

package/dist/sdk/core/path.js

@@ -0,0 +1,79 @@
+// Where executables are found. POSIX desktop apps may start with a minimal PATH, so the login
+// shell's PATH is resolved once. Windows keeps the inherited PATH and its native separator.
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, extname, isAbsolute, join } from 'node:path';
+let resolved = null;
+export function searchPath() {
+    const platform = process.platform;
+    const pathKey = pathVariableName(process.env);
+    const inherited = process.env[pathKey] ?? '';
+    if (resolved?.platform === platform && resolved.inherited === inherited)
+        return resolved.path;
+    const separator = pathSeparator(platform);
+    const entries = [];
+    if (platform !== 'win32') {
+        try {
+            const output = execFileSync(process.env.SHELL || '/bin/zsh', ['-ilc', 'printf %s "$PATH"'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+            // Interactive shells may print banners; the PATH is the last line.
+            entries.push(...(output.split('\n').filter(Boolean).at(-1) ?? '').split(separator));
+        }
+        catch {
+            // The inherited PATH and the usual folders still apply.
+        }
+    }
+    entries.push(...inherited.split(separator));
+    if (platform !== 'win32') {
+        const home = homedir();
+        if (home)
+            entries.push(...['.local/bin', '.bun/bin', '.npm-global/bin', '.cargo/bin'].map((folder) => join(home, folder)));
+        entries.push('/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin');
+    }
+    const path = [...new Set(entries.filter(Boolean))].join(separator);
+    resolved = { platform, inherited, path };
+    return path;
+}
+/** The inherited PATH key, preserving Windows' existing capitalization. */
+export function pathVariableName(environment) {
+    return Object.keys(environment).find((name) => name.toLowerCase() === 'path') ?? 'PATH';
+}
+/** A child environment with a directory prepended using the selected platform's PATH rules. */
+export function prependSearchPath(directory, existing, environment = process.env, platform = process.platform) {
+    const values = [directory, existing].filter(Boolean);
+    return { [pathVariableName(environment)]: values.join(pathSeparator(platform)) };
+}
+function pathSeparator(platform) {
+    return platform === 'win32' ? ';' : delimiter;
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The executable `name` resolves to: itself when absolute, else the first match on the search path. */
+export function findBinary(name) {
+    const platform = process.platform;
+    const suffixes = platform === 'win32' && !extname(name)
+        ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+        : [];
+    const names = [name, ...suffixes.map((suffix) => `${name}${suffix}`)];
+    if (isAbsolute(name)) {
+        for (const candidate of names)
+            if (isExecutable(candidate))
+                return candidate;
+        return null;
+    }
+    for (const directory of searchPath().split(pathSeparator(platform))) {
+        for (const candidateName of names) {
+            const candidate = join(directory, candidateName);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}

package/dist/sdk/core/projects.d.ts

@@ -0,0 +1,18 @@
+export interface Project {
+    id: string;
+    name: string;
+    rootPath: string;
+    isGitRepository: boolean;
+    autoMaintenance: boolean;
+    createdAt: string;
+    slug: string;
+    /** `/projects/<slug>`: where this project's pages live in the Wiki. */
+    wikiNamespace: string;
+}
+/** Same rule as the Wiki's page slugs, kept here so `core` does not depend on `memory`. */
+export declare function slugify(text: string): string;
+export declare function uniqueSlug(name: string, taken: readonly string[]): string;
+export declare function listProjects(root: string): Project[];
+/** `listProjects` for callers that treat an unreadable registry like an empty one. */
+export declare function projectsOrNone(root: string): Project[];
+export declare function findProject(root: string, projectId: string): Project;

package/dist/sdk/core/projects.js

@@ -0,0 +1,67 @@
+// Projects: named working folders, each with a Wiki namespace (`/projects/<slug>`). The harness
+// reads `<data root>/projects.json`; the embedding application adds, renames, and removes them.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { notFound } from "./errors.js";
+import { readJson } from "./fs.js";
+import { newId } from "./fs.js";
+/** Same rule as the Wiki's page slugs, kept here so `core` does not depend on `memory`. */
+export function slugify(text) {
+    let value = '';
+    for (const character of text.toLowerCase()) {
+        if (/^[a-z0-9]$/.test(character))
+            value += character;
+        else if (value && !value.endsWith('-'))
+            value += '-';
+    }
+    value = value.replace(/^-+|-+$/g, '').slice(0, 60);
+    return value || `page-${newId().slice(0, 8)}`;
+}
+export function uniqueSlug(name, taken) {
+    const slug = slugify(name);
+    const base = slug.startsWith('page-') ? 'project' : slug;
+    let candidate = base;
+    for (let counter = 2; taken.includes(candidate); counter += 1)
+        candidate = `${base}-${counter}`;
+    return candidate;
+}
+function load(root) {
+    const records = readJson(join(root, 'projects.json')) ?? [];
+    // Records without a slug get a unique one derived from the name, in list order, so the result
+    // is the same on every read until the application persists it.
+    const taken = records.map((record) => record.slug ?? '').filter(Boolean);
+    for (const record of records) {
+        if (record.slug)
+            continue;
+        record.slug = uniqueSlug(record.name, taken);
+        taken.push(record.slug);
+    }
+    return records;
+}
+export function listProjects(root) {
+    return load(root).map((record) => ({
+        id: record.id,
+        name: record.name,
+        rootPath: record.rootPath,
+        isGitRepository: existsSync(join(record.rootPath, '.git')),
+        autoMaintenance: record.autoMaintenance,
+        createdAt: record.createdAt,
+        slug: record.slug,
+        wikiNamespace: `/projects/${record.slug}`
+    }));
+}
+/** `listProjects` for callers that treat an unreadable registry like an empty one. */
+export function projectsOrNone(root) {
+    try {
+        return listProjects(root);
+    }
+    catch {
+        return [];
+    }
+}
+export function findProject(root, projectId) {
+    const project = listProjects(root).find((entry) => entry.id === projectId);
+    if (!project)
+        throw notFound('Project');
+    return project;
+}

package/dist/sdk/core/secrets.d.ts

@@ -0,0 +1,2 @@
+/** Text that carries a credential marker is never written to the Wiki. */
+export declare function looksSecret(text: string): boolean;

package/dist/sdk/core/secrets.js

@@ -0,0 +1,5 @@
+const SECRET_MARKERS = ['-----BEGIN', 'sk-ant-', 'sk-proj-', 'ghp_', 'github_pat_', 'AKIA', 'xoxb-'];
+/** Text that carries a credential marker is never written to the Wiki. */
+export function looksSecret(text) {
+    return SECRET_MARKERS.some((marker) => text.includes(marker));
+}

package/dist/sdk/core/shell.d.ts

@@ -0,0 +1,20 @@
+export type ShellKind = 'bash' | 'powershell';
+export interface Shell {
+    kind: ShellKind;
+    executable: string;
+    /** Arguments placed before the command text. */
+    args: readonly string[];
+}
+export interface ShellLookup {
+    env?: NodeJS.ProcessEnv;
+    /** Whether a file exists at an absolute path. */
+    exists?: (path: string) => boolean;
+    /** The first match for an executable name on the search path. */
+    onPath?: (name: string) => string | null;
+}
+/** The shell for this machine, resolved once. Null when none was found. */
+export declare function hostShell(): Shell | null;
+export declare function resolveShell(platform: NodeJS.Platform, lookup?: ShellLookup): Shell | null;
+/** The full argument list that runs `command` in `shell`. */
+export declare function shellArguments(shell: Shell, command: string): string[];
+export declare function shellLabel(shell: Shell): string;

package/dist/sdk/core/shell.js

@@ -0,0 +1,73 @@
+// The shell the Bash tool runs commands in. POSIX systems use Bash. Windows uses Git Bash when it
+// is installed and PowerShell otherwise, so a fresh machine can run commands with nothing extra.
+import { accessSync, constants, statSync } from 'node:fs';
+import { win32 } from 'node:path';
+import { findBinary } from "./path.js";
+const POWERSHELL_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command'];
+// Windows PowerShell writes the console code page by default; ask for UTF-8 like Pi does.
+const POWERSHELL_UTF8 = 'try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n';
+let cached;
+/** The shell for this machine, resolved once. Null when none was found. */
+export function hostShell() {
+    if (cached === undefined)
+        cached = resolveShell(process.platform);
+    return cached;
+}
+export function resolveShell(platform, lookup = {}) {
+    const env = lookup.env ?? process.env;
+    const exists = lookup.exists ?? isFile;
+    const onPath = lookup.onPath ?? findBinary;
+    if (platform !== 'win32') {
+        const executable = ['/bin/bash', '/usr/bin/bash'].find((candidate) => exists(candidate));
+        return executable ? { kind: 'bash', executable, args: ['-c'] } : null;
+    }
+    const gitBash = [env.ProgramFiles, env['ProgramFiles(x86)']]
+        .filter((folder) => Boolean(folder))
+        .map((folder) => win32.join(folder, 'Git', 'bin', 'bash.exe'))
+        .find((candidate) => exists(candidate));
+    if (gitBash)
+        return { kind: 'bash', executable: gitBash, args: ['-c'] };
+    const bashOnPath = onPath('bash.exe');
+    if (bashOnPath && !isWslLauncher(bashOnPath, env))
+        return { kind: 'bash', executable: bashOnPath, args: ['-c'] };
+    const existing = (folder, ...parts) => {
+        if (!folder)
+            return null;
+        const candidate = win32.join(folder, ...parts);
+        return exists(candidate) ? candidate : null;
+    };
+    // PowerShell 7 first; Windows PowerShell ships with every supported Windows version.
+    const powershell = onPath('pwsh.exe')
+        ?? existing(env.ProgramFiles, 'PowerShell', '7', 'pwsh.exe')
+        ?? onPath('powershell.exe')
+        ?? existing(env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+    return powershell ? { kind: 'powershell', executable: powershell, args: POWERSHELL_ARGS } : null;
+}
+/** The full argument list that runs `command` in `shell`. */
+export function shellArguments(shell, command) {
+    return [...shell.args, shell.kind === 'powershell' ? `${POWERSHELL_UTF8}${command}` : command];
+}
+export function shellLabel(shell) {
+    if (shell.kind === 'powershell')
+        return 'PowerShell';
+    return /\\git\\/iu.test(shell.executable) ? 'Git Bash' : 'Bash';
+}
+// System32\bash.exe starts WSL, a separate Linux system that does not see Windows paths the same
+// way and needs its command on stdin. It is not a usable Bash for this tool.
+function isWslLauncher(path, env) {
+    const normalized = win32.normalize(path).toLowerCase();
+    const systemRoot = env.SystemRoot;
+    if (systemRoot) {
+        return ['System32', 'Sysnative'].some((folder) => normalized === win32.join(systemRoot, folder, 'bash.exe').toLowerCase());
+    }
+    return /^[a-z]:\\windows\\(?:system32|sysnative)\\bash\.exe$/u.test(normalized);
+}
+function isFile(path) {
+    try {
+        accessSync(path, constants.F_OK);
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sdk/core/text.d.ts

@@ -0,0 +1,7 @@
+export declare function charCount(text: string): number;
+export declare function takeChars(text: string, count: number): string;
+/** Lines without their terminators; a final newline does not add an empty last line. */
+export declare function lines(text: string): string[];
+/** Orders file paths segment by segment, so a folder sorts before a sibling whose name extends it. */
+export declare function comparePaths(left: string, right: string): number;
+export declare const compareText: (left: string, right: string) => number;