@chatcode/cco-market 1.45.1

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

@@ -0,0 +1,324 @@
+/**
+ * Process layer: re-invoking the ChatCode CLI launcher that started this host,
+ * spawning plugin commands with timeouts and live progress, and provisioning
+ * pnpm. This is the only module that starts child processes.
+ *
+ * Installs run through node:child_process, not ctx.shell: the shell service is
+ * the agent's sandboxed executor and denies writes to the profile directory.
+ */
+import type { ChildProcess } from 'node:child_process';
+import { type ProgressPhase } from './ndjson.ts';
+import { type Region } from './regions.ts';
+/**
+ * The real Node executable for spawning children. On Android the kernel runs
+ * node through the dynamic linker, so `process.execPath` is
+ * `/apex/.../linker64` — spawning IT with `--expose-internals` makes the
+ * linker treat the flag as the program path and die with
+ * `error: expected absolute path: "--expose-internals"`. `process.argv0`
+ * carries the real node binary; prefer it whenever it is an existing
+ * absolute path, and fall back to execPath everywhere else.
+ * @param argv0 - `process.argv0`, injectable for tests.
+ * @param execPath - `process.execPath`, injectable for tests.
+ */
+export declare function nodeExecutable(argv0?: string | undefined, execPath?: string): string;
+/**
+ * The directory holding the Node binary running this process. `npm`,
+ * `npm.cmd` and `corepack` are installed alongside it by every official Node
+ * distribution, so it is the one place the toolchain can be looked for
+ * without guessing — and unlike a PATH entry it cannot be absent, because
+ * this process is executing out of it.
+ *
+ * #167: a Windows desktop host spawned dsh without the Node install
+ * directory on PATH. Node itself was running (v24.18.1 in the log) while
+ * both `corepack` and `npm` came back "not recognized as an internal or
+ * external command", so the one-click setup had no way to succeed.
+ */
+export declare const nodeBinDir: string;
+/**
+ * Translate the machine's proxy environment into the ONE form pnpm reads.
+ *
+ * `HTTPS_PROXY` / `http_proxy` are what every other tool honours, and what
+ * `net.ts` already routes the market's own catalog fetches through — but
+ * pnpm ignores them completely. It reads npm config, so a proxy reaches it
+ * only as `npm_config_https_proxy` / `npm_config_proxy` (or an .npmrc entry,
+ * which is the user's file and not ours to rewrite).
+ *
+ * That gap is why the market could load its catalog through a proxy and
+ * then hang installing anything at all — reported four separate times
+ * (#148, #161, #188, #232), always from a network that needs one.
+ *
+ * An `npm_config_*` value the caller already set always wins: it is the more
+ * specific statement of intent, and on Windows env keys are case-insensitive
+ * so the check has to be too. NO_PROXY is forwarded verbatim because pnpm
+ * reads `npm_config_noproxy` and a host excluding its own registry mirror
+ * must keep excluding it.
+ */
+export declare function proxyEnvForPnpm(env?: NodeJS.ProcessEnv, region?: Region): NodeJS.ProcessEnv;
+/**
+ * Directories to append to PATH so a spawned pnpm can be found (#32, #38,
+ * #167, #292).
+ *
+ * A GUI or desktop launch inherits none of the shell profile, so PATH holds
+ * whatever the launcher had — usually not the directory the user's package
+ * manager lives in. The market appends the places it is actually installed
+ * to rather than telling the user to fix their environment.
+ *
+ * Windows used to get only the Node directory, which made the market's own
+ * advice unfollowable: the error it prints recommends installing pnpm with
+ * `iwr https://get.pnpm.io/install.ps1`, and then it did not look where that
+ * installer puts it (#292). Both Windows layouts are covered now — the
+ * standalone installer's `%LOCALAPPDATA%\pnpm`, and `%APPDATA%\npm` where
+ * `npm i -g pnpm` writes `pnpm.cmd`.
+ *
+ * `PNPM_HOME` comes first on every platform: the installer sets it, so it is
+ * the one answer that is right even when the layout is not the default one.
+ *
+ * @param platform - `process.platform`, injectable for tests.
+ * @param env - environment, for PNPM_HOME and the Windows app-data roots.
+ * @param home - home directory, injectable for tests.
+ */
+export declare function toolSearchDirs(platform?: string, env?: NodeJS.ProcessEnv, home?: string): string[];
+/**
+ * Windows npm/corepack/pnpm are `.cmd` shims. Node's `spawn` without a shell
+ * cannot start them (ENOENT / EINVAL). Same pattern as dsh's `plugin` forwarder.
+ */
+export declare const winCmdShim: boolean;
+/**
+ * Quote one argv token for a cmd.exe `/c` command line. cmd only groups with
+ * double quotes, so a token that needs quoting gets wrapped and embedded
+ * quotes are doubled.
+ */
+export declare function quoteCmdArg(arg: string): string;
+/**
+ * Build a cmd.exe command line from argv. Only the Windows shim path uses
+ * this: cmd re-parses the joined string, so every token is quoted before
+ * joining.
+ */
+export declare function cmdCommandLine(argv: readonly string[]): string;
+/**
+ * Whether a profile name can cross the rare Windows `dsh.cmd` fallback.
+ *
+ * cmd.exe expands percent-delimited environment variables even inside a
+ * quoted argument. Keep that fallback to names made only of letters, marks,
+ * numbers, spaces, dots, underscores, and hyphens. The normal direct-Node
+ * launcher remains argv-safe and accepts every DSH-valid profile name.
+ */
+export declare function isCmdSafeProfileName(profile: string): boolean;
+/**
+ * Argv re-invoking the CLI that launched this host process, so installs work
+ * whether ChatCode CLI runs from a global bin, a local install, or repo source
+ * (`node --import tsx/esm .../bin.ts`). Falls back to PATH `chatcode-cli`.
+ */
+export declare function dshArgv(): {
+    file: string;
+    args: string[];
+    cwd: string | undefined;
+    viaShell: boolean;
+};
+/** Outcome of one spawned plugin command. */
+export interface InstallResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    /** True when the run ended because the user cancelled it. */
+    cancelled: boolean;
+    /** Desktop's generation-wide package-operation gate rejected the start. */
+    busy?: boolean;
+    /** Package names pnpm reported as having ignored build scripts (ndjson). */
+    ignoredBuilds?: string[];
+    /**
+     * pnpm's OWN error message and code, from its structured ndjson stream
+     * (#244).
+     *
+     * Without this the only thing a failure could report was the tail of
+     * stderr — which for a market install is dsh's wrapper line, "pnpm failed
+     * in profile directory …", identical for every possible cause. pnpm's
+     * real error never went to stderr at all; it goes to the ndjson stdout
+     * this already parses for progress, and was being thrown away on the way
+     * out. Three separate reports (#244, #192, #138) are all "the UI shows a
+     * stack tail and nothing else".
+     */
+    pnpmError?: string;
+    pnpmErrorCode?: string;
+    /**
+     * Exact npm version this Desktop run actually handed to the host (#496).
+     *
+     * Anywhere Labs' install boundary rewrites a floating dist-tag (or bare
+     * name) to `name@x.y.z` with its own registry fetch. The update route
+     * normally pins that version itself before `add`, so this field matches
+     * the request and is unused for verification. It matters when registry
+     * metadata was unavailable and the add still carried `@latest`/`@beta`:
+     * verification then adopts this pin instead of leaving the expected
+     * version unset. When the route already sent an exact pin, callers must
+     * keep that pin authoritative and must not let this field lower it.
+     */
+    resolvedNpmVersion?: string;
+}
+/** The shape every orchestration function takes to run plugin commands (injectable in tests). */
+export type PluginRunner = (profile: string, pluginArgs: string[]) => Promise<InstallResult>;
+/** Package-operation boundary consumed by the HTTP route layer. */
+export interface PluginCommandRuntime {
+    runPlugin: PluginRunner;
+    probePnpm(): Promise<boolean>;
+    provisionPnpm(): Promise<{
+        ok: boolean;
+        hint?: string;
+    }>;
+    cancelActive(): boolean;
+    /** Whether this host can execute an immutable rollback add target. */
+    supportsExactRollbackTarget?(target: string): boolean;
+}
+/** One running package operation, however it was started. */
+export interface DesktopPnpmHandleLike {
+    readonly stdout: NodeJS.ReadableStream;
+    readonly stderr: NodeJS.ReadableStream;
+    readonly done: Promise<{
+        readonly exitCode: number | null;
+        readonly signal: NodeJS.Signals | null;
+    }>;
+    cancel(): void;
+}
+/**
+ * Structural subset of DSH Desktop's public `desktopPnpm` contract.
+ *
+ * Anywhere Labs' DSH Desktop is ONE third-party client among several, and
+ * this interface exists only for it. Nothing here is part of the official
+ * DSH protocol — `desktopPnpm`, `installPlugin` and the install boundary
+ * below appear nowhere in `@deepseek-ai/*`. Every other client the market
+ * runs under, including other desktop apps, installs through the ordinary
+ * `dsh plugin --profile <p> add` CLI, and so does the market itself when
+ * none of these services are present.
+ *
+ * That is why every member past `runPlugin` is optional and reached by
+ * feature detection. A host that does not publish one simply never enters
+ * the branch, and the ordinary path it already used stays untouched — the
+ * cost of accommodating one vendor must not be paid by the others, or by
+ * the far larger number of people on plain `dsh web`.
+ */
+export interface DesktopPnpmLike {
+    runPlugin(args: readonly string[], invokingDir: string, signal?: AbortSignal): DesktopPnpmHandleLike;
+    /**
+     * Desktop 2.x refuses `add` through `runPlugin` — "plugin add must use the
+     * recoverable install boundary" (#215, #219, #272) — and offers this
+     * instead, which their launcher enables only for the selected market
+     * provider. Same arguments, same handle, no recovery receipt and no
+     * write-ahead log for the caller to reconcile.
+     *
+     * Optional because it is theirs: absent on every other host, including
+     * the other third-party desktop client in #292, which installs perfectly
+     * well through the ordinary CLI.
+     *
+     * Read from their published source rather than assumed: it accepts ONLY
+     * `add` with exactly one target of the form `name@exact.version`
+     * (`validateExternalMarketInstallArgs` in dsh-plugin-desktop/src/pnpm.ts).
+     * A `github:owner/repo` target is rejected before any process starts, so
+     * the 1085 catalog entries with no npm package — 57% of it — cannot be
+     * installed on that host by any spelling this market could send. That is
+     * a gap in their contract, not something to work around here.
+     */
+    runExternalMarketPluginInstall?(args: readonly string[], invokingDir: string, signal?: AbortSignal): DesktopPnpmHandleLike;
+}
+/** Desktop runtime also owns cleanup of any operation started by this fiber. */
+export interface DesktopPluginRuntime extends PluginCommandRuntime {
+    dispose(): Promise<void>;
+}
+/**
+ * Kill a spawned child and, on Windows, its whole process tree — `kill()`
+ * there only terminates the wrapper, leaving pnpm children running.
+ * (Contributed in #7 by @mraing.)
+ */
+export declare function killChild(child: ChildProcess): void;
+/**
+ * Cancel the plugin command currently running.
+ * @returns true when there was one to cancel.
+ */
+export declare function cancelActive(): boolean;
+/** Why `pnpm --version` last failed, or null when it has not failed. */
+export declare function lastPnpmProbeFailure(): {
+    kind: 'missing' | 'failed';
+    output: string;
+} | null;
+/** Probe `pnpm --version` on PATH. */
+export declare function probePnpm(): Promise<boolean>;
+/**
+ * Provision pnpm without user involvement: corepack (ships with Node) first,
+ * a global npm install as fallback.
+ * @returns true when `pnpm --version` succeeds afterwards.
+ */
+export declare function provisionPnpm(): Promise<{
+    ok: boolean;
+    hint?: string;
+}>;
+/**
+ * Whether a bare command name resolves to a file on the PATH the market
+ * hands its children.
+ *
+ * The market cannot read the reason a spawn failed out of the child's
+ * message: cmd.exe reports a missing command in the console's ANSI codepage
+ * ("'npm' 不是内部或外部命令" on a Chinese Windows), which is neither the
+ * string `ENOENT` nor even valid UTF-8 — so the #32 hint, written against
+ * Node's own ENOENT wording, could never fire on Windows and the user was
+ * left with no guidance at all (#167). Looking on disk answers the same
+ * question in every locale.
+ */
+export declare function toolOnPath(name: string): boolean;
+/**
+ * Why the one-click pnpm setup failed, in terms the user can act on.
+ *
+ * Every one of these was a real report where the market said only "自动准备
+ * 没成功" while the log held the actual cause: EEXIST (#142 — corepack had
+ * already placed a pnpm shim, so `npm -g` refused to overwrite it), EPERM
+ * (#108 — Node installed somewhere the user cannot write), ENOENT (#32 —
+ * a GUI launch with no Node on PATH at all).
+ * @returns a bilingual, actionable hint, or undefined when unrecognized.
+ */
+export declare function provisionHint(corepackOutput: string, npmOutput: string, npmFound?: boolean, probeFailure?: {
+    kind: 'missing' | 'failed';
+    output: string;
+} | null): string | undefined;
+/** Live progress of the running plugin command, for the status route. */
+export interface InstallProgress {
+    active: boolean;
+    target: string;
+    startedAt: number;
+    lastLine: string;
+    /** Parsed from pnpm's ndjson stage events; null when none arrived. */
+    phase: ProgressPhase;
+    /** Distinct packages resolved/fetched so far. */
+    done: number;
+    total: number | null;
+    currentPackage: string | null;
+    downloaded: number | null;
+    size: number | null;
+    /** True when structured ndjson progress has been observed. */
+    ndjson: boolean;
+    /** Last fatal error from the stream (only meaningful after a failure). */
+    error: string | null;
+    /** True from the moment the user asks to cancel until the run ends. */
+    cancelling: boolean;
+}
+/** Singleton progress state; the status route reads it, runDshPlugin writes it. */
+export declare const progress: InstallProgress;
+/** Identifies this host process; the client scopes its pending-restart flags to it. */
+export declare const BOOT_ID: string;
+/**
+ * Central allowlist for every spawn target, regardless of which route built
+ * it (defense in depth on top of per-route validation — the win32 bare-dsh
+ * fallback runs through a shell). Suggested in #16 by @anupamme.
+ *
+ * `^`, `~` and `=` are intentionally allowed: restore/install flows turn
+ * manifest specs such as "dsh-better-sidebar": "^0.14.0" into targets like
+ * `dsh-better-sidebar@^0.14.0`, and regex-valid semver ranges must not be
+ * mistaken for shell injection (whitespace and shell metacharacters remain
+ * rejected — the win32 bare-dsh fallback is the reason to keep them out).
+ */
+export declare const TARGET_RE: RegExp;
+/** Run one `chatcode-cli plugin --profile <p> …` command with timeout and progress tracking. */
+export declare function runDshPlugin(profile: string, pluginArgs: string[]): Promise<InstallResult>;
+/**
+ * Adapt DSH Desktop's generation-scoped package manager to the existing
+ * market runner. There is no runtime import or dependency on Desktop: the
+ * Host supplies this public service only when the package is mounted there.
+ */
+export declare function createDesktopPluginRuntime(service: DesktopPnpmLike, activeProfileDir: string, invokingDir?: string, timeoutMs?: number): DesktopPluginRuntime;

