pi-simple-english 0.7.0 → 0.8.0

package/README.md

@@ -1,42 +1,86 @@
 # simple-english for `pi`
 
-A `pi` package that lints the prose the agent writes.
+> Write for human, not for agent.
 
-The package ships the `lint-simple-english` skill, the
-`write-simple-english` skill, and the `se_lint` tool. The tool lints
-a file or a directory. The write skill carries the rules, so the
-agent writes clean prose the first time. The lint skill tells the
-agent to lint the prose it writes and fix every finding.
+You can teach an agent plain-English prose with a skill or a
+prompt. It writes clean prose in the first paragraph and slop again
+by the third. This linter keeps the agent honest: it reads what the
+agent wrote and names every broken rule. Send the findings back, and
+the agent corrects its own text.
 
-## Prerequisites
+<table>
+<tr>
+<th width="50%">Before</th>
+<th width="50%">After</th>
+</tr>
+<tr>
+<td valign="top">
 
-The linter is a Ruby gem. Install it once, before the adapter:
+> Your API keys are rotated by the service every 90 days — you will need to update them if you get a 401; don't panic, simply re-run the setup command, which regenerates the credentials without any downtime. <!-- se: ignore -->
 
-```bash
-gem install simple_english
-```
+</td>
+<td valign="top">
 
-## Install
+> The service rotates your API keys every 90 days. If you get a 401, update them. Do not panic. Re-run the setup command. It regenerates the credentials without any downtime.
+
+</td>
+</tr>
+</table>
 
-For yourself, on every project:
+The linter covers Markdown prose plus code comments in Python, Ruby,
+JavaScript, TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and
+YAML.
+
+## What it checks
+
+- **Voice:** say who does the action.
+- **Tense:** simple tenses only, no present perfect.
+- **Modals:** `can`, `will`, `must` only.
+- **Punctuation:** no em-dashes, no semicolons.
+- **Contractions:** write every word in full.
+- **Sentence shape:** condition before command, no `-ing` phrase after a comma.
+- **Word choice:** about 50 substitution rules, from `leverage` to `in conclusion`.
+- **Counts:** 20 words per sentence in list items, 25 in paragraphs, six sentences per paragraph at most.
+
+It lints Markdown prose plus code comments in Python, Ruby,
+JavaScript, TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and
+YAML. The full list, with a wrong and a right example for each rule,
+is [docs/RULES.md](https://github.com/TonyCTHsu/simple-english/blob/master/docs/RULES.md).
+
+## Install
 
 ```bash
 pi install npm:pi-simple-english
 ```
 
-For one project, with the team, install into the project instead. Run
-the install with `-l` from the project root:
+Install it for one project only by adding `-l` and running the
+command from the project root.
+
+The tool calls the `se` CLI. That CLI ships as a Ruby gem. Install
+it once, before the first lint:
 
 ```bash
-pi install npm:pi-simple-english -l
+gem install simple_english
+```
+
+## What you get
+
+The `se_lint` tool lints a file or a directory on demand. Every
+file edit lints too. The findings land in the edit result, so the
+agent fixes them in the same turn. Each finding carries a line
+number, a rule ID, and a fix hint:
+
+```
+README.md:12:31-32: [SE_NO_SEMICOLON] ";" - Write two sentences, or name the relation.
 ```
 
-The project install writes `.pi/settings.json`, which you commit. Pi
-loads it only after you grant project trust.
+The `write-simple-english` skill carries the rules, so the agent
+writes clean prose the first time. The `lint-simple-english` skill
+tells the agent to lint the prose it writes and fix every finding.
 
 ## Versions
 
-The package version tracks the gem version. The changelog is the
-repository changelog. See the section that matches the version:
+The package version tracks the gem version. The changelog lives in
+the repository:
 
 https://github.com/TonyCTHsu/simple-english/blob/master/CHANGELOG.md

package/extensions/se-lint.ts

@@ -1,19 +1,86 @@
 /**
  * se_lint - lint Markdown prose and code comments with simple_english.
  *
- * Shells out to the `se` CLI. Assumes the gem is installed; on a
- * missing binary the tool fails with install steps.
+ * Two layers. The se_lint tool lints on demand. Enforcement runs the
+ * same lint after every edit or write and appends the findings to the
+ * tool result, so the agent sees them in the turn that made them. It
+ * never blocks the edit. The contract mirrors the claude-code hook in
+ * integrations/claude-code/hooks/lint.sh: a clean file stays silent,
+ * a failed lint says so instead of reading as clean, and a missing
+ * binary names the install step.
  */
 
 import { execFile } from "node:child_process";
 import { Type } from "typebox";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ToolResultEvent,
+	ToolResultEventResult,
+} from "@earendil-works/pi-coding-agent";
 
 const OUTPUT_LIMIT = 4000;
 // ponytail: 120s allows a cold daemon boot (LanguageTool + JVM). If that
 // ever proves slow in practice, cut to 30s and pre-warm via `se serve`.
 const TIMEOUT_MS = 120_000;
 
