dsh-pstack 0.2.0-beta.3 → 0.2.1

package/dist/role-config-a4JpVdc-.mjs

@@ -0,0 +1,379 @@
+import { i as findRoleSpec, n as PSTACK_MODELS_FILENAME, o as normalizeRoleName, r as ROLE_MANIFEST, t as INHERIT_PARENT_ALIASES } from "./role-manifest-79cnFfDM.mjs";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+// src/internal/role-grammar.ts
+function frontmatterBodyStart(lines) {
+	if (lines[0]?.trim() !== "---") return 0;
+	for (let index = 1; index < lines.length; index += 1) if (lines[index]?.trim() === "---") return index + 1;
+	return 0;
+}
+/** One line grammar for role parsing and byte-preserving updates. */
+function scanRoleDocument(text) {
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	const bodyStart = frontmatterBodyStart(lines);
+	const scanned = [];
+	let offset = 0;
+	for (let index = 0; index < lines.length; index += 1) {
+		const rawLine = lines[index];
+		const line = index + 1 - bodyStart;
+		const contentEnd = offset + rawLine.length - (rawLine.endsWith("\r") ? 1 : 0);
+		if (index < bodyStart) {
+			scanned.push({
+				kind: "blank",
+				line
+			});
+			offset += rawLine.length + 1;
+			continue;
+		}
+		const trimmed = rawLine.trim();
+		if (trimmed === "") scanned.push({
+			kind: "blank",
+			line
+		});
+		else if (trimmed.startsWith("#")) {
+			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
+			scanned.push({
+				kind: "comment",
+				line,
+				...match === null ? {} : { budget: match[1].trim() }
+			});
+		} else {
+			const separator = trimmed.indexOf(":");
+			if (separator === -1) scanned.push({
+				kind: "malformed",
+				line,
+				rawLine: trimmed
+			});
+			else {
+				const rawKey = trimmed.slice(0, separator).trim();
+				const key = normalizeRoleName(rawKey);
+				const spec = findRoleSpec(key);
+				if (key === "") scanned.push({
+					kind: "malformed",
+					line,
+					rawLine: ""
+				});
+				else if (spec === void 0) scanned.push({
+					kind: "unknown-role",
+					line,
+					rawKey
+				});
+				else {
+					const valueText = rawLine.slice(0, contentEnd - offset);
+					const sourceSeparator = valueText.indexOf(":");
+					const afterSeparator = valueText.slice(sourceSeparator + 1);
+					const rawValue = afterSeparator.trim();
+					const valueLeading = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimStart().length;
+					const valueTrailing = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimEnd().length;
+					const valueStart = offset + sourceSeparator + 1 + valueLeading;
+					const valueEnd = contentEnd - valueTrailing;
+					scanned.push({
+						kind: "role",
+						line,
+						rawKey,
+						key,
+						rawValue,
+						spec,
+						valueStart,
+						valueEnd
+					});
+				}
+			}
+		}
+		offset += rawLine.length + 1;
+	}
+	return { lines: scanned };
+}
+/** Replace only the winning role's value, retaining every other source byte. */
+function updateRoleDocument(text, spec, value) {
+	const winning = scanRoleDocument(text).lines.findLast((line) => line.kind === "role" && line.key === spec.key);
+	if (winning?.kind === "role") return `${text.slice(0, winning.valueStart)}${value}${text.slice(winning.valueEnd)}`;
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	return `${text}${text === "" || text.endsWith("\n") ? "" : eol}${spec.key}: ${value}${eol}`;
+}
+// src/internal/role-config.ts
+/**
+* The pstack role configuration: `$DSH_HOME/pstack-models.mdc`.
+*
+* `pstack_subagent` reads this file again on every delegation, so a change reaches the
+* next child and never a child that already started.
+*
+* Three states stay apart because each needs a different fix: the file is missing (no
+* policy, so every role inherits the parent route), unreadable (a broken install, never
+* treated as "no configuration"), or loaded with per-line issues reported by line.
+*/
+/** Absolute path of the role file for one DSH home. */
+function modelsFilePath(dshHome) {
+	return join(dshHome, PSTACK_MODELS_FILENAME);
+}
+/** Resolve `$DSH_HOME` the way the Host does: the environment when set, else `~/.dsh`. */
+function resolveDshHome(env = process.env, home = homedir()) {
+	const configured = env["DSH_HOME"];
+	const path = configured !== void 0 && configured.trim() !== "" ? configured : join(home, ".dsh");
+	const expanded = path === "~" ? home : path.startsWith("~/") || path.startsWith("~\\") ? join(home, path.slice(2)) : path;
+	return resolve(expanded);
+}
+/** Read the role file. Never throws for a missing or unreadable file. */
+function readRoleConfiguration(path) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		if (isMissingFile(error)) return {
+			status: "missing",
+			path
+		};
+		return {
+			status: "unreadable",
+			path,
+			reason: describeError(error)
+		};
+	}
+	return parseRoleConfiguration(text, path);
+}
+/** Parse role-file text. Pure: no file system access. */
+function parseRoleConfiguration(text, path) {
+	const issues = [];
+	const roles = /* @__PURE__ */ new Map();
+	let budget;
+	for (const scanned of scanRoleDocument(text).lines) {
+		const { line } = scanned;
+		if (scanned.kind === "blank") continue;
+		if (scanned.kind === "comment") {
+			if (scanned.budget !== void 0) budget = scanned.budget;
+			continue;
+		}
+		if (scanned.kind === "malformed") {
+			issues.push({
+				line,
+				message: scanned.rawLine === "" ? "the role key is empty" : `expected \`<role>: <value>\`, found ${JSON.stringify(scanned.rawLine)}`
+			});
+			continue;
+		}
+		if (scanned.kind === "unknown-role") {
+			issues.push({
+				line,
+				message: unknownRoleMessage(scanned.rawKey, normalizeRoleName(scanned.rawKey))
+			});
+			continue;
+		}
+		const { rawKey, spec } = scanned;
+		const parsed = parseRouteValue(scanned.rawValue);
+		const entryIssues = [...parsed.issues];
+		if (spec.shape === "single" && parsed.routes.length > 1) entryIssues.push("a single-route role cannot hold a comma-separated list");
+		for (const issue of entryIssues) issues.push({
+			line,
+			message: `${rawKey}: ${issue}`
+		});
+		if (parsed.routes.length === 0) continue;
+		const previous = roles.get(spec.key);
+		if (previous !== void 0) issues.push({
+			line,
+			message: `role "${spec.key}" is already configured on line ${previous.line}; line ${line} wins`
+		});
+		roles.set(spec.key, {
+			line,
+			rawKey,
+			key: spec.key,
+			spec,
+			routes: parsed.routes,
+			issues: entryIssues
+		});
+	}
+	return budget === void 0 ? {
+		status: "loaded",
+		path,
+		roles,
+		issues
+	} : {
+		status: "loaded",
+		path,
+		budget,
+		roles,
+		issues
+	};
+}
+/** Parse a role value: one route, or a comma-separated list of routes. */
+function parseRouteValue(raw) {
+	const routes = [];
+	const issues = [];
+	const segments = raw.split(",");
+	segments.forEach((segment, index) => {
+		const trimmed = segment.trim();
+		if (trimmed === "") {
+			if (index !== segments.length - 1) issues.push(`entry ${index + 1} of the list is empty`);
+			return;
+		}
+		const parsed = parseRoute(trimmed);
+		if (parsed.route === void 0) {
+			issues.push(parsed.issue);
+			return;
+		}
+		routes.push(parsed.route);
+	});
+	if (routes.length === 0 && issues.length === 0) issues.push("the value is empty; use `inherit-parent`, `auto`, or `<provider>/<model> [effort]`");
+	return {
+		routes,
+		issues
+	};
+}
+/** Parse one entry of a role value. */
+function parseRoute(raw) {
+	const value = raw.trim();
+	if (value === "") return { issue: "the value is empty" };
+	const alias = value.toLowerCase();
+	if (INHERIT_PARENT_ALIASES.includes(alias)) return { route: {
+		kind: "inherit",
+		alias
+	} };
+	const match = /^([^\s/,[]+)\/([^\s/,[\]]+(?:\/[^\s/,[\]]+)*)(?:\s+\[([^[\]]*)\])?$/.exec(value);
+	if (match === null) return { issue: `${JSON.stringify(value)} is not a route; use \`inherit-parent\`, \`auto\`, or \`<provider>/<model> [effort]\`` };
+	const provider = match[1];
+	const model = match[2];
+	const effort = match[3];
+	if (effort === void 0) return { route: {
+		kind: "route",
+		provider,
+		model
+	} };
+	const trimmedEffort = effort.trim();
+	if (trimmedEffort === "") return { issue: `${JSON.stringify(value)} has empty brackets; write \`<provider>/<model> [effort]\` or drop the brackets` };
+	if (/\s/.test(trimmedEffort)) return { issue: `${JSON.stringify(value)} has a multi-word effort; an effort is one adapter-owned token` };
+	return { route: {
+		kind: "route",
+		provider,
+		model,
+		effort: trimmedEffort
+	} };
+}
+/** Raised when a role's configured list cannot be selected from. */
+var RouteSelectionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RouteSelectionError";
+	}
+};
+/**
+* Expand one role into the routes this call starts.
+*
+* Automatic panels start one child per entry. Another list role selects one entry, the
+* first by default; `roleIndex` chooses which. A single role holds exactly one route and
+* rejects `roleIndex`.
+*/
+function selectRoleRoutes(spec, entry, roleIndex) {
+	if (spec.shape === "single" && roleIndex !== void 0) throw new RouteSelectionError(`role "${spec.key}" holds a single route, so \`roleIndex\` does not apply; drop \`roleIndex\` or use a list-valued role (${listRoleKeys().join(", ")})`);
+	if (spec.autoPanel && roleIndex !== void 0) throw new RouteSelectionError(`role "${spec.key}" is an automatic panel: it starts one child per entry, so \`roleIndex\` does not apply`);
+	if (entry === void 0) return {
+		role: spec,
+		mode: spec.autoPanel ? "panel" : "single",
+		configured: false,
+		routes: [{ kind: "inherit" }],
+		total: 1
+	};
+	if (entry.issues.length > 0) throw new RouteSelectionError(`role "${spec.key}" has invalid configuration on line ${entry.line}: ${entry.issues.join("; ")}. Fix the role file before delegating.`);
+	if (spec.autoPanel) return {
+		role: spec,
+		mode: "panel",
+		configured: true,
+		routes: entry.routes,
+		total: entry.routes.length
+	};
+	if (spec.shape === "list") {
+		const index = roleIndex ?? 0;
+		if (index >= entry.routes.length) throw new RouteSelectionError(`role "${spec.key}" has ${entry.routes.length} entr${entry.routes.length === 1 ? "y" : "ies"}, so \`roleIndex\` ${index} is out of range; valid indexes are ${entry.routes.map((_route, position) => position).join(", ")}`);
+		return {
+			role: spec,
+			mode: "selected",
+			configured: true,
+			routes: [entry.routes[index]],
+			total: entry.routes.length,
+			roleIndex: index
+		};
+	}
+	return {
+		role: spec,
+		mode: "single",
+		configured: true,
+		routes: [entry.routes[0]],
+		total: entry.routes.length
+	};
+}
+/** Keys of the list-valued roles, including the automatic panels. */
+function listRoleKeys() {
+	return ROLE_MANIFEST.filter((role) => role.shape === "list").map((role) => role.key);
+}
+/** Raised when a role name does not match the manifest. */
+var RoleNameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RoleNameError";
+	}
+};
+/** Resolve a role name, or throw a diagnostic that names the near misses. */
+function requireRole(raw) {
+	const spec = findRoleSpec(normalizeRoleName(raw));
+	if (spec !== void 0) return spec;
+	const suggestions = suggestRoles(raw);
+	const hint = suggestions.length === 0 ? "No role key is close to it." : `Closest role keys: ${suggestions.map((key) => `"${key}"`).join(", ")}.`;
+	throw new RoleNameError(`unknown pstack role ${JSON.stringify(raw)}. ${hint} Role names come from the role manifest, not from free text: pass the exact key, or omit \`role\` to inherit the parent route.`);
+}
+function suggestRoles(raw, limit = 3) {
+	const target = normalizeRoleName(raw);
+	if (target === "") return [];
+	return ROLE_MANIFEST.map((role) => {
+		const shared = sharedTokenCount(target, role.key);
+		const distance = editDistance(target, role.key);
+		const contains = role.key.includes(target) || target.includes(role.key);
+		const score = (contains ? 1e3 : 0) + shared * 100 - distance + Math.min(role.key.length, target.length);
+		return {
+			key: role.key,
+			score,
+			distance,
+			shared,
+			contains
+		};
+	}).filter((candidate) => candidate.contains || candidate.shared > 0 || candidate.distance <= 4).sort((left, right) => right.score - left.score).slice(0, limit).map((candidate) => candidate.key);
+}
+function unknownRoleMessage(rawKey, key) {
+	const suggestions = suggestRoles(key);
+	const hint = suggestions.length === 0 ? "no role key is close to it" : `closest role keys: ${suggestions.map((candidate) => `"${candidate}"`).join(", ")}`;
+	return `unknown role ${JSON.stringify(rawKey)} (${hint}). A line for a retired or misspelled role is reported rather than ignored.`;
+}
+function sharedTokenCount(left, right) {
+	const rightTokens = new Set(tokenize(right));
+	return [...new Set(tokenize(left))].filter((token) => rightTokens.has(token)).length;
+}
+function tokenize(value) {
+	return value.split(/[^a-z0-9]+/).filter((token) => token !== "");
+}
+/** Levenshtein distance, iterative with one row of state. */
+function editDistance(left, right) {
+	if (left === right) return 0;
+	if (left === "") return right.length;
+	if (right === "") return left.length;
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let row = 1; row <= left.length; row += 1) {
+		const current = [row];
+		for (let column = 1; column <= right.length; column += 1) {
+			const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
+			const deletion = previous[column] + 1;
+			const insertion = current[column - 1] + 1;
+			current.push(Math.min(substitution, deletion, insertion));
+		}
+		previous = current;
+	}
+	return previous[right.length];
+}
+function isMissingFile(error) {
+	return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function describeError(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		return typeof code === "string" ? `${code}: ${error.message}` : error.message;
+	}
+	return String(error);
+}
+export { selectRoleRoutes as a, resolveDshHome as i, readRoleConfiguration as n, updateRoleDocument as o, requireRole as r, modelsFilePath as t };

package/dist/role-manifest-79cnFfDM.mjs

@@ -0,0 +1,112 @@
+// src/internal/role-manifest.ts
+/**
+* File name the role configuration lives under inside `$DSH_HOME`.
+*
+* It keeps the upstream name `pstack-models.mdc`, so a reader moving from the Cursor docs
+* recognizes it, but stores it directly under `$DSH_HOME`; DSH does not load `.mdc` files
+* on its own, and `pstack_subagent` is the only reader.
+*/
+const PSTACK_MODELS_FILENAME = "pstack-models.mdc";
+/** Values that resolve to "send no `agentOptions` and inherit the parent route". */
+const INHERIT_PARENT_ALIASES = ["inherit-parent", "auto"];
+/** The 17 roles, in manifest order. */
+const ROLE_MANIFEST = [
+	{
+		key: "feature, refactoring",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "bug-fix",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "perf-issue",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hillclimb",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "judgment and prose",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "hardest tasks",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explorer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "how explainer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why investigators",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "why synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect tooling",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "reflect judgment, divergent, synthesizer",
+		shape: "single",
+		autoPanel: false
+	},
+	{
+		key: "arena runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "arena cross-judge pool",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "swarm workers",
+		shape: "list",
+		autoPanel: false
+	},
+	{
+		key: "architect runners",
+		shape: "list",
+		autoPanel: true
+	},
+	{
+		key: "interrogate reviewers",
+		shape: "list",
+		autoPanel: true
+	}
+];
+function isRoleKey(value) {
+	return ROLE_MANIFEST.some((role) => role.key === value);
+}
+/** Normalize formatting while keeping commas that belong to a role name. */
+function normalizeRoleName(raw) {
+	return raw.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").replace(/:+$/, "").trim();
+}
+/** Exact manifest lookup. Callers normalize the key first. */
+function findRoleSpec(key) {
+	if (!isRoleKey(key)) return void 0;
+	return ROLE_MANIFEST.find((role) => role.key === key);
+}
+export { isRoleKey as a, findRoleSpec as i, PSTACK_MODELS_FILENAME as n, normalizeRoleName as o, ROLE_MANIFEST as r, INHERIT_PARENT_ALIASES as t };

package/dist/role-manifest-8OERX9-s.d.mts

@@ -0,0 +1,90 @@
+/**
+ * The one pstack role manifest.
+ *
+ * Keys are matched exactly after normalization, and commas belong to some keys
+ * (`feature, refactoring`, `reflect judgment, divergent, synthesizer`), so nothing here
+ * may split a key on a comma. A second literal role list anywhere is a bug.
+ *
+ * This module has no Node imports: the bundle imports it directly.
+ */
+/** Whether a role holds one route or a comma-separated list of routes. */
+type RoleValueShape = "single" | "list";
+interface RoleSpec {
+  /** Exact key as written in the role file. Commas belong to the key. */
+  readonly key: string;
+  readonly shape: RoleValueShape;
+  /** A list role that starts one child per entry automatically. */
+  readonly autoPanel: boolean;
+}
+/** The 17 roles, in manifest order. */
+declare const ROLE_MANIFEST: readonly [{
+  readonly key: "feature, refactoring";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "bug-fix";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "perf-issue";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "hillclimb";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "judgment and prose";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "hardest tasks";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "how explorer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "how explainer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "why investigators";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "why synthesizer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "reflect tooling";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "reflect judgment, divergent, synthesizer";
+  readonly shape: "single";
+  readonly autoPanel: false;
+}, {
+  readonly key: "arena runners";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}, {
+  readonly key: "arena cross-judge pool";
+  readonly shape: "list";
+  readonly autoPanel: false;
+}, {
+  readonly key: "swarm workers";
+  readonly shape: "list";
+  readonly autoPanel: false;
+}, {
+  readonly key: "architect runners";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}, {
+  readonly key: "interrogate reviewers";
+  readonly shape: "list";
+  readonly autoPanel: true;
+}];
+type RoleKey = (typeof ROLE_MANIFEST)[number]["key"];
+export { RoleSpec as n, RoleValueShape as r, RoleKey as t };

package/dist/role-wire-CAJsVA6e.d.mts

@@ -0,0 +1,54 @@
+import { r as RoleValueShape, t as RoleKey } from "./role-manifest-8OERX9-s.mjs";
+/** Which spelling of "inherit the parent route" a role line uses. */
+type InheritAlias = "inherit-parent" | "auto";
+/** One role value as the configuration page sees it. */
+type RouteView = {
+  readonly kind: "inherit";
+  readonly alias: InheritAlias;
+} | {
+  readonly kind: "route";
+  readonly provider: string;
+  readonly model: string;
+  readonly effort?: string;
+};
+/** One of the 17 roles in manifest order. */
+interface RoleView {
+  readonly key: RoleKey;
+  readonly shape: RoleValueShape;
+  /** Whether the role file configures this role. */
+  readonly configured: boolean;
+  /** The winning line, when the role file configures this role. */
+  readonly line?: number;
+  readonly routes: readonly RouteView[];
+  readonly issues: readonly string[];
+}
+/** One file-level problem. Unknown and malformed lines are reported, never dropped. */
+interface RoleFileIssue {
+  readonly line?: number;
+  readonly message: string;
+}
+/** Everything the configuration page renders about `$DSH_HOME/pstack-models.mdc`. */
+interface RoleFileSnapshot {
+  readonly path: string;
+  readonly status: "missing" | "loaded" | "unreadable";
+  readonly reason?: string;
+  readonly budget?: string;
+  readonly roles: readonly RoleView[];
+  readonly issues: readonly RoleFileIssue[];
+  /** False only when the file cannot be read at all. */
+  readonly canSave: boolean;
+}
+/** One role save. List roles carry every route, never only the edited one. */
+interface SaveRoleRequest {
+  readonly key: string;
+  readonly routes: readonly RouteView[];
+}
+/** A refused save leaves the file untouched and names the reason. */
+type SaveRoleResult = {
+  readonly ok: true;
+  readonly snapshot: RoleFileSnapshot;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+export { SaveRoleRequest as n, SaveRoleResult as r, RoleFileSnapshot as t };

package/dist/roles.d.mts

@@ -0,0 +1,18 @@
+import { CatalogueResult } from "./models.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-CAJsVA6e.mjs";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+/** Read and write the role file for the Plugins configuration page. */
+export declare class PstackRolesService extends TypertRemoteService {
+  static inject: string[];
+  constructor(ctx: Context);
+  protected [Service.init](): void;
+  /** Current path, status, values, and per-line issues. */
+  status(): RoleFileSnapshot;
+  /** The live directory the page offers for its provider/model/effort selects. */
+  catalogue(signal: AbortSignal): Promise<CatalogueResult>;
+  /** Validate and save one role, then return the reloaded snapshot. */
+  save(request: SaveRoleRequest, signal: AbortSignal): Promise<SaveRoleResult>;
+  private get llm();
+}
+export { PstackRolesService as default };