package/lib/types/dsh-install.d.ts

@@ -0,0 +1,46 @@
+/** Locate the DSH host package in CLI and packaged Desktop runtimes. */
+/**
+ * The version of the DSH host this market is running inside.
+ *
+ * Read from the same manifest `findDshInstallDir` already parses to identify
+ * the package — the version was sitting in that object and being discarded.
+ *
+ * Worth reporting because the host version has repeatedly been the thing
+ * neither side could see. #293 turned on it (the reporter was on
+ * 0.1.1-rc.2 while every attempt to reproduce had been on 0.1.0-rc.8, which
+ * nobody knew until three rounds in), and #404 is entirely about a plugin
+ * that requires a host newer than the Desktop build it was installed on.
+ *
+ * The directory comes back too, because WHERE it was found is the other half
+ * of the answer: a path under Electron's resources is a Desktop-bundled host,
+ * which #139 established can be older than whatever `npm ls` would report.
+ * Asking the user is not a substitute — that is the number they do not have.
+ * @returns the host version and the directory it was read from, or null when
+ * no host package is locatable (a plain `dsh web` from a global install can
+ * legitimately land here).
+ */
+export declare function dshHostInfo(entry?: string): {
+    version: string;
+    directory: string;
+} | null;
+/**
+ * Walk up from the CLI entry first, then inspect Electron's authoritative
+ * resources directory. Desktop distributions may keep node_modules outside
+ * the ASAR, expose them through ASAR's virtual filesystem, or disable ASAR.
+ *
+ * The entry is resolved through symlinks before the walk, because for a
+ * globally installed dsh it IS one. `npm i -g` and Homebrew both put a link
+ * in a `bin/` directory pointing at the real package, so `process.argv[1]`
+ * is `/opt/homebrew/bin/dsh` and walking up from there reaches `/` without
+ * ever passing the package. Measured: the same call answers `null` for the
+ * link and the correct directory for its target.
+ *
+ * That was not a cosmetic gap. Everything downstream reads the host version
+ * from here — the exported log's `dsh host:` line (#426), Discover's
+ * host-requirement column and filter (#473), and the pre-update check
+ * (#404) — and a null version makes every one of them answer "unknown",
+ * silently, on exactly the ordinary global install. A bundled Desktop host
+ * is reached by the resources branch below and was never affected, which is
+ * why this survived: the case that worked is the one that gets tested.
+ */
+export declare function findDshInstallDir(entry?: string): string | null;

package/lib/types/gist.d.ts

@@ -0,0 +1,53 @@
+import { type ProfileBackup } from './backup.ts';
+/** The single file every dshmarket backup Gist carries. */
+export declare const GIST_FILENAME = "dsh-profile-backup.json";
+/** GitHub hard limit for one Gist file (1 MB); enforced before upload. */
+export declare const GIST_MAX_BYTES: number;
+/** Environment variable for a host-configured token (never read from disk). */
+export declare const GIST_TOKEN_ENV = "CHATCODE_CLI_MARKET_GITHUB_TOKEN";
+export declare const LEGACY_GIST_TOKEN_ENV = "DSH_GITHUB_TOKEN";
+/** Machine-readable error codes the client maps to localized messages. */
+export type GistErrorCode = 'auth' | 'notfound' | 'rate-limit' | 'invalid' | 'timeout' | 'network' | 'other';
+/** Error with a code for the UI; the message stays human-readable. */
+export declare class GistError extends Error {
+    readonly code: GistErrorCode;
+    constructor(message: string, code?: GistErrorCode);
+}
+/** Classify any thrown value into a stable GistErrorCode. */
+export declare function gistErrorCode(error: unknown): GistErrorCode;
+export interface GistRef {
+    id: string;
+    htmlUrl: string;
+}
+/** Where the token used for a request came from (shown in the UI). */
+export type GistTokenSource = 'token' | 'env' | 'gh';
+/**
+ * Normalize a Gist id or a gist.github.com URL to a bare id.
+ * Anything else (paths, embedded slashes, oversize input) is rejected.
+ */
+export declare function parseGistId(input: string): string;
+/**
+ * Resolve the token for one request, in order of preference:
+ * 1. an explicitly supplied token (session memory only);
+ * 2. the host-configured CHATCODE_CLI_MARKET_GITHUB_TOKEN environment variable;
+ * 3. an already-logged-in GitHub CLI (`gh auth token`) — the token is used
+ *    for this request only and never written to disk.
+ */
+export declare function resolveGistTokenSource(bodyToken: unknown): Promise<{
+    token: string;
+    source: GistTokenSource;
+}>;
+/** Resolve just the token (kept for callers that do not need the source). */
+export declare function resolveGistToken(bodyToken: unknown): Promise<string>;
+/** Test hook: drop the gh token cache between tests. */
+export declare function resetGhTokenCache(): void;
+/** Create a new private Gist carrying one backup file. */
+export declare function createGist(token: string, content: string, signal?: AbortSignal): Promise<GistRef>;
+/** Overwrite the backup file inside an existing Gist (other files kept). */
+export declare function updateGist(token: string, gistId: string, content: string, signal?: AbortSignal): Promise<GistRef>;
+/** Download and strictly validate the backup file inside a Gist. */
+export declare function readGist(token: string, gistId: string, signal?: AbortSignal): Promise<ProfileBackup>;
+/** Confirm the token is usable (GET /user). */
+export declare function verifyGistToken(token: string, signal?: AbortSignal): Promise<void>;
+/** True when the serialized backup fits inside a Gist file. */
+export declare function fitsGistLimit(content: string): boolean;

package/lib/types/groups.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Custom plugin groups (Roadmap #60): user-defined named collections of
+ * installed plugins whose enable/disable state can be switched as a unit —
+ * borrowing the "group by capability, toggle as one" idea from Claude
+ * Desktop's skill management. Membership lives in state.json and is the
+ * only durable truth: a group's switch state is always derived from its
+ * members and never persisted itself.
+ *
+ * Pure CRUD over the caller-owned state objects; routes.ts persists after
+ * each mutation and applies the live toggles for the batch action.
+ */
+export type GroupAction = 'create' | 'rename' | 'delete' | 'set-members' | 'toggle';
+/** The slices of market state group CRUD touches (routes.ts owns the rest). */
+export interface GroupState {
+    groups: Record<string, string[]>;
+    groupOrder: string[];
+}
+export interface GroupMutationResult {
+    ok: boolean;
+    error?: string;
+}
+export declare function createGroup(state: GroupState, name: unknown): GroupMutationResult;
+export declare function renameGroup(state: GroupState, name: unknown, newName: unknown): GroupMutationResult;
+export declare function deleteGroup(state: GroupState, name: unknown): GroupMutationResult;
+/**
+ * Replace a group's membership. Only currently installed plugins can be
+ * members — ghost names (uninstalled meanwhile) are dropped and duplicates
+ * collapse, so the persisted list stays clean. Themes are exclusive: a group
+ * may hold at most one theme plugin, mirroring the global one-active-theme
+ * rule (only one theme can be enabled at a time).
+ */
+export declare function setGroupMembers(state: GroupState, name: unknown, members: unknown, installed: ReadonlySet<string>, themes: ReadonlySet<string>): GroupMutationResult;
+/** Drop `name` from every group (called after a successful uninstall). */
+export declare function removeFromGroups(state: GroupState, name: string): void;

package/lib/types/home-paths.d.ts

@@ -0,0 +1,16 @@
+/** ChatCode CLI Home resolution with legacy Harness input compatibility. */
+/** Default single-root ChatCode CLI home. */
+export declare function defaultChatCodeHome(): string;
+/** @deprecated Compatibility alias for downstream code. */
+export declare const defaultDshHome: typeof defaultChatCodeHome;
+/** Expand the tilde forms supported by ChatCode CLI configuration. */
+export declare function expandHomePath(path: string): string;
+/**
+ * Resolve an explicit home, `CHATCODE_CLI_HOME`, legacy `DSH_HOME`, or the
+ * default to one normalized absolute path. Blank environment values are unset.
+ */
+export declare function resolveChatCodeHome(configured?: string, env?: Record<string, string | undefined>): string;
+/** @deprecated Compatibility alias for callers that still import the old API. */
+export declare const resolveDshHome: typeof resolveChatCodeHome;
+/** Read a non-empty ChatCode variable before its legacy compatibility input. */
+export declare function compatibilityEnv(env: Record<string, string | undefined>, currentName: string, legacyName: string): string | undefined;