+interface SeResult {
+	stdout: string;
+	code: number;
+}
+
+interface SeDetails {
+	path: string;
+	exitCode: number;
+	findings: number;
+	full?: string;
+}
+
+function seLint(path: string, signal?: AbortSignal): Promise<SeResult> {
+	return new Promise((resolve, reject) => {
+		execFile(
+			"se",
+			["lint", path],
+			{ timeout: TIMEOUT_MS, maxBuffer: 1024 * 1024, signal },
+			(error, stdout) => {
+				if (error && typeof error.code !== "number") {
+					reject(error);
+					return;
+				}
+				resolve({ stdout, code: (error?.code as number | undefined) ?? 0 });
+			},
+		);
+	});
+}
+
+// The feedback appended to an edit or write result. undefined means
+// clean: nothing is appended, so a clean edit reads as a clean edit.
+async function lintFeedback(path: string): Promise<string | undefined> {
+	let result: SeResult;
+	try {
+		result = await seLint(path);
+	} catch (err) {
+		const e = err as NodeJS.ErrnoException;
+		if (e.code === "ENOENT") {
+			return "`se` is not installed, so the file was not linted. Install it first: `gem install simple_english`, then retry.";
+		}
+		return `se lint failed, so the file was not linted. Run \`se lint ${path}\` to see the error.`;
+	}
+	if (result.code >= 2) {
+		return `se exited ${result.code} and the file was not linted. Run \`se lint ${path}\` to see the error.`;
+	}
+	const full = result.stdout.trim();
+	if (result.code === 0 || !full) {
+		return undefined;
+	}
+	const findings = full.split("\n").length;
+	const text =
+		full.length > OUTPUT_LIMIT
+			? `${full.slice(0, OUTPUT_LIMIT)}\n... truncated (${full.length} chars, ${findings} findings). Full output: run \`se lint ${path}\` with bash.`
+			: full;
+	return `se found ${findings} lint finding(s) in ${path}. Fix them, then lint again:\n${text}`;
+}
+
 export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "se_lint",
@@ -28,24 +95,11 @@ export default function (pi: ExtensionAPI) {
 			path: Type.String({ description: "File or directory to lint, relative to the CWD or absolute" }),
 		}),
 
-		async execute(_toolCallId, params, signal) {
+		async execute(_toolCallId, params, signal): Promise<AgentToolResult<SeDetails>> {
 			let stdout: string;
 			let code: number;
 			try {
-				({ stdout, code } = await new Promise<{ stdout: string; code: number }>((resolve, reject) => {
-					execFile(
-						"se",
-						["lint", params.path],
-						{ timeout: TIMEOUT_MS, maxBuffer: 1024 * 1024, signal },
-						(error, out) => {
-							if (error && typeof error.code !== "number") {
-								reject(error);
-								return;
-							}
-							resolve({ stdout: out, code: (error?.code as number | undefined) ?? 0 });
-						},
-					);
-				}));
+				({ stdout, code } = await seLint(params.path, signal));
 			} catch (err) {
 				const e = err as NodeJS.ErrnoException;
 				if (e.code === "ENOENT") {
@@ -64,7 +118,7 @@ export default function (pi: ExtensionAPI) {
 			if (!full) {
 				return {
 					content: [{ type: "text" as const, text: `clean: no findings in ${params.path}` }],
-					details: { path: params.path, exitCode: code, findings: 0 },
+					details: { path: params.path, exitCode: code, findings: 0, full: undefined },
 				};
 			}
 
@@ -79,4 +133,15 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 	});
+
+	pi.on("tool_result", async (event: ToolResultEvent): Promise<ToolResultEventResult | undefined> => {
+		if (event.toolName !== "edit" && event.toolName !== "write") return;
+		// A failed edit wrote nothing: there is nothing to lint.
+		if (event.isError) return;
+		const path = event.input.path;
+		if (typeof path !== "string" || path === "") return;
+		const feedback = await lintFeedback(path);
+		if (!feedback) return;
+		return { content: [...event.content, { type: "text" as const, text: feedback }] };
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simple-english",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Lint prose and code comments with the simple_english plain-English rules.",
   "type": "module",
   "license": "MIT",