@stackstackstack/dsh-commands 0.1.5

package/lib/types/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Durable command event vocabulary and the registry's Cordis event
+ * declaration, shared with type-only consumers. Client-safe: nothing here
+ * reaches a Host-only symbol, so a Client compilation face reads the same
+ * `commands/change` signature the Host emits.
+ *
+ * @module @stackstackstack/dsh-commands/types
+ */
+import type { CommandId } from './brand.ts';
+/** Immutable metadata for a command's optional unstructured input. */
+export interface CommandInputDescriptor {
+    /** Placeholder shown before the user supplies free-form input. */
+    readonly hint: string;
+}
+/** Expected command outcome rendered directly by the dispatching UI. */
+export type CommandResult = {
+    readonly kind: 'success';
+    readonly text?: string;
+    /** Earlier authoritative domain event that owns a richer presentation. */
+    readonly sourceEventSeq?: number;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/**
+ * One settled command execution: the handler's normalized result plus the
+ * lifecycle pairing id minted for its `command/run`/`command/done` records,
+ * so a dispatching surface can correlate the Remote acknowledgment with the
+ * flow node those events produce.
+ */
+export interface CommandExecution {
+    /** Pairing id carried by this execution's lifecycle events. */
+    readonly commandId: CommandId;
+    /** The handler's normalized outcome. */
+    readonly result: CommandResult;
+}
+/** Handler-free immutable command view returned to UI adapters. */
+export interface CommandDescriptor {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Human-readable summary used in discovery UI. */
+    readonly description: string;
+    /** Optional free-form input hint advertised to capable clients. */
+    readonly input?: CommandInputDescriptor;
+}
+/**
+ * Producer record for one command invocation (the `command/run` event's
+ * source slot). Merge-extensible sum type mirroring `MessageSourceMap`'s
+ * shape; minimal today because every executor caller is a human-facing UI
+ * surface dispatching a human-typed line, so the sole variant is `user`.
+ */
+export interface CommandSourceMap {
+    user: {
+        kind: 'user';
+    };
+}
+/** The union over {@link CommandSourceMap} — who issued a command line. */
+export type CommandSource = CommandSourceMap[keyof CommandSourceMap];
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * A command was registered or unregistered. This is an unfiltered registry
+         * notification because a global or scoped change may affect any UI view.
+         * Observer failures are contained and cannot veto the registry mutation.
+         * @mode emit
+         */
+        'commands/change'(): void;
+    }
+}
+declare module '@stackstackstack/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * A resolved slash command entered its handler. Log-only (never model
+         * surface); paired with `command/done` by `commandId`, mirroring the
+         * `tool/call`↔`tool/result` pairing. The payload is structured — `name`
+         * and `args` are `parseCommand`'s own split (name and verbatim rawInput,
+         * separator whitespace included), so a consumer (a projection unit
+         * folding its own command records, a rich command card) never re-parses
+         * a line. `args` is absent when the definition sets `recordInput: false`
+         * because an authoritative domain event owns the input payload.
+         */
+        'command/run': {
+            commandId: CommandId;
+            name: string;
+            args?: string;
+            source: CommandSource;
+        };
+        /**
+         * The paired command settled. `kind`/`text` carry the handler's verbatim
+         * outcome (a thrown/aborted handler settles as `kind: 'error'` with the
+         * rendered failure). A successful command may identify the earlier
+         * authoritative domain event for a richer client-computed presentation.
+         */
+        'command/done': {
+            commandId: CommandId;
+            kind: 'success' | 'error';
+            text?: string;
+            sourceEventSeq?: number;
+        };
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Durable command event vocabulary and the registry's Cordis event
+ * declaration, shared with type-only consumers. Client-safe: nothing here
+ * reaches a Host-only symbol, so a Client compilation face reads the same
+ * `commands/change` signature the Host emits.
+ *
+ * @module @stackstackstack/dsh-commands/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@stackstackstack/dsh-commands",
+  "description": "Plugin-owned human command registry for DeepSeek Harness UIs",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/interaction/commands"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./brand": {
+      "types": "./lib/types/brand.d.ts",
+      "default": "./lib/types/brand.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.host.d.ts",
+      "default": "./lib/typert.host.js"
+    },
+    "./remote": {
+      "types": "./lib/typert.remote-client.d.ts",
+      "default": "./lib/typert.remote-client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/typert.host.js",
+    "lib/typert.host.d.ts",
+    "lib/typert.remote-client.js",
+    "lib/typert.remote-client.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-typert-protocol": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-brand": "^0.1.5"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-brand": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@stackstackstack/dsh-typert-protocol": "^0.1.5"
+  }
+}