@takara-ai/miru-code 1.6.0 → 1.7.2

package/src/installer/style-packs/ste/skill.ts

@@ -0,0 +1,218 @@
+/**
+ * STE mode — on-demand Agent Skill + references (clear technical English).
+ * Unofficial ASD-STE100-inspired aid; not ASD-certified.
+ */
+
+export const STE_SKILL_NAME = "ste";
+
+export interface SteReferenceFile {
+  relativePath: string;
+  content: string;
+}
+
+/** Compact pragmatic `SKILL.md` (YAML frontmatter + body). */
+export const STE_SKILL_MD = `---
+name: ste
+description: >-
+  Clear technical English for docs, runbooks, errors, and release notes.
+  Use when the user says STE, ASD-STE100, /ste, de-slop, write for non-native
+  readers, or asks to rewrite technical prose. Pragmatic by default; strict
+  when they ask for STE compliance. Not for marketing or brand copy. Not for
+  ultra-compressed chat telegraph style.
+---
+
+# STE writing (Simplified Technical English)
+
+On-demand clear technical writing for Miru. **Short complete sentences. Keep articles.**
+
+Unofficial aid inspired by [ASD-STE100](https://www.asd-ste100.org) Issue 9 themes.
+**Not ASD-certified. Not ASD-endorsed.** Full dictionary compliance needs the official standard at asd-ste100.org.
+
+Inspired by prior art ([AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish), [woosal STE kit](https://github.com/woosal1337/blog/tree/main/videos/ep01-the-cure-for-ai-slop)) — original Miru skill text. Do not vend copyrighted ASD dictionary word lists.
+
+## Activate
+
+| User says | Effect |
+|-----------|--------|
+| \`/ste\`, \`STE\`, \`write in STE\`, \`de-slop this\` | ON **pragmatic** (default) |
+| \`ASD-STE100\`, \`strict STE\`, \`STE compliance\` | ON **strict** — also load \`references/rules.md\` |
+| Check / audit my STE | Use \`references/checklist.md\` |
+
+## Task flow
+
+1. Select mode (pragmatic vs strict)
+2. Classify text as **procedural** or **descriptive**
+3. Pick one consistent term per concept
+4. Apply core rules below
+5. Run **self-check**
+6. Deliver
+
+## Modes
+
+| Mode | Behaviour |
+|------|-----------|
+| **Pragmatic** (default) | Structural rules + consistent terms. Domain nouns/verbs OK (\`webhook\`, \`deploy\`, \`commit\`). |
+| **Strict** | Stricter vocabulary discipline. Tell the user full compliance needs the official ASD dictionary: https://www.asd-ste100.org — then load \`references/rules.md\`. |
+
+Cite rule numbers **only** when they appear in \`references/rules.md\`. Do not invent ASD rule IDs.
+
+## Core rules (pragmatic)
+
+- Short **complete** sentences. Keep \`a\` / \`an\` / \`the\` and \`that\`. No telegraph omission.
+- No semicolons — use two sentences.
+- **Procedural:** imperative; about 20 words max per sentence; one instruction per sentence; **condition BEFORE command**.
+- **Descriptive:** simple tenses; about 25 words max per sentence; one topic per paragraph.
+- Active voice; simple tenses; avoid present-perfect stacks and comma "-ing" padding.
+- Prefer modals \`can\` / \`will\` / \`must\`. Avoid \`should\` / \`would\` / \`may\` / \`might\` / \`could\` in instructions.
+- One name per concept in the document (no check/verify/confirm/validate roulette).
+- Warnings: state the command or condition first, then the risk.
+
+## Untouchables
+
+Never alter:
+
+- Code fences, identifiers, CLI flags, paths
+- Quoted errors, product/API names
+- Required safety conditions, limits, versions
+
+If shortening would drop a required qualifier, keep the longer clear sentence.
+Miru MCP tool use stays intact when search policy is installed.
+
+## Not for marketing
+
+Do **not** apply STE to marketing, brand, or persuasive copy. Decline and offer a docs-oriented rewrite instead.
+
+## Slop → plain (examples)
+
+| Slop | Plain |
+|------|-------|
+| It is worth noting that the service is highly robust | The service stays up if the primary node fails |
+| You should consider carefully validating the input | You must validate the input |
+| Feel free to simply leverage the existing utility | Use the existing utility |
+
+## Before / after
+
+**Before (slop):**
+> It is worth noting that you should carefully ensure the migration has completed successfully before you proceed to delete the old volume, as doing so might potentially result in irreversible data loss.
+
+**After (STE pragmatic):**
+> Wait until the migration is complete. Then delete the old volume. If you delete the volume too early, you will lose data permanently.
+
+## Self-check (before delivery)
+
+1. Sentences complete with articles where needed?
+2. One instruction per procedural sentence; condition before command?
+3. Terms consistent; modals are can/will/must where instructions appear?
+4. Code, paths, errors, and safety limits untouched?
+
+For a longer audit, read \`references/checklist.md\`.
+
+## References
+
+- \`references/rules.md\` — fuller paraphrased rule catalog (strict / audit)
+- \`references/checklist.md\` — extended self-check patterns
+`;
+
+export const STE_RULES_MD = `# STE rules catalog (Miru paraphrase)
+
+Unofficial structural catalog for Miru STE **strict** / audit use.
+Themes follow ASD-STE100 Issue 9. **Not a copy of the official standard. Not a dictionary.**
+Official standard and dictionary: https://www.asd-ste100.org
+
+Cite the rule IDs below only. Do not invent other ASD numbers.
+
+## Words and terms
+
+### R1 — One name per concept
+Pick one term for each idea in the document. Do not rotate synonyms (\`check\` / \`verify\` / \`validate\`) for the same action.
+
+### R2 — Approved instruction modals
+In procedures, prefer \`can\`, \`will\`, \`must\`. Avoid \`should\`, \`would\`, \`may\`, \`might\`, \`could\` when you give an instruction.
+
+### R3 — Keep articles and "that"
+Write complete noun phrases. Keep \`a\`, \`an\`, \`the\`, and \`that\`. Do not drop them for brevity.
+
+### R4 — No semicolon glue
+Do not join two ideas with a semicolon. Use two sentences.
+
+## Sentences
+
+### R5 — Procedural length
+In procedures, aim for about **20 words or fewer** per sentence. Give **one instruction** per sentence.
+
+### R6 — Descriptive length
+In descriptions, aim for about **25 words or fewer** per sentence. Keep **one topic** per paragraph.
+
+### R7 — Condition before command
+State the condition first. Then give the command.
+
+Example: \`If the node is down, stop the job.\`
+Not: \`Stop the job if the node is down.\` when the condition is the safety gate.
+
+### R8 — Active voice and simple tense
+Prefer active voice and simple present or simple past. Avoid stacked present-perfect and trailing "-ing" clauses that hide the actor.
+
+## Safety
+
+### R9 — Warning shape
+For destructive actions: state the command or the condition clearly, then state the risk.
+
+Example: \`Do not run this on production. This command deletes all rows in the table.\`
+
+### R10 — Do not drop required limits
+If a version, limit, or condition is required for safety, keep it. Clarity beats compression.
+
+## Software examples
+
+| Weak | Stronger STE shape |
+|------|--------------------|
+| You might want to restart the pod | Restart the pod |
+| Ensure that connectivity has been established | Make sure the connection is up |
+| After having deployed the chart, proceed to verify | Deploy the chart. Then check the release status |
+
+## Dictionary
+
+Miru does **not** ship the ASD approved-word list. For strict vocabulary compliance, use the official dictionary from asd-ste100.org. Domain technical nouns (\`Kubernetes\`, \`webhook\`, \`IAM\`) stay as product names (untouchable).
+`;
+
+export const STE_CHECKLIST_MD = `# STE extended checklist (Miru)
+
+Use this for **check mode** / audits after a rewrite. Unofficial. Not ASD certification.
+
+## Structure
+
+- [ ] Procedural sentences ≈ ≤20 words; one instruction each
+- [ ] Descriptive sentences ≈ ≤25 words; one topic per paragraph
+- [ ] Condition appears before the command when safety depends on it
+- [ ] No semicolons used as sentence glue
+- [ ] Articles and \`that\` kept (not telegraph)
+
+## Wording
+
+- [ ] One term per concept across the document
+- [ ] Instruction modals are can / will / must (not should / might / could)
+- [ ] Active voice; simple tenses
+- [ ] No marketing filler ("robust", "seamless", "it is worth noting")
+
+## Safety and precision
+
+- [ ] Destructive steps warn with command/condition first, then risk
+- [ ] Required versions, limits, and conditions still present
+- [ ] Code, paths, CLI, quoted errors unchanged
+
+## Scope
+
+- [ ] Not applied to marketing / brand copy
+- [ ] Strict mode users pointed at https://www.asd-ste100.org for the official dictionary
+- [ ] Disclaimer remembered: Miru STE is unofficial / not certified
+
+## Delivery
+
+- [ ] Self-check in the main skill completed before send
+`;
+
+/** Files written under the skill directory beside `SKILL.md`. */
+export const STE_REFERENCE_FILES: SteReferenceFile[] = [
+  { relativePath: "references/rules.md", content: STE_RULES_MD },
+  { relativePath: "references/checklist.md", content: STE_CHECKLIST_MD },
+];

