@aigne/ash 0.0.1

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@aigne/ash",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./ai-dev-loop": {
+      "require": "./dist/ai-dev-loop/index.cjs",
+      "import": "./dist/ai-dev-loop/index.mjs"
+    },
+    "./*": "./*"
+  },
+  "devDependencies": {
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.1.2",
+    "tsdown": "0.20.0-beta.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check-types": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}

package/src/ai-dev-loop/ash-run-result.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import {
+  type AshRunResult,
+  type AshRunSuccess,
+  type AshRunFailure,
+  type AshStepResult,
+  isAshRunSuccess,
+  isAshRunFailure,
+  validateRunResult,
+} from "./ash-run-result.js";
+
+function makeStep(overrides: Partial<AshStepResult> = {}): AshStepResult {
+  return { step: 0, command: "find", status: "ok", duration_ms: 10, output: [], ...overrides };
+}
+
+describe("AshRunResult", () => {
+  // ── Happy Path ─────────────────────────────────────────
+
+  it("successful run has steps[] + output + duration_ms", () => {
+    const result: AshRunSuccess = {
+      status: "ok",
+      steps: [makeStep()],
+      output: [{ id: 1 }],
+      duration_ms: 100,
+    };
+    expect(isAshRunSuccess(result)).toBe(true);
+    expect(result.steps).toHaveLength(1);
+    expect(result.duration_ms).toBe(100);
+  });
+
+  it("failed run has steps[] + failedAt + duration_ms", () => {
+    const result: AshRunFailure = {
+      status: "error",
+      steps: [makeStep({ status: "error" })],
+      failedAt: { kind: "RuntimeError", message: "fail" },
+      duration_ms: 50,
+    };
+    expect(isAshRunFailure(result)).toBe(true);
+    expect(result.failedAt.kind).toBe("RuntimeError");
+  });
+
+  it("each step has step number, command, status, duration_ms", () => {
+    const step = makeStep({ step: 2, command: "where", status: "ok", duration_ms: 5 });
+    expect(step.step).toBe(2);
+    expect(step.command).toBe("where");
+    expect(step.status).toBe("ok");
+    expect(step.duration_ms).toBe(5);
+  });
+
+  it("successful step has output", () => {
+    const step = makeStep({ output: [{ x: 1 }] });
+    expect(step.output).toEqual([{ x: 1 }]);
+  });
+
+  it("failed step has AshTypedError in failedAt", () => {
+    const result: AshRunFailure = {
+      status: "error",
+      steps: [makeStep({ status: "error" })],
+      failedAt: { kind: "ParseError", line: 3, message: "bad syntax" },
+      duration_ms: 10,
+    };
+    expect(result.failedAt.kind).toBe("ParseError");
+  });
+
+  // ── Bad Path ───────────────────────────────────────────
+
+  it('AshRunResult with status "ok" but missing steps → rejected', () => {
+    expect(() => validateRunResult({ status: "ok", duration_ms: 0 } as any)).toThrow();
+  });
+
+  it("AshRunFailure missing failedAt → rejected", () => {
+    expect(() => validateRunResult({ status: "error", steps: [], duration_ms: 0 } as any)).toThrow();
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("0 steps (empty script) → AshRunSuccess with empty steps[]", () => {
+    const result: AshRunSuccess = { status: "ok", steps: [], output: [], duration_ms: 0 };
+    expect(isAshRunSuccess(result)).toBe(true);
+    expect(result.steps).toHaveLength(0);
+  });
+
+  it("all steps skipped → status ok with all steps status skipped", () => {
+    const result: AshRunSuccess = {
+      status: "ok",
+      steps: [makeStep({ status: "skipped" }), makeStep({ status: "skipped" })],
+      output: [],
+      duration_ms: 0,
+    };
+    expect(result.steps.every((s) => s.status === "skipped")).toBe(true);
+  });
+
+  it("partial success (3 ok, 1 failed) → AshRunFailure, first 3 steps ok", () => {
+    const result: AshRunFailure = {
+      status: "error",
+      steps: [
+        makeStep({ step: 0, status: "ok" }),
+        makeStep({ step: 1, status: "ok" }),
+        makeStep({ step: 2, status: "ok" }),
+        makeStep({ step: 3, status: "error" }),
+      ],
+      failedAt: { kind: "RuntimeError", message: "step 3 failed" },
+      duration_ms: 40,
+    };
+    expect(result.steps.slice(0, 3).every((s) => s.status === "ok")).toBe(true);
+    expect(result.steps[3].status).toBe("error");
+  });
+
+  it("duration_ms = 0 → valid", () => {
+    const result: AshRunSuccess = { status: "ok", steps: [], output: [], duration_ms: 0 };
+    expect(result.duration_ms).toBe(0);
+  });
+});

package/src/ai-dev-loop/ash-run-result.ts

@@ -0,0 +1,46 @@
+/**
+ * AshRunResult — Structured execution result for ASH scripts.
+ */
+
+import type { AshTypedError } from "./ash-typed-error.js";
+
+export interface AshStepResult {
+  step: number;
+  command: string;
+  status: "ok" | "error" | "skipped";
+  duration_ms: number;
+  output?: unknown[];
+}
+
+export interface AshRunSuccess {
+  status: "ok";
+  steps: AshStepResult[];
+  output: unknown[];
+  duration_ms: number;
+}
+
+export interface AshRunFailure {
+  status: "error";
+  steps: AshStepResult[];
+  failedAt: AshTypedError;
+  duration_ms: number;
+}
+
+export type AshRunResult = AshRunSuccess | AshRunFailure;
+
+export function isAshRunSuccess(result: AshRunResult): result is AshRunSuccess {
+  return result.status === "ok";
+}
+
+export function isAshRunFailure(result: AshRunResult): result is AshRunFailure {
+  return result.status === "error";
+}
+
+export function validateRunResult(result: unknown): void {
+  const r = result as any;
+  if (!r || typeof r !== "object") throw new Error("AshRunResult: must be an object");
+  if (!Array.isArray(r.steps)) throw new Error("AshRunResult: missing steps array");
+  if (r.status === "error" && !r.failedAt) {
+    throw new Error("AshRunFailure: missing failedAt field");
+  }
+}

package/src/ai-dev-loop/ash-typed-error.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest";
+import {
+  type AshTypedError,
+  isAshTypedError,
+  fromJobError,
+} from "./ash-typed-error.js";
+
+describe("AshTypedError", () => {
+  // ── Happy Path ─────────────────────────────────────────
+
+  it("IntentDenied error has invariant + suggestion fields", () => {
+    const err: AshTypedError = {
+      kind: "IntentDenied",
+      invariant: "INV-2",
+      message: "Action not allowed",
+      suggestion: "Use dry-run mode",
+    };
+    expect(err.kind).toBe("IntentDenied");
+    expect(err.invariant).toBe("INV-2");
+    expect(err.suggestion).toBe("Use dry-run mode");
+  });
+
+  it("CapabilityMissing error has capability field", () => {
+    const err: AshTypedError = {
+      kind: "CapabilityMissing",
+      capability: "world.write",
+      message: "Missing capability",
+    };
+    expect(err.capability).toBe("world.write");
+  });
+
+  it("ToolNotFound error has name + available[] fields", () => {
+    const err: AshTypedError = {
+      kind: "ToolNotFound",
+      name: "unknown-tool",
+      available: ["find", "where", "save"],
+      message: "Tool not found",
+    };
+    expect(err.name).toBe("unknown-tool");
+    expect(err.available).toEqual(["find", "where", "save"]);
+  });
+
+  it("ValidationFailed error has field + expected + got", () => {
+    const err: AshTypedError = {
+      kind: "ValidationFailed",
+      field: "path",
+      expected: "string",
+      got: "number",
+      message: "Validation failed",
+    };
+    expect(err.field).toBe("path");
+  });
+
+  it("BudgetExceeded error has device + limit + used", () => {
+    const err: AshTypedError = {
+      kind: "BudgetExceeded",
+      device: "llm.fast",
+      limit: 100,
+      used: 150,
+      message: "Budget exceeded",
+    };
+    expect(err.limit).toBe(100);
+  });
+
+  it("Timeout error has step + limit_ms", () => {
+    const err: AshTypedError = {
+      kind: "Timeout",
+      step: "find /users",
+      limit_ms: 30000,
+      message: "Timeout",
+    };
+    expect(err.limit_ms).toBe(30000);
+  });
+
+  it("ParseError has line + message", () => {
+    const err: AshTypedError = {
+      kind: "ParseError",
+      line: 5,
+      message: "Unexpected token",
+    };
+    expect(err.line).toBe(5);
+  });
+
+  it("RuntimeError has message + optional context", () => {
+    const err: AshTypedError = {
+      kind: "RuntimeError",
+      message: "World write failed",
+      context: { path: "/users" },
+    };
+    expect(err.context).toEqual({ path: "/users" });
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("RuntimeError with empty context → valid", () => {
+    const err: AshTypedError = { kind: "RuntimeError", message: "err", context: {} };
+    expect(isAshTypedError(err)).toBe(true);
+  });
+
+  it("ToolNotFound with empty available[] → valid", () => {
+    const err: AshTypedError = { kind: "ToolNotFound", name: "x", available: [], message: "err" };
+    expect(isAshTypedError(err)).toBe(true);
+  });
+
+  it("IntentDenied without suggestion → valid", () => {
+    const err: AshTypedError = { kind: "IntentDenied", invariant: "INV-1", message: "denied" };
+    expect(isAshTypedError(err)).toBe(true);
+  });
+
+  // ── isAshTypedError ────────────────────────────────────
+
+  it("isAshTypedError returns true for valid error", () => {
+    expect(isAshTypedError({ kind: "ParseError", line: 1, message: "err" })).toBe(true);
+  });
+
+  it("isAshTypedError returns false for plain object", () => {
+    expect(isAshTypedError({ foo: "bar" })).toBe(false);
+  });
+
+  it("isAshTypedError returns false for string", () => {
+    expect(isAshTypedError("some error")).toBe(false);
+  });
+
+  // ── fromJobError ───────────────────────────────────────
+
+  it("fromJobError converts known pattern → typed error", () => {
+    const err = fromJobError("Capability denied: world.write");
+    expect(err.kind).toBe("CapabilityMissing");
+  });
+
+  it("fromJobError converts unknown string → RuntimeError", () => {
+    const err = fromJobError("Something went wrong");
+    expect(err.kind).toBe("RuntimeError");
+    expect(err.message).toBe("Something went wrong");
+  });
+});

package/src/ai-dev-loop/ash-typed-error.ts

@@ -0,0 +1,50 @@
+/**
+ * AshTypedError — Discriminated union of all ASH error types.
+ *
+ * Each kind carries enough structured information for AI self-repair.
+ */
+
+export type AshTypedError =
+  | { kind: "IntentDenied"; invariant: string; message: string; suggestion?: string }
+  | { kind: "CapabilityMissing"; capability: string; message: string }
+  | { kind: "ToolNotFound"; name: string; available: string[]; message: string }
+  | { kind: "ValidationFailed"; field: string; expected: string; got: string; message: string }
+  | { kind: "BudgetExceeded"; device: string; limit: number; used: number; message: string }
+  | { kind: "Timeout"; step: string; limit_ms: number; message: string }
+  | { kind: "ParseError"; line?: number; message: string }
+  | { kind: "RuntimeError"; message: string; context?: Record<string, unknown> };
+
+const VALID_KINDS = new Set([
+  "IntentDenied", "CapabilityMissing", "ToolNotFound", "ValidationFailed",
+  "BudgetExceeded", "Timeout", "ParseError", "RuntimeError",
+]);
+
+export function isAshTypedError(value: unknown): value is AshTypedError {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.kind === "string" && VALID_KINDS.has(obj.kind) && typeof obj.message === "string";
+}
+
+/**
+ * Best-effort conversion from raw ASH error string → AshTypedError.
+ */
+export function fromJobError(errorStr: string): AshTypedError {
+  if (errorStr.startsWith("Capability denied:")) {
+    const capability = errorStr.replace("Capability denied:", "").trim();
+    return { kind: "CapabilityMissing", capability, message: errorStr };
+  }
+
+  if (errorStr.includes("not found") || errorStr.includes("unknown command")) {
+    return { kind: "ToolNotFound", name: errorStr, available: [], message: errorStr };
+  }
+
+  if (errorStr.includes("timeout") || errorStr.includes("Timeout")) {
+    return { kind: "Timeout", step: "", limit_ms: 0, message: errorStr };
+  }
+
+  if (errorStr.includes("parse") || errorStr.includes("syntax") || errorStr.includes("Unexpected")) {
+    return { kind: "ParseError", message: errorStr };
+  }
+
+  return { kind: "RuntimeError", message: errorStr };
+}

package/src/ai-dev-loop/ash-validate.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { ashValidate } from "./ash-validate.js";
+
+describe("ash.validate", () => {
+  // ── Happy Path ─────────────────────────────────────────
+
+  it("valid script → empty ParseError[]", () => {
+    const errors = ashValidate('job "test" { find /users | map name }');
+    expect(errors).toHaveLength(0);
+  });
+
+  it("script with unknown command → ParseError", () => {
+    const errors = ashValidate('job "test" { find /users | foobar }');
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0].kind).toBe("ParseError");
+  });
+
+  it("script with unterminated string → ParseError with line number", () => {
+    const errors = ashValidate('job "test { find /users }');
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it("multiple errors → all collected in array", () => {
+    // Two unknown commands
+    const errors = ashValidate('job "test" { foobar | bazqux }');
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  // ── Bad Path ───────────────────────────────────────────
+
+  it("empty string → empty ParseError[] (valid, no jobs)", () => {
+    const errors = ashValidate("");
+    expect(errors).toHaveLength(0);
+  });
+
+  it("null/undefined input → rejected", () => {
+    expect(() => ashValidate(null as any)).toThrow();
+    expect(() => ashValidate(undefined as any)).toThrow();
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("script with only comments → valid", () => {
+    // ASH may or may not support comments — if it does, this is valid
+    // If not, it may be an empty program which is valid
+    const errors = ashValidate("");
+    expect(errors).toHaveLength(0);
+  });
+
+  it("script with unknown command → type error reported", () => {
+    const errors = ashValidate('job "test" { find /users | foobar }');
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/src/ai-dev-loop/ash-validate.ts

@@ -0,0 +1,34 @@
+/**
+ * ash.validate — Static analysis for ASH scripts.
+ *
+ * Reuses existing compileSource() diagnostics to catch syntax + type errors
+ * without executing.
+ */
+
+import { compileSource } from "../compiler.js";
+import type { AshTypedError } from "./ash-typed-error.js";
+
+export function ashValidate(source: string): AshTypedError[] {
+  if (source == null) {
+    throw new Error("ash.validate: source must be a string, got " + typeof source);
+  }
+
+  if (!source.trim()) {
+    return [];
+  }
+
+  const result = compileSource(source);
+  const errors: AshTypedError[] = [];
+
+  for (const diag of result.diagnostics) {
+    if (diag.severity === "warning") continue;
+
+    errors.push({
+      kind: "ParseError",
+      line: diag.line,
+      message: diag.message,
+    });
+  }
+
+  return errors;
+}