@yankeguo/dsh-command-devlead 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Y.-K. Guo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.js

@@ -0,0 +1,352 @@
+// Built by dsh-devlead. Do not edit.
+
+// packages/command/src/index.ts
+import { CommandDefinitionId } from "@deepseek-ai/dsh-commands/brand";
+import { isDevLeadError } from "@yankeguo/dsh-devlead";
+import { DEVLEAD_COMMAND_NAME as DEVLEAD_COMMAND_NAME2 } from "@yankeguo/dsh-devlead-protocol";
+
+// packages/command/src/parse.ts
+import { DEVLEAD_COMMAND_NAME } from "@yankeguo/dsh-devlead-protocol";
+var COMMAND_GRAMMAR = "[status|on|off|watch <session>|unwatch <session>]";
+var USAGE = `Usage: /${DEVLEAD_COMMAND_NAME} ${COMMAND_GRAMMAR}`;
+function invalid(message) {
+  return { kind: "invalid", message };
+}
+function splitHead(input) {
+  const match = /^(\S+)(?:\s+([\s\S]*))?$/u.exec(input);
+  if (match === null) return { head: input.toLowerCase(), rest: "" };
+  return { head: match[1].toLowerCase(), rest: (match[2] ?? "").trim() };
+}
+function unquote(text) {
+  const trimmed = text.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  const pair = first === '"' && last === '"' || first === "'" && last === "'";
+  return pair ? trimmed.slice(1, -1).trim() : trimmed;
+}
+function unexpectedArgument(subcommand) {
+  return invalid(`The /devlead ${subcommand} subcommand does not take an argument.`);
+}
+function parseSessionArgument(subcommand, text) {
+  const session = unquote(text);
+  if (session.length === 0) {
+    return invalid(
+      `/devlead ${subcommand} requires a Session id or a unique id prefix. Run /devlead to inspect the current watch set.`
+    );
+  }
+  if (/\s/u.test(session)) {
+    return invalid(
+      `"/devlead ${subcommand}" takes one Session reference without spaces; pass the full Session id or a unique id prefix.`
+    );
+  }
+  return { kind: subcommand, session };
+}
+function parseDevLeadCommand(rawInput) {
+  const trimmed = rawInput.trim();
+  const complete = /^\/devlead[/\s]*/iu.exec(trimmed);
+  const input = (complete === null ? trimmed : trimmed.slice(complete[0].length)).trim();
+  if (input.length === 0) return { kind: "status" };
+  switch (input.toLowerCase()) {
+    case "status":
+      return { kind: "status" };
+    case "on":
+      return { kind: "on" };
+    case "off":
+      return { kind: "off" };
+    default:
+      break;
+  }
+  const { head, rest } = splitHead(input);
+  switch (head) {
+    case "watch":
+      return parseSessionArgument("watch", rest);
+    case "unwatch":
+      return parseSessionArgument("unwatch", rest);
+    // A no-argument subcommand followed by stray text is a typo, not a
+    // Session reference; name the offending subcommand instead of guessing.
+    case "status":
+    case "on":
+    case "off":
+      return unexpectedArgument(head);
+    default:
+      return invalid(`Unknown /devlead subcommand "${head}".`);
+  }
+}
+
+// packages/command/src/render.ts
+import {
+  formatInstant,
+  notificationLine,
+  transitionLabel
+} from "@yankeguo/dsh-devlead-protocol";
+var RECENT_NOTIFICATION_LIMIT = 5;
+var HELP_LINE = "Help: /devlead on | /devlead off | /devlead watch <session> | /devlead unwatch <session>";
+function modeLabel(enabled) {
+  return enabled ? "on" : "off";
+}
+function sessionLabel(view) {
+  const title = view.title?.trim() ?? "";
+  return title.length === 0 ? view.sessionId : `${title} (${view.sessionId})`;
+}
+function sessionStateLabel(view) {
+  const state = view.archived ? "archived" : view.running ? "running" : view.live ? "idle" : "cold";
+  const parts = [state];
+  if (view.running && (view.pendingInputs ?? 0) > 0) parts.push(`${view.pendingInputs} queued`);
+  if (view.lastTurn !== void 0) {
+    const outcome = view.lastTransition === void 0 ? "" : ` ${transitionLabel(view.lastTransition)}`;
+    parts.push(`last turn ${view.lastTurn}${outcome}`);
+  }
+  const base = parts.join(" \xB7 ");
+  return view.lastError === void 0 ? base : `${base}: ${view.lastError}`;
+}
+function watchedLines(snapshot) {
+  const total = snapshot.watched.length + snapshot.missingWatched.length;
+  if (total === 0) return ["Watched sessions: none"];
+  const running = snapshot.watched.filter((view) => view.running).length;
+  const summary = running === 0 ? `Watched sessions: ${total}` : `Watched sessions: ${total} (${running} running)`;
+  const lines = [summary];
+  for (const view of snapshot.watched) lines.push(`  - ${sessionLabel(view)} \u2014 ${sessionStateLabel(view)}`);
+  for (const sessionId of snapshot.missingWatched) lines.push(`  - ${sessionId} \u2014 not found`);
+  return lines;
+}
+function notificationLines(snapshot) {
+  if (snapshot.notifications.length === 0) return ["Recent notifications: none"];
+  const lines = ["Recent notifications:"];
+  for (const notification of snapshot.notifications) {
+    lines.push(`  - ${formatInstant(notification.at)} ${notificationLine(notification)}`);
+  }
+  return lines;
+}
+function statusLines(snapshot) {
+  const lines = [
+    `DevLead mode: ${modeLabel(snapshot.enabled)}`,
+    ...watchedLines(snapshot),
+    ...notificationLines(snapshot)
+  ];
+  if (!snapshot.enabled) {
+    lines.push(
+      "DevLead mode is off: no notification wakes this Session until it is turned on again.",
+      "Turn DevLead mode on with: /devlead on"
+    );
+  }
+  lines.push(HELP_LINE);
+  return lines;
+}
+function renderStatus(snapshot, title) {
+  const lines = title === void 0 ? [] : [title, ""];
+  return { kind: "success", text: [...lines, ...statusLines(snapshot)].join("\n") };
+}
+function errorResult(text) {
+  return { kind: "error", text };
+}
+
+// packages/command/src/resolve.ts
+function candidateOf(view) {
+  return view.title === void 0 ? { sessionId: view.sessionId } : { sessionId: view.sessionId, title: view.title };
+}
+function mergeCandidates(listed, watchedSessionIds) {
+  const candidates = /* @__PURE__ */ new Map();
+  for (const view of listed) candidates.set(view.sessionId, candidateOf(view));
+  for (const sessionId of watchedSessionIds) {
+    if (!candidates.has(sessionId)) candidates.set(sessionId, { sessionId });
+  }
+  return [...candidates.values()];
+}
+function resolveSessionReference(query, candidates) {
+  const reference = query.trim();
+  if (reference.length === 0) return { kind: "missing" };
+  for (const candidate of candidates) {
+    if (candidate.sessionId !== reference) continue;
+    return candidate.title === void 0 ? { kind: "resolved", sessionId: candidate.sessionId } : { kind: "resolved", sessionId: candidate.sessionId, title: candidate.title };
+  }
+  const matches = candidates.filter((candidate) => candidate.sessionId.startsWith(reference));
+  const first = matches[0];
+  if (first === void 0) return { kind: "missing" };
+  if (matches.length === 1) {
+    return first.title === void 0 ? { kind: "resolved", sessionId: first.sessionId } : { kind: "resolved", sessionId: first.sessionId, title: first.title };
+  }
+  return { kind: "ambiguous", candidates: matches };
+}
+var MAX_RENDERED_CANDIDATES = 10;
+function candidateLabel(candidate) {
+  return candidate.title === void 0 ? candidate.sessionId : `${candidate.title} (${candidate.sessionId})`;
+}
+function formatCandidates(candidates) {
+  const shown = candidates.slice(0, MAX_RENDERED_CANDIDATES);
+  const lines = shown.map((candidate) => `  - ${candidateLabel(candidate)}`);
+  const hidden = candidates.length - shown.length;
+  if (hidden > 0) lines.push(`  \u2026 and ${hidden} more`);
+  return lines;
+}
+
+// packages/command/src/index.ts
+var name = "command-devlead";
+var inject = ["commands", "devLead"];
+var DESCRIPTION = "Turn DevLead mode on or off for this Session, watch or unwatch another Session, and inspect the DevLead mode, watch set, and recent notification digest.";
+var NOT_ENABLED_MESSAGE = "DevLead mode is off for this Session, so its watch set cannot change. Turn it on with /devlead on first.";
+async function collectStatus(ctx, invocation) {
+  const view = ctx.devLead.view(invocation.agent);
+  const watched = [];
+  const missingWatched = [];
+  if (view.sessions.length > 0) {
+    const sessions = await ctx.devLead.listSessions(
+      invocation.agent,
+      { watchedOnly: true },
+      invocation.signal
+    );
+    const byId = new Map(sessions.map((session) => [session.sessionId, session]));
+    for (const sessionId of view.sessions) {
+      const session = byId.get(sessionId);
+      if (session === void 0) missingWatched.push(sessionId);
+      else watched.push(session);
+    }
+  }
+  return {
+    enabled: view.enabled,
+    watched,
+    missingWatched,
+    notifications: ctx.devLead.notifications(invocation.agent, { limit: RECENT_NOTIFICATION_LIMIT })
+  };
+}
+async function collectCandidates(ctx, invocation, watchedSessionIds) {
+  const sessions = await ctx.devLead.listSessions(invocation.agent, {}, invocation.signal);
+  return mergeCandidates(sessions, watchedSessionIds);
+}
+function ambiguousResult(query, candidates) {
+  return errorResult([
+    `Session reference "${query}" is ambiguous; it matches ${candidates.length} Sessions:`,
+    ...formatCandidates(candidates),
+    "Use a longer prefix or the full Session id."
+  ].join("\n"));
+}
+function missingSessionResult(query) {
+  return errorResult(
+    `No Session matches "${query}". Check the Session id, or run /devlead to inspect the watched Sessions.`
+  );
+}
+function referenceLabel(sessionId, title) {
+  return title === void 0 ? sessionId : `${title} (${sessionId})`;
+}
+async function resolveBeyondListing(ctx, invocation, reference) {
+  try {
+    const view = await ctx.devLead.getSession(invocation.agent, reference, invocation.signal);
+    return view.title === void 0 ? { kind: "resolved", sessionId: view.sessionId } : { kind: "resolved", sessionId: view.sessionId, title: view.title };
+  } catch (error) {
+    if (!isDevLeadError(error)) throw error;
+    if (error.code === "DEVLEAD_INVALID_INPUT") return { kind: "ambiguous", message: error.message };
+    if (error.code === "DEVLEAD_SESSION_NOT_FOUND") return { kind: "missing" };
+    throw error;
+  }
+}
+async function resolveWatchTarget(ctx, invocation, reference, watchedSessionIds) {
+  const candidates = await collectCandidates(ctx, invocation, watchedSessionIds);
+  const resolution = resolveSessionReference(reference, candidates);
+  if (resolution.kind === "resolved") return resolution;
+  if (resolution.kind === "ambiguous") {
+    return { kind: "failure", result: ambiguousResult(reference, resolution.candidates) };
+  }
+  const fallback = await resolveBeyondListing(ctx, invocation, reference);
+  if (fallback.kind === "resolved") return fallback;
+  if (fallback.kind === "ambiguous") {
+    return {
+      kind: "failure",
+      result: errorResult(`${fallback.message}
+Use a longer prefix or the full Session id.`)
+    };
+  }
+  return { kind: "failure", result: missingSessionResult(reference) };
+}
+async function executeMode(ctx, invocation, enabled) {
+  if (ctx.devLead.view(invocation.agent).enabled === enabled) {
+    const title2 = enabled ? "DevLead mode is already on." : "DevLead mode is already off.";
+    return renderStatus(await collectStatus(ctx, invocation), title2);
+  }
+  await ctx.devLead.setEnabled(invocation.agent, enabled, invocation.signal);
+  const title = enabled ? "DevLead mode enabled." : "DevLead mode disabled.";
+  return renderStatus(await collectStatus(ctx, invocation), title);
+}
+async function executeWatch(ctx, invocation, command) {
+  const view = ctx.devLead.view(invocation.agent);
+  if (!view.enabled) return errorResult(NOT_ENABLED_MESSAGE);
+  const target = await resolveWatchTarget(ctx, invocation, command.session, view.sessions);
+  if (target.kind === "failure") return target.result;
+  const { sessionId } = target;
+  const label = referenceLabel(sessionId, target.title);
+  const watching = view.sessions.includes(sessionId);
+  if (command.kind === "watch") {
+    const title2 = watching ? `Already watching ${label}.` : `Now watching ${label}.`;
+    if (!watching) await ctx.devLead.watchSession(invocation.agent, sessionId, true);
+    return renderStatus(await collectStatus(ctx, invocation), title2);
+  }
+  const title = watching ? `Stopped watching ${label}.` : `Not watching ${label}.`;
+  if (watching) await ctx.devLead.watchSession(invocation.agent, sessionId, false);
+  return renderStatus(await collectStatus(ctx, invocation), title);
+}
+function friendlyDevLeadError(error) {
+  switch (error.code) {
+    case "DEVLEAD_NOT_ENABLED":
+      return NOT_ENABLED_MESSAGE;
+    case "DEVLEAD_AGENT_NOT_LIVE":
+      return "This Session is no longer live, so DevLead mode cannot be changed. Open it again from the sidebar and retry.";
+    case "DEVLEAD_INVALID_INPUT":
+      return `The /devlead request is not usable: ${error.message}`;
+    case "DEVLEAD_SESSION_NOT_FOUND":
+      return `The host could not find that Session: ${error.message}`;
+    case "DEVLEAD_SESSION_ARCHIVED":
+      return "That Session is archived; unarchive it in DSH before watching or steering it.";
+    case "DEVLEAD_SESSION_UNAVAILABLE":
+      return `That Session cannot be resumed right now: ${error.message}`;
+    case "DEVLEAD_WATCH_LIMIT":
+      return "The maximum number of watched Sessions has been reached. Stop watching one with /devlead unwatch <session> first.";
+    case "DEVLEAD_SELF_WATCH":
+      return "A DevLead Session cannot watch itself.";
+    case "DEVLEAD_PROJECTION_INVALID":
+      return `This Session's DevLead records are damaged: ${error.message}. Inspect the Session log for the offending plugin:devlead record.`;
+    case "DEVLEAD_WORKSPACE_NOT_FOUND":
+      return `The Workspace could not be resolved: ${error.message}`;
+    case "DEVLEAD_DIRECTORY_MISSING":
+      return `The target directory is missing: ${error.message}`;
+    default:
+      return `The DevLead request failed: ${error.message}`;
+  }
+}
+async function executeDevLeadCommand(ctx, invocation) {
+  const command = parseDevLeadCommand(invocation.rawInput);
+  if (invocation.attachments.length > 0) {
+    return errorResult(
+      "The /devlead command does not accept attachments; use the plain command text instead."
+    );
+  }
+  if (command.kind === "invalid") return errorResult(`${command.message}
+${USAGE}`);
+  try {
+    switch (command.kind) {
+      case "status":
+        return renderStatus(await collectStatus(ctx, invocation));
+      case "on":
+      case "off":
+        return await executeMode(ctx, invocation, command.kind === "on");
+      case "watch":
+      case "unwatch":
+        return await executeWatch(ctx, invocation, command);
+    }
+  } catch (error) {
+    if (isDevLeadError(error)) return errorResult(friendlyDevLeadError(error));
+    throw error;
+  }
+}
+function apply(ctx) {
+  ctx.commands.register({
+    definitionId: CommandDefinitionId("@yankeguo/dsh-command-devlead"),
+    name: DEVLEAD_COMMAND_NAME2,
+    description: DESCRIPTION,
+    input: { hint: COMMAND_GRAMMAR },
+    handler: (invocation) => executeDevLeadCommand(ctx, invocation)
+  });
+}
+export {
+  apply,
+  inject,
+  name
+};

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@yankeguo/dsh-command-devlead",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Human-facing /devlead command: enable or disable DevLead mode for the current session and inspect the lead's managed workspaces, sessions, and notifications.",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0",
+    "@deepseek-ai/dsh-commands": "0.2.2-rc.1"
+  },
+  "dependencies": {
+    "@yankeguo/dsh-devlead": "0.1.0",
+    "@yankeguo/dsh-devlead-protocol": "0.1.0"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yankeguo/dsh-devlead.git",
+    "directory": "packages/command"
+  },
+  "homepage": "https://github.com/yankeguo/dsh-devlead#readme"
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.