package/src/mcp/auth-tool.ts

@@ -3,20 +3,54 @@ import {
   checkDeviceAuthorizationOnce,
   type DeviceAuthConfig,
   type DeviceAuthorizationStart,
+  openBrowserForDeviceLogin,
   resolveDeviceAuthConfig,
   startDeviceAuthorization,
 } from "../auth/device.ts";
+import { isCredentialsError } from "../auth/errors.ts";
 import { saveStoredCredentials, setStoredCredentialsEnvToken } from "../credentials.ts";
 import { toolText } from "./index-cache.ts";
 import type { MiruMcpServer } from "./runtime.ts";
 
+type ToolResult = ReturnType<typeof toolText>;
+
+const CHECK_HINT =
+  'Once the user approves, call `auth` again with action "check" to finish signing in.';
+
+/** Appended to credentials failures so an agent knows Miru's own recovery step. */
+const RECOVERY_HINT =
+  'Miru is not signed in. Call the `auth` tool with action "start" — it opens the Takara ' +
+  'device-login page in the browser — then action "check" once the user approves.';
+
 const AUTH_TOOL_DESCRIPTION =
   "Sign in with Takara credentials via device-code login — no terminal required. " +
   "Only call this in direct response to a tool error mentioning missing/expired " +
   "credentials — never speculatively, since it starts a real sign-in prompt for the " +
-  'user. Call with no arguments (or action "start") to begin: it returns a URL and a ' +
-  "short code. Show both to the user and ask them to open the link and approve. Once " +
-  'they confirm, call again with action "check" to complete sign-in.';
+  'user. Call with no arguments (or action "start") to begin: it opens the device-login ' +
+  `page in the user's browser and returns that URL plus a short code. ${CHECK_HINT}`;
+
+/** Browser opener seam; the real one spawns a detached `open`/`xdg-open`/`start`. */
+export type BrowserOpener = (url: string) => boolean;
+
+/** Opening is on unless MIRU_OPEN_BROWSER is set to something other than "1" (matches `miru setup`). */
+function openIfAllowed(open: BrowserOpener, url: string): boolean {
+  const raw = process.env.MIRU_OPEN_BROWSER;
+  if (raw !== undefined && raw !== "1") {
+    return false;
+  }
+  return open(url);
+}
+
+function approvalText(link: string, userCode: string, opened: boolean): string {
+  const lead = opened ? `A browser tab is open at ${link}` : `Ask the user to open ${link}`;
+  return `${lead}. Code: ${userCode}. ${CHECK_HINT}`;
+}
+
+/** Tool-failure text for every Miru tool, with the sign-in step added when relevant. */
+export function toolErrorText(err: unknown): ToolResult {
+  const message = err instanceof Error ? err.message : String(err);
+  return toolText(isCredentialsError(err) ? `${message}\n\n${RECOVERY_HINT}` : message);
+}
 
 type PendingDeviceAuth = {
   start: DeviceAuthorizationStart;
@@ -24,7 +58,7 @@ type PendingDeviceAuth = {
   startedAtMs: number;
 };
 
-function isExpired(entry: Pick<PendingDeviceAuth, "start" | "startedAtMs">): boolean {
+function isExpired(entry: PendingDeviceAuth): boolean {
   return Date.now() >= entry.startedAtMs + entry.start.expiresIn * 1000;
 }
 
@@ -36,31 +70,24 @@ function isExpired(entry: Pick<PendingDeviceAuth, "start" | "startedAtMs">): boo
 class AuthToolState {
   private pending: PendingDeviceAuth | null = null;
 
-  async start(): Promise<{ content: Array<{ type: "text"; text: string }> }> {
-    if (this.pending && !isExpired(this.pending)) {
-      const { userCode, verificationUriComplete, verificationUri } = this.pending.start;
-      return toolText(
-        `A device login is already pending. Open ${verificationUriComplete ?? verificationUri} ` +
-          `and enter code ${userCode} if not already filled in, then call \`auth\` again with ` +
-          'action "check" once approved.',
-      );
+  constructor(private readonly openBrowser: BrowserOpener) {}
+
+  async start(): Promise<ToolResult> {
+    let pending = this.pending;
+    if (!pending || isExpired(pending)) {
+      const config = resolveDeviceAuthConfig();
+      const start = await startDeviceAuthorization({ config });
+      pending = { start, config, startedAtMs: Date.now() };
+      this.pending = pending;
     }
-    this.pending = null;
-
-    const config = resolveDeviceAuthConfig();
-    const start = await startDeviceAuthorization({ config });
-    this.pending = { start, config, startedAtMs: Date.now() };
-
-    const link = start.verificationUriComplete ?? start.verificationUri;
-    return toolText(
-      `Open ${link} and approve the request` +
-        (start.verificationUriComplete ? "." : ` (enter code ${start.userCode} if prompted).`) +
-        ` Code: ${start.userCode}. Once the user confirms they've approved it, call \`auth\` again ` +
-        'with action "check" to finish signing in.',
-    );
+
+    const { verificationUriComplete, verificationUri, userCode } = pending.start;
+    const link = verificationUriComplete ?? verificationUri;
+    // Reopening on a repeat call is deliberate: the user may have closed the first tab.
+    return toolText(approvalText(link, userCode, openIfAllowed(this.openBrowser, link)));
   }
 
-  async check(): Promise<{ content: Array<{ type: "text"; text: string }> }> {
+  async check(): Promise<ToolResult> {
     if (!this.pending) {
       return toolText('No device login is pending. Call `auth` with action "start" first.');
     }
@@ -106,8 +133,11 @@ class AuthToolState {
   }
 }
 
-export function registerAuthTool(server: MiruMcpServer): void {
-  const state = new AuthToolState();
+export function registerAuthTool(
+  server: MiruMcpServer,
+  options?: { openBrowser?: BrowserOpener },
+): void {
+  const state = new AuthToolState(options?.openBrowser ?? openBrowserForDeviceLogin);
 
   server.registerTool(
     "auth",

package/src/mcp/index-cache.ts

@@ -399,7 +399,8 @@ export async function getIndexForRepo(
     return await cache.get(repo, ref);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`Failed to index ${repo}: ${message}`);
+    // Keep `cause` so the tool boundary can still recognize a credentials failure.
+    throw new Error(`Failed to index ${repo}: ${message}`, { cause: err });
   }
 }
 

package/src/mcp/server.ts

@@ -34,7 +34,7 @@ import {
   MAX_MCP_TOP_K,
   resolveChunk,
 } from "../utils.ts";
-import { registerAuthTool } from "./auth-tool.ts";
+import { registerAuthTool, toolErrorText } from "./auth-tool.ts";
 import {
   formatExpandResultsText,
   formatLiteralLocateText,
@@ -161,7 +161,7 @@ export function createMcpServer(
         const body = formatResultsText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -247,7 +247,7 @@ export function createMcpServer(
         const body = formatLiteralLocateText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -308,7 +308,7 @@ export function createMcpServer(
           ),
         );
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );
@@ -360,7 +360,7 @@ export function createMcpServer(
           ),
         );
       } catch (err) {
-        return toolText(err instanceof Error ? err.message : String(err));
+        return toolErrorText(err);
       }
     },
   );

package/src/spinner.ts

@@ -1,10 +1,12 @@
 import { dim, green, red } from "./cli-ui.ts";
+import { displayWidth } from "./terminal.ts";
 
 const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
 export class Spinner {
   private timer: ReturnType<typeof setInterval> | null = null;
   private frame = 0;
+  private belowLines = 0;
 
   constructor(private readonly message: string) {}
 
@@ -13,10 +15,22 @@ export class Spinner {
       process.stderr.write(`${this.message}...\n`);
       return;
     }
-    this.timer = setInterval(() => {
-      const glyph = FRAMES[this.frame++ % FRAMES.length];
-      process.stderr.write(`\r${dim(glyph)} ${this.message}`);
-    }, 80);
+    this.draw();
+    this.timer = setInterval(() => this.draw(), 80);
+  }
+
+  follow(line: string): void {
+    if (!process.stderr.isTTY) {
+      process.stderr.write(`${line}\n`);
+      return;
+    }
+    const cols = process.stderr.columns || 80;
+    const rows = line.split("\n").reduce((count, part) => {
+      return count + Math.max(1, Math.ceil(displayWidth(part) / cols));
+    }, 0);
+    process.stderr.write(`\n${line}`);
+    this.belowLines += rows;
+    process.stderr.write(`\x1b[${this.belowLines}A`);
   }
 
   stop(finalMessage?: string): void {
@@ -26,8 +40,16 @@ export class Spinner {
     }
     if (process.stderr.isTTY) {
       process.stderr.write("\r\x1b[K");
-    }
-    if (finalMessage) {
+      if (finalMessage) {
+        process.stderr.write(finalMessage);
+      }
+      if (this.belowLines > 0) {
+        process.stderr.write(`\x1b[${this.belowLines}B`);
+      }
+      if (finalMessage || this.belowLines > 0) {
+        process.stderr.write("\n");
+      }
+    } else if (finalMessage) {
       process.stderr.write(`${finalMessage}\n`);
     }
   }
@@ -43,6 +65,11 @@ export class Spinner {
   fail(message?: string): void {
     this.stop(red("✗ ") + (message ?? this.message));
   }
+
+  private draw(): void {
+    const glyph = FRAMES[this.frame++ % FRAMES.length];
+    process.stderr.write(`\r${dim(glyph)} ${this.message}`);
+  }
 }
 
 export async function withSpinner<T>(