@mirinjs/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/src/shared/report.ts

@@ -0,0 +1,69 @@
+/**
+ * Output shaping for CLI commands. Invariant: in `--json` mode nothing but JSON
+ * reaches stdout, process-wide — `childStdio` and `build()` route child output away.
+ */
+
+import type { $ } from "bun";
+
+export type ChildStdio = ["ignore", "inherit" | 2, "inherit"];
+
+export interface Reporter {
+  readonly json: boolean;
+  /** Progress for a person. Suppressed in JSON mode. */
+  info(message: string): void;
+  /** Progress for a tool. Suppressed in human mode. */
+  event(phase: string, data?: Record<string, unknown>): void;
+  /** The final outcome. JSON mode prints `payload`; human mode calls `render`. */
+  finish(payload: Record<string, unknown>, render: () => void): void;
+  /** `stdio` for a long-lived child (Vite, the app): in JSON mode its stdout is
+   *  pointed at stderr, off the stream a caller parses. */
+  readonly childStdio: ChildStdio;
+  /** Await a build subprocess under the same rule — `bun build` writes its
+   *  bundle summary to stdout. */
+  build(shell: $.ShellPromise): Promise<void>;
+}
+
+export function createReporter(json: boolean): Reporter {
+  return {
+    json,
+    childStdio: ["ignore", json ? 2 : "inherit", "inherit"],
+    info(message) {
+      if (!json) console.log(message);
+    },
+    event(phase, data) {
+      if (json) console.log(JSON.stringify({ ts: Date.now(), phase, ...data }));
+    },
+    async build(shell) {
+      // Stream live: a cold `cargo build` takes minutes, and buffering looks like a hang.
+      if (!json) {
+        await shell;
+        return;
+      }
+      // Replay on stderr rather than dropping, or a failed build reports only its exit status.
+      try {
+        const output = await shell.quiet();
+        writeToStderr(output.stdout, output.stderr);
+      } catch (err) {
+        writeToStderr(...capturedStreams(err));
+        throw err;
+      }
+    },
+    finish(payload, render) {
+      if (json) console.log(JSON.stringify({ ts: Date.now(), phase: "result", ...payload }));
+      else render();
+    },
+  };
+}
+
+/** A `ShellError` carries the output the failed command produced; a plain Error does not. */
+function capturedStreams(value: unknown): unknown[] {
+  if (typeof value !== "object" || value === null) return [];
+  const shellError = value as Record<string, unknown>;
+  return [shellError.stdout, shellError.stderr];
+}
+
+function writeToStderr(...chunks: unknown[]): void {
+  for (const chunk of chunks) {
+    if (chunk instanceof Uint8Array && chunk.byteLength > 0) process.stderr.write(chunk);
+  }
+}

package/src/shared/scenario.ts

@@ -0,0 +1,58 @@
+/**
+ * Loading and running a `mirin check` scenario — an ordinary module that
+ * default-exports an async function (docs/agent-devtools.md).
+ */
+
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { CheckScenario } from "mirinjs/check";
+import { createDriver, type ScenarioOutcome } from "./driver.ts";
+import type { InspectorClient } from "./inspector.ts";
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Resolve and import a scenario file. Throws with an actionable message. */
+export async function loadScenario(projectDir: string, file: string): Promise<CheckScenario> {
+  const path = isAbsolute(file) ? file : resolve(projectDir, file);
+  if (!existsSync(path)) {
+    throw new Error(`scenario file not found: ${path}`);
+  }
+
+  let loaded: unknown;
+  try {
+    loaded = (await import(path)) as unknown;
+  } catch (err) {
+    throw new Error(`scenario ${file} failed to load: ${message(err)}`);
+  }
+
+  const scenario = (loaded as { default?: unknown }).default;
+  if (typeof scenario !== "function") {
+    throw new Error(
+      `scenario ${file} must default-export a function — see \`defineCheck\` from "mirinjs/check"`,
+    );
+  }
+  return scenario as CheckScenario;
+}
+
+/** Run `scenario` against the app. Never throws: a failure is a result, so the
+ *  caller still captures artifacts and writes a report. */
+export async function runScenario(
+  client: InspectorClient,
+  scenario: CheckScenario,
+  onStep?: (name: string) => void,
+): Promise<ScenarioOutcome> {
+  const { driver, outcome, finishStep } = createDriver(client, onStep);
+  try {
+    await scenario(driver);
+    finishStep(true);
+  } catch (err) {
+    finishStep(false);
+    outcome.failure = {
+      step: outcome.steps.at(-1)?.name ?? "scenario",
+      message: message(err),
+    };
+  }
+  return outcome;
+}

package/src/shared/session.ts

@@ -0,0 +1,153 @@
+/**
+ * Dev-session bookkeeping (docs/agent-devtools.md). The CLI owns `session.json`
+ * and `exit.json`; the app's Worker owns `inspector.json` and `events.jsonl` —
+ * one writer per file, so nothing needs locking.
+ */
+
+import {
+  createSessionDir,
+  DEV_SESSION_ENV,
+  type InspectorEndpoint,
+  newSessionId,
+  readEventsFile,
+  readInspectorEndpoint,
+  type SessionInfo,
+  type SessionPaths,
+  type SessionPhase,
+  writeCurrentSession,
+  writeSessionExit,
+  writeSessionInfo,
+} from "mirinjs/devtools/session";
+
+/** Events kept in `exit.json`, so the post-mortem is self-contained. */
+const EXIT_TAIL = 50;
+
+/** A phase in progress; call exactly one terminal method. */
+export interface PhaseHandle {
+  ok(detail?: string): void;
+  fail(detail?: string): void;
+}
+
+export interface DevSessionInit {
+  projectDir: string;
+  appName: string;
+  appId: string;
+  version?: string;
+  devUrl?: string;
+}
+
+export class DevSession {
+  readonly paths: SessionPaths;
+  #info: SessionInfo;
+
+  private constructor(paths: SessionPaths, info: SessionInfo) {
+    this.paths = paths;
+    this.#info = info;
+  }
+
+  /** Create `.mirin/dev/<id>/` and point `current.json` at it. Failure is not
+   *  fatal: a read-only project still runs `mirin dev`, just without artifacts. */
+  static create(init: DevSessionInit): DevSession | undefined {
+    const now = Date.now();
+    const id = newSessionId(now, process.pid);
+    try {
+      const paths = createSessionDir(init.projectDir, id);
+      const info: SessionInfo = {
+        version: 1,
+        id,
+        app: {
+          name: init.appName,
+          id: init.appId,
+          ...(init.version !== undefined ? { version: init.version } : {}),
+        },
+        projectDir: init.projectDir,
+        startedAt: now,
+        dev: true,
+        ...(init.devUrl !== undefined ? { devUrl: init.devUrl } : {}),
+        phases: [],
+      };
+      const session = new DevSession(paths, info);
+      session.#save();
+      writeCurrentSession(init.projectDir, paths.dir);
+      return session;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Env additions that point the app process at this session. */
+  env(): Record<string, string> {
+    return { [DEV_SESSION_ENV]: this.paths.dir };
+  }
+
+  /** Wait for the app's Worker to publish `inspector.json`; gives up quietly
+   *  rather than delay the dev loop. */
+  async waitForInspector(timeoutMs = 10_000): Promise<InspectorEndpoint | undefined> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const endpoint = readInspectorEndpoint(this.paths);
+      if (endpoint !== undefined) return endpoint;
+      await Bun.sleep(100);
+    }
+    return undefined;
+  }
+
+  /** Record the start of a phase and return its terminal handles. */
+  phase(name: string): PhaseHandle {
+    const startedAt = Date.now();
+    this.#push({ name, status: "start", ts: startedAt });
+    const settle = (status: "ok" | "fail", detail?: string): void => {
+      this.#push({
+        name,
+        status,
+        ts: Date.now(),
+        ms: Date.now() - startedAt,
+        ...(detail !== undefined ? { detail } : {}),
+      });
+    };
+    return {
+      ok: (detail) => settle("ok", detail),
+      fail: (detail) => settle("fail", detail),
+    };
+  }
+
+  setDevUrl(devUrl: string): void {
+    this.#info = { ...this.#info, devUrl };
+    this.#save();
+  }
+
+  setPid(pid: number): void {
+    this.#info = { ...this.#info, pid };
+    this.#save();
+  }
+
+  /** Write the post-mortem. The event tail is included so the file stands alone. */
+  finish(code: number | null, signal?: string): void {
+    const events = readEventsFile(this.paths.events);
+    try {
+      writeSessionExit(this.paths, {
+        version: 1,
+        exitedAt: Date.now(),
+        code,
+        ...(signal !== undefined ? { signal } : {}),
+        errorCount: events.filter((event) => event.level === "error").length,
+        tail: events.slice(-EXIT_TAIL),
+      });
+    } catch {
+      // Best effort: the exit code still reaches the caller through the return path.
+    }
+  }
+
+  #push(phase: SessionPhase): void {
+    this.#info = { ...this.#info, phases: [...this.#info.phases, phase] };
+    this.#save();
+  }
+
+  #save(): void {
+    try {
+      writeSessionInfo(this.paths, this.#info);
+    } catch {
+      // Diagnostics only — never interrupt the dev loop for them.
+    }
+  }
+}

package/src/skill.ts

@@ -0,0 +1,51 @@
+/**
+ * `mirin skill` — install or refresh the agent skill in an existing project.
+ * New apps get it from `mirin init`; a stale copy describes a surface that moved.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { installSkill } from "create-mirinjs/skill";
+import { createReporter } from "./shared/report.ts";
+
+export interface SkillOptions {
+  json?: boolean;
+}
+
+export async function skill(
+  projectDir = process.cwd(),
+  options: SkillOptions = {},
+): Promise<number> {
+  const reporter = createReporter(options.json === true);
+
+  // Not fatal: a monorepo may install the skill at its root, away from any manifest.
+  const hasManifest = existsSync(join(projectDir, "mirin.config.ts"));
+
+  try {
+    const result = installSkill(projectDir);
+    reporter.finish(
+      {
+        ok: true,
+        path: result.path,
+        replaced: result.replaced,
+        mirinProject: hasManifest,
+      },
+      () => {
+        console.log(
+          `\n✓ ${result.replaced ? "updated" : "installed"} the mirin agent skill at ${result.relativePath}`,
+        );
+        if (!hasManifest) {
+          console.log("  ! no mirin.config.ts here — is this the project root?");
+        }
+        console.log("  it teaches agents to verify changes with `mirin check`.\n");
+      },
+    );
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    reporter.finish({ ok: false, reason: message }, () => {
+      console.error(`\n✗ could not install the mirin agent skill: ${message}\n`);
+    });
+    return 1;
+  }
+}