dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/pstack/skills/statechart/scripts/statechart.test.mjs

@@ -0,0 +1,198 @@
+import { key, show } from "./ir.mjs";
+import { plainText } from "./backends/plain-text.mjs";
+import { compile } from "./pipeline.mjs";
+import { readConfig } from "./frontends/config.mjs";
+import { parseValue } from "./frontends/value.mjs";
+import { readMessages } from "./frontends/messages.mjs";
+import { readChecks } from "./frontends/spec.mjs";
+import { checkView, json } from "./frontends/view.mjs";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import { inspect } from "node:util";
+import assert from "node:assert/strict";
+// runtime/skills/statechart/scripts/statechart.test.ts
+const invariant = {
+	kind: "invariant",
+	name: "Inv"
+};
+function graphWithBreak() {
+	return {
+		states: /* @__PURE__ */ new Map([["s0", {
+			vars: { x: 0 },
+			start: true,
+			breaks: []
+		}], ["s1", {
+			vars: { x: 1 },
+			start: false,
+			breaks: [invariant]
+		}]]),
+		steps: [{
+			from: "s0",
+			to: "s1",
+			action: "Next"
+		}]
+	};
+}
+function resultWithBreak() {
+	return {
+		spec: {
+			module: "Test",
+			folder: "/tmp",
+			variables: ["x"],
+			invariants: ["Inv"],
+			properties: [],
+			deadlock: false,
+			written: []
+		},
+		graph: graphWithBreak(),
+		paths: void 0,
+		rules: [{
+			rule: invariant,
+			outcome: "broken",
+			messages: ["Inv is violated"]
+		}],
+		properties: [],
+		exit: 1,
+		stop: void 0,
+		drawing: void 0,
+		states: {
+			distinct: 2,
+			initial: 1,
+			complete: true,
+			cut: false
+		},
+		messages: ["TLC finished"]
+	};
+}
+test("reads the TLA+ value grammar the skill documents", () => {
+	assert.deepEqual(json(parseValue("<<1, \"a\", <<>>>>")), {
+		1: 1,
+		2: "a",
+		3: {}
+	});
+	assert.deepEqual(json(parseValue("{r1, -2}")), ["r1", -2]);
+	assert.deepEqual(json(parseValue("-1..2")), [
+		-1,
+		0,
+		1,
+		2
+	]);
+	assert.deepEqual(json(parseValue("[ok |-> TRUE, msg |-> \"say \\\"hi\\\"\"]")), {
+		ok: true,
+		msg: "say \"hi\""
+	});
+	assert.throws(() => parseValue("1.."), /cannot read TLA\+ value/);
+});
+test("prints each value in TLA+ and compares by TLA+ equality", () => {
+	assert.equal(show(parseValue("<<0>>")), "<<0>>");
+	assert.equal(show(parseValue("[a |-> 1]")), "[a |-> 1]");
+	assert.equal(key(parseValue("1..3")), key(parseValue("{3, 1, 2, 2}")));
+	assert.notEqual(key(parseValue("\"A\"")), key(parseValue("A")));
+});
+test("reads a TLC config into the checks the report names", () => {
+	const config = readConfig({
+		file: "Min.cfg",
+		text: "INIT Init\nNEXT Next\nINVARIANT Inv\nPROPERTY Live\n"
+	});
+	assert.equal(config.init, "Init");
+	assert.equal(config.next, "Next");
+	assert.deepEqual(config.invariants, ["Inv"]);
+	assert.deepEqual(config.properties, ["Live"]);
+	const checks = readChecks({
+		configFile: "Min.cfg",
+		config
+	});
+	assert.equal(checks.deadlock, true);
+});
+test("prints TLC's -tool messages as plain text", () => {
+	const text = [
+		"@!@!@STARTMSG 2262:0 @!@!@",
+		"TLC2 Version 2.19",
+		"@!@!@ENDMSG 2262 @!@!@"
+	].join("\n");
+	assert.equal([...plainText(readMessages(text))].join(""), "TLC2 Version 2.19\n");
+});
+test("compiles a broken rule into report.md, chart.mmd, and tlc.out", () => {
+	const compiled = compile(resultWithBreak(), checkView({}, inspect));
+	assert.equal(compiled.exit, 1);
+	const report = compiled.report;
+	assert.match(report, /Inv/);
+	assert.match(report, /Next/);
+	const chart = [...compiled.files.get("chart.mmd") ?? []].join("");
+	assert.match(chart, /stateDiagram/);
+	assert.match(chart, /Next/);
+	assert.ok(compiled.files.has("report.md"));
+	assert.ok(compiled.files.has("tlc.out"));
+});
+test("the CLI rejects a missing spec with usage and exit 2", () => {
+	const here = import.meta.dirname;
+	const entry = join(here, import.meta.url.endsWith(".ts") ? "statechart.ts" : "statechart.mjs");
+	const result = spawnSync(process.execPath, [entry], { encoding: "utf8" });
+	assert.equal(result.status, 2);
+	assert.match(result.stderr, /Give one SPEC\.tla\./);
+	assert.match(result.stderr, /Usage: statechart SPEC\.tla/);
+});
+test("the CLI runs the worker against TLC and writes the report, chart, and tlc.out", () => {
+	const root = mkdtempSync(join(tmpdir(), "statechart-worker-"));
+	try {
+		const caseDir = join(root, "case");
+		mkdirSync(caseDir);
+		writeFileSync(join(caseDir, "Smoke.tla"), "---- MODULE Smoke ----\n====\n");
+		writeFileSync(join(caseDir, "Smoke.cfg"), "INIT Init\nNEXT Next\n");
+		const fakeJava = join(root, "fake-java.mjs");
+		writeFileSync(fakeJava, String.raw`#!/usr/bin/env node
+import fs from "node:fs";
+const args = process.argv.slice(2);
+if (args.includes("tla2sany.xml.XMLExporter")) {
+  process.stdout.write('<modules><context><entry><UID>1</UID><OpDeclNode><uniquename>x</uniquename><kind>3</kind></OpDeclNode></entry><entry><UID>2</UID><ModuleNode><uniquename>Smoke</uniquename><OpDeclNodeRef><UID>1</UID></OpDeclNodeRef></ModuleNode></entry></context><RootModule>Smoke</RootModule></modules>');
+  process.exit(0);
+}
+const dump = args.indexOf("-dump");
+if (dump !== -1) {
+  fs.writeFileSync(args[dump + 2] + ".dot", [
+    "strict digraph DiskGraph {",
+    '1 [label="/\\\\ x = 0",style = filled]',
+    '2 [label="/\\\\ x = 1"]',
+    '1 -> 2 [label="Next"];',
+    "}",
+  ].join("\n"));
+}
+process.stdout.write("@!@!@STARTMSG 2199:0 @!@!@\n2 distinct states found.\n@!@!@ENDMSG 2199 @!@!@\n");
+process.exit(0);
+`);
+		chmodSync(fakeJava, 493);
+		const here = import.meta.dirname;
+		const entry = join(here, import.meta.url.endsWith(".ts") ? "statechart.ts" : "statechart.mjs");
+		const out = join(root, "out");
+		const result = spawnSync(process.execPath, [
+			entry,
+			join(caseDir, "Smoke.tla"),
+			"--out",
+			out
+		], {
+			encoding: "utf8",
+			env: {
+				...process.env,
+				JAVA: fakeJava,
+				TLA2TOOLS: "tla2tools.jar"
+			}
+		});
+		assert.equal(result.status, 0, result.stderr);
+		assert.deepEqual(readdirSync(out).sort(), [
+			"chart.mmd",
+			"report.md",
+			"tlc.out"
+		]);
+		assert.match(readFileSync(join(out, "report.md"), "utf8"), /# Smoke[\s\S]*NoDeadlock/);
+		assert.match(readFileSync(join(out, "chart.mmd"), "utf8"), /stateDiagram/);
+	} finally {
+		rmSync(root, {
+			recursive: true,
+			force: true
+		});
+	}
+});
+export {};

package/dist/pstack/skills/statechart/scripts/worker.mjs

@@ -0,0 +1,31 @@
+import { compile } from "./pipeline.mjs";
+import { check, messageOf } from "./run.mjs";
+import { checkView } from "./frontends/view.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { inspect } from "node:util";
+import { pathToFileURL } from "node:url";
+import { Buffer } from "node:buffer";
+// runtime/skills/statechart/scripts/worker.ts
+const [stage, specFile, configFile, viewFile] = process.argv.slice(2);
+try {
+	const view = checkView(viewFile ? await import(pathToFileURL(path.resolve(viewFile)).href) : {}, inspect);
+	const { files, exit } = compile(await check(specFile, configFile), view);
+	const draft = path.join(stage, "draft");
+	fs.mkdirSync(draft);
+	for (const [name, parts] of files) {
+		const fd = fs.openSync(path.join(draft, name), "wx");
+		try {
+			for (const part of parts) fs.writeSync(fd, typeof part === "string" ? Buffer.from(part) : part);
+			fs.writeSync(fd, "\n");
+		} finally {
+			fs.closeSync(fd);
+		}
+	}
+	fs.renameSync(draft, path.join(stage, "done"));
+	process.exit(exit);
+} catch (error) {
+	console.error(messageOf(error));
+	process.exit(2);
+}
+export {};

package/dist/pstack/skills/swarm/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: swarm
+description: "Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration."
+disable-model-invocation: true
+---
+
+# Swarm
+
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
+
+## Start
+
+Open a todolist with one entry per phase before launching anything.
+
+1. Frame
+2. Fan out
+3. Aggregate
+4. Report
+
+## Phase A: Frame
+
+1. State the done predicate and the artifact or report the swarm must return.
+2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
+3. Pick the worker model from the `swarm workers` line in `~/.cursor/rules/pstack-models.mdc`. If the rule or that line is missing, use `grok-4.7-xhigh-fast`. For `auto` or `inherit-parent`, omit `model` so the workers run on the parent model. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message. For a model race, name each arm's model up front. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+4. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
+
+## Phase B: Fan out
+
+Spawn all N workers in one message with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true`, and the step 3 model, left unset for `auto` or `inherit-parent`. Use `environment: "local"` only when the worker needs access to something on the user's computer.
+
+When a worker must start from a non-default pushed branch, pass `cloud_base_branch`.
+
+Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
+
+If a worker drops out, proceed with N-1 and note it.
+
+## Phase C: Aggregate
+
+Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
+
+## Phase D: Report
+
+Return one consolidated in-chat report with a result table, issue one-liners, gaps or dropouts, and the race rule when used.

package/{assets → dist/pstack}/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.
+description: "Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested."
 disable-model-invocation: true
 ---
 

package/{assets → dist/pstack}/skills/teach/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: teach
-description: Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'.
+description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
 disable-model-invocation: true
 ---
 
 # Teach
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
 **You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
 

package/{assets → dist/pstack}/skills/technical-writing/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Technical writing
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
 Write so a tired engineer understands on the first read. Apply all four layers.
 

package/{assets → dist/pstack}/skills/typescript-best-practices/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: typescript-best-practices
 description: TypeScript best practices. Use when reading or editing any .ts or .tsx file.
+paths: ["**/*.ts", "**/*.tsx"]
 disable-model-invocation: true
 ---
 
 # TypeScript best practices
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
-Apply `principle-type-system-discipline` first; read its `SKILL.md` at its absolute resource path.
+Apply the **type-system-discipline** principle skill first.
 
 | Rule | Summary |
 |------|---------|
@@ -23,12 +22,10 @@ Apply `principle-type-system-discipline` first; read its `SKILL.md` at its absol
 | Type guards | Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`. |
 | Exhaustiveness | Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added. |
 | `satisfies` over `as` | Validates the value without widening literal types. |
-| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See `principle-boundary-discipline`; read its `SKILL.md` at its absolute resource path. |
+| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. See the **boundary-discipline** principle skill. |
 | Schema-derived types | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface. |
 | Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
 | Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
 | Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code. |
 
 Examples: `references/patterns.md`.
-
-This skill is explicit-invocation only. DSH does not consume a `paths` glob, so opening a `.ts` or `.tsx` file does not attach it: load it by name when you want it applied.

package/{assets → dist/pstack}/skills/why/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: why
-description: Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
+description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior."
 disable-model-invocation: true
 ---
 
 # Why
 
-> DSH port of pstack. `pstack_subagent` replaces Cursor's Task tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
+In DeepSeek Harness, read [the DSH adapter](../../docs/harness/dsh.md) once per session before you follow this skill. It maps the Cursor names in pstack skills to DeepSeek Harness.
 
-Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works; read its `SKILL.md` at its absolute resource path when you need it. `why` answers what forces led to its shape.
+Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape.
 
-Each spawn below names a role key. `pstack_subagent` reads the route from `$DSH_HOME/pstack-models.md` on every delegation, and a role the file does not name inherits the parent route. Never invent a model id: this package cannot know which routes a deployment serves. An effort is different, because the target model advertises its own list and `pstack_subagent` checks your value against it and names the real values when it refuses, so predict no ladder beyond that. Read the Subagents section of the `poteto-mode` skill at its absolute resource path before you spawn anything. Start from the level the role line names, raise it for hard work and lower it for routine work by passing `reasoningEffort`; a child that cannot call `set_reasoning_effort` keeps the level you gave it.
+Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
 
-Every spawn is `agent: "general"` with a brief that forbids writes. **Do not swap in a narrower preset or tool set.** A narrower set can drop MCP tools, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still must not write anything, and each brief says so; that rule is an instruction, not a sandbox, so check `git status` before believing a report.
+Every spawn is `generalPurpose` with `readonly: false` (agent mode). **Do not use readonly/Ask mode.** It strips MCP access, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still shouldn't write anything.
 
 ## Operating Posture
 
@@ -34,7 +34,7 @@ Before spawning investigators, build the seed context inline: file paths and lin
 
 ### Discovery
 
-Before spawning investigators, list the tools this Session actually has, and treat an MCP as available only when its own tools appear in that list. The DSH harness exposes no MCP directory to inspect, and this port does not read one: an MCP that is absent from the tool list is a recorded gap, never a guess.
+Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers.
 
 Map each available MCP to one evidence category:
 
@@ -48,7 +48,7 @@ Map each available MCP to one evidence category:
 
 Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.
 
-Spawn one investigator per category that has a matching MCP, all in one batch of `pstack_subagent` calls so they start together, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. Use `role: "why investigators"`. Each call returns a child id and the reports arrive as completion notices, so nothing polls and the synthesizer waits for every investigator that was started.
+Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `model`: the `why investigators` line, default `grok-4.7-xhigh-fast`.
 
 Each investigator's prompt is `references/investigator-prompt.md` filled in, plus:
 - the category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`
@@ -78,7 +78,7 @@ If your scope assessment suggests a single-commit trivial target where the PR de
 
 ## Step 4. Synthesize
 
-Spawn one synthesizer with `role: "why synthesizer"`. It gets:
+Spawn one synthesizer. `model`: the `why synthesizer` line, default `claude-opus-5-5-xhigh`. It gets:
 1. The investigator findings, including any null results and any categories skipped with justification
 2. The code anchor
 3. The user's original question

package/dist/remote.d.mts

@@ -0,0 +1,27 @@
+import { CatalogueResult } from "./models.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-DZwTn2wF.mjs";
+import { RemoteResult, TypertRemoteContribution, TypertRemoteInfo } from "@deepseek-ai/dsh-typert-protocol";
+/** npm package that owns these methods. */
+export declare const REMOTE_PACKAGE = "dsh-pstack";
+/** Cordis service key and wire namespace of the Host role service. */
+export declare const ROLES_SERVICE = "pstackRoles";
+/** Parse one save request from the wire. */
+export declare function parseSaveRoleRequest(value: unknown): SaveRoleRequest;
+/** Parse a role-file snapshot from the wire. */
+export declare function parseRoleFileSnapshot(value: unknown): RoleFileSnapshot;
+/** Parse a save result from the wire. */
+export declare function parseSaveRoleResult(value: unknown): SaveRoleResult;
+/** Parse the live catalogue the page offers. */
+export declare function parseCatalogue(value: unknown): CatalogueResult;
+/** The typed Client face installed by `$mount`. */
+export interface PstackRolesNamespace {
+  readonly pstackRoles: {
+    status(): Promise<RemoteResult<RoleFileSnapshot>>;
+    catalogue(signal?: AbortSignal): Promise<RemoteResult<CatalogueResult>>;
+    save(request: SaveRoleRequest, signal?: AbortSignal): Promise<RemoteResult<SaveRoleResult>>;
+  };
+}
+/** Mountable contribution the Client passes to `ctx.remote.$mount()`. */
+export declare const pstackRolesRemote: TypertRemoteInfo;
+/** The same descriptors registered by the Host as its strict definitions. */
+export declare const pstackRolesContribution: TypertRemoteContribution;