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

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

@@ -0,0 +1,139 @@
+/**
+ * The optional capabilities a Plus installation can enable, and the interview that
+ * decides which ones to set up.
+ *
+ * A standalone installation works without any of them: the agent runs, the shell
+ * runs, and files are read and written. Each entry here adds a capability whose
+ * backing service lives outside npm — a search provider that needs a key, a PDF
+ * parser that needs a local server, an Office toolchain that needs a runtime — so
+ * the choice is offered once, at install time, rather than left to a user who has
+ * no way to know what the deployment is missing.
+ *
+ * Every capability is selected by default. A user who wants the plain harness
+ * deselects them; a user who accepts the defaults ends up with a deployment whose
+ * features work, which is the state the interactive question exists to reach.
+ *
+ * Enabling a capability has to mean the feature works, so each entry carries both
+ * halves of that: the profile row that mounts it and the service it needs. A
+ * capability that only asked a question and then dropped the answer would report
+ * success while the deployment stayed exactly as it was.
+ *
+ * @module @sparkelf/dsh-plus/standalone-capabilities
+ */
+/** One optional capability a deployment can enable. */
+export interface Capability {
+    /** Stable key used on the command line and in the profile. */
+    readonly id: string;
+    /** One-line name shown in the interview. */
+    readonly title: string;
+    /** What the deployment gains, shown beside the name. */
+    readonly detail: string;
+    /** Whether the backing service needs an address the user must supply. */
+    readonly needsEndpoint: boolean;
+}
+/** Capabilities offered at install time, in interview order. */
+export declare const CAPABILITIES: readonly Capability[];
+/** The answers one interview produced. */
+export interface CapabilityAnswers {
+    /** Capability ids the user kept selected. */
+    readonly enabled: readonly string[];
+    /** Exa API key when web search was enabled and the user supplied one. */
+    readonly exaApiKey?: string;
+    /** MinerU endpoint to write; defaults to the local service this command starts. */
+    readonly mineruEndpoint?: string;
+}
+/** Where this command starts MinerU when the capability is enabled. */
+export declare const DEFAULT_MINERU_ENDPOINT = "http://127.0.0.1:8000/file_parse";
+/** File under the deployment home recording which capabilities were enabled. */
+export declare const CAPABILITY_RECORD = "capabilities.json";
+/** Deployment env file the launcher reads as its `user-env` layer. */
+export declare const CAPABILITY_ENV_FILE = ".env";
+/** Comment that identifies a profile layer this interview wrote. */
+export declare const CAPABILITY_MARKER = "Written by dsh-plus start from the capability interview.";
+/**
+ * Interview the user about the optional capabilities.
+ *
+ * Each is offered on its own line and defaults to enabled, so pressing Enter
+ * through the interview produces a deployment whose features work. The answers are
+ * returned rather than applied, so a caller can report what it will do before it
+ * touches the profile.
+ *
+ * @param interactive - when false, every capability is enabled without asking.
+ * @returns the ids to enable and the values the enabled ones need.
+ */
+export declare function interviewCapabilities(interactive: boolean): Promise<CapabilityAnswers>;
+/**
+ * The deployment env file, with one assignment per enabled capability that reaches
+ * its service through the launch environment.
+ *
+ * Exa reads its key from the launch environment, so a capability the user selected is enabled here
+ * as well as in the profile layer. Only the names this interview owns are rewritten: a
+ * deployment that keeps its own assignments in the same file keeps them, and
+ * deselecting a capability removes the assignment that turned it on.
+ *
+ * @param answers - the interview's answers.
+ * @param existing - the file's current text, when it already exists.
+ * @returns the environment file's text.
+ */
+export declare function capabilityEnvironment(answers: CapabilityAnswers, existing?: string): string;
+export declare function capabilityPatchLayer(answers: CapabilityAnswers, existing?: string): string;
+/**
+ * The capability record a previous configured run wrote, or `undefined` when none exists.
+ *
+ * The record is what lets a later run report the deployment's answers instead of asking
+ * again. A malformed or unreadable file is treated as absent rather than fatal: it is a
+ * convenience cache, and refusing to boot over it would strand a deployment whose record
+ * was corrupted by an interrupted write.
+ *
+ * @param home - the deployment home holding the record.
+ * @returns the enabled ids, and the MinerU endpoint when the record carries one.
+ */
+export declare function readCapabilityRecord(home: string): CapabilityAnswers | undefined;
+/**
+ * The capabilities a deployment actually has mounted, read from the files the loader and
+ * the launch environment consume.
+ *
+ * A record is a cache of an earlier answer and can drift from the deployment — a profile
+ * layer edited by hand, a record deleted, a plugin removed from the distribution. What a
+ * capability is *doing* is decided by the profile patch rows and the env file, so that is
+ * what a report reads.
+ *
+ * @param profilePatchText - the profile layer's YAML text.
+ * @param envText - the deployment env file's text.
+ * @returns the ids found in the profile layer and the env names present.
+ */
+export declare function detectEnabledCapabilities(profilePatchText: string, envText: string): {
+    readonly mounted: readonly string[];
+    readonly env: readonly string[];
+};
+/**
+ * One capability's effect, added to or removed from an existing profile layer without
+ * disturbing the rest of the file.
+ *
+ * `dsh-plus start` owns the whole layer and rewrites it from the interview's answers, which
+ * is correct for an install that answered once and never edits afterwards. A deployment
+ * that maintains its own rows in that same layer cannot be served that way: replacing the
+ * file drops every row the operator wrote. This edits the rows this module owns and leaves
+ * every other entry, comment, and blank line exactly where it was.
+ *
+ * @param existing - the layer's current YAML text.
+ * @param id - the capability to add or remove.
+ * @param enable - whether to add the capability.
+ * @param mineruEndpoint - the endpoint to write when enabling MinerU.
+ * @returns the layer's new text.
+ */
+export declare function editCapabilityPatchLayer(existing: string, id: string, enable: boolean, mineruEndpoint?: string): string;
+/**
+ * Install and start the backing services the selected capabilities need.
+ *
+ * Enabling a capability means the deployment expects its service to answer, so the
+ * command that offers the choice is also the command that provides it. Each step
+ * reports what it is doing and, on failure, the command a user can run by hand —
+ * a missing runtime is a fact about the host, not a reason to abandon the install.
+ *
+ * @param answers - the interview's answers.
+ * @param home - the deployment home, where generated service units are recorded.
+ * @returns the ids whose service is ready.
+ */
+export declare function installCapabilityServices(answers: CapabilityAnswers, home: string): Promise<readonly string[]>;
+//# sourceMappingURL=standalone-capabilities.d.ts.map