@asterxsk/kiln 0.1.0 → 0.3.0

package/agent.bak.20260905-190020/extensions/file-search/src/process.ts

@@ -0,0 +1,146 @@
+import { dirname, join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { Effect, FileSystem, Stream } from "effect";
+import { ChildProcess } from "effect/unstable/process";
+import type { CapturedOutput } from "./output.ts";
+
+const STDERR_MAX_BYTES = 64 * 1024;
+
+interface PreviewState {
+  readonly decoder: TextDecoder;
+  preview: string;
+  totalBytes: number;
+  lineBreaks: number;
+  trailingLineBreaks: number;
+  truncated: boolean;
+}
+
+function makePreviewState(): PreviewState {
+  return {
+    decoder: new TextDecoder(),
+    preview: "",
+    totalBytes: 0,
+    lineBreaks: 0,
+    trailingLineBreaks: 0,
+    truncated: false,
+  };
+}
+
+function observeStdout(state: PreviewState, chunk: Uint8Array) {
+  state.totalBytes += chunk.byteLength;
+  for (const byte of chunk) {
+    if (byte === 0x0a) {
+      state.lineBreaks++;
+      state.trailingLineBreaks++;
+    } else {
+      state.trailingLineBreaks = 0;
+    }
+  }
+
+  if (state.truncated) return;
+  state.preview += state.decoder.decode(chunk, { stream: true });
+  const truncation = truncateHead(state.preview, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+  if (truncation.truncated) {
+    state.preview = truncation.content;
+    state.truncated = true;
+  }
+}
+
+function finishStdout(state: PreviewState, fullOutputPath: string) {
+  if (!state.truncated) state.preview += state.decoder.decode();
+  const totalBytes = state.totalBytes - state.trailingLineBreaks;
+  const lineCount =
+    totalBytes === 0 ? 0 : state.lineBreaks - state.trailingLineBreaks + 1;
+  return {
+    preview: state.preview,
+    lineCount,
+    totalBytes,
+    truncated: state.truncated,
+    fullOutputPath: state.truncated ? fullOutputPath : undefined,
+  } satisfies CapturedOutput;
+}
+
+function collectStderr<E, R>(stream: Stream.Stream<Uint8Array, E, R>) {
+  return Stream.runFold(
+    stream,
+    () => Buffer.alloc(0),
+    (captured, chunk) => {
+      if (captured.byteLength >= STDERR_MAX_BYTES) return captured;
+      const remaining = STDERR_MAX_BYTES - captured.byteLength;
+      return Buffer.concat([captured, chunk.subarray(0, remaining)]);
+    },
+  ).pipe(Effect.map((bytes) => bytes.toString("utf8")));
+}
+
+export function executeSearchProcess(options: {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly tempPrefix: string;
+}) {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const directory = yield* fs.makeTempDirectory({
+      prefix: options.tempPrefix,
+    });
+    const fullOutputPath = join(directory, "output.txt");
+    let retainDirectory = false;
+
+    return yield* Effect.gen(function* () {
+      const preview = makePreviewState();
+      const process = yield* ChildProcess.make(options.command, options.args, {
+        cwd: options.cwd,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const result = yield* Effect.all(
+        {
+          exitCode: process.exitCode,
+          stdout: process.stdout.pipe(
+            Stream.tap((chunk) =>
+              Effect.sync(() => observeStdout(preview, chunk)),
+            ),
+            Stream.run(fs.sink(fullOutputPath)),
+          ),
+          stderr: collectStderr(process.stderr),
+        },
+        { concurrency: "unbounded" },
+      );
+      const output = finishStdout(preview, fullOutputPath);
+      retainDirectory = output.truncated;
+      return {
+        code: Number(result.exitCode),
+        stderr: result.stderr,
+        output,
+      };
+    }).pipe(
+      Effect.ensuring(
+        Effect.suspend(() =>
+          retainDirectory
+            ? Effect.void
+            : fs
+                .remove(directory, { recursive: true, force: true })
+                .pipe(Effect.orDie),
+        ),
+      ),
+    );
+  }).pipe(Effect.scoped);
+}
+
+export function discardCapturedOutput(output: CapturedOutput) {
+  if (!output.fullOutputPath) return Effect.void;
+  const directory = dirname(output.fullOutputPath);
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.remove(directory, { recursive: true, force: true });
+  });
+}

package/agent.bak.20260905-190020/extensions/file-search/src/prompt.ts

@@ -0,0 +1,52 @@
+/** Model-facing text for the fd and rg tools. */
+
+export const FD_TOOL_DESCRIPTION =
+  "Find files and directories by name with fd. Respects .gitignore by default. Results are limited to 1000 entries unless a higher limit is given; output is limited to 2000 lines or 50KB, and complete truncated output is saved to a temporary file.";
+
+export const FD_PROMPT_SNIPPET =
+  "Find files and directories by name with fd (fast, gitignore-aware).";
+
+export const FD_PROMPT_GUIDELINES = [
+  "Use fd as the primary tool for discovering files and directories by name, extension, or glob instead of bash with find or ls -R.",
+  "Use rg instead of fd when searching file contents rather than file names.",
+  "Keep using bash for complex multi-step workflows that pipe or post-process file listings.",
+];
+
+export const FD_PARAMETER_DESCRIPTIONS = {
+  pattern:
+    "Regex matched against file names (or a glob when glob is true). Omit to list everything under path.",
+  path: "Directory to search. Defaults to the current working directory.",
+  type: "Only return entries of this type: file, directory, or symlink.",
+  extension: "Only return files with this extension, e.g. 'ts' or 'md'.",
+  glob: "Treat pattern as a glob (e.g. '*.test.ts') instead of a regex.",
+  hidden: "Include hidden files and directories. Defaults to false.",
+  max_depth: "Maximum directory depth to descend (1-64).",
+  limit: "Maximum number of results (1-10000). Defaults to 1000.",
+};
+
+export const RG_TOOL_DESCRIPTION =
+  "Search file contents with ripgrep. Uses smart-case matching, respects .gitignore by default, and returns at most 100 matches per file unless a different limit is given. Output is limited to 2000 lines or 50KB; complete truncated output is saved to a temporary file.";
+
+export const RG_PROMPT_SNIPPET =
+  "Search file contents with ripgrep (fast regex content search).";
+
+export const RG_PROMPT_GUIDELINES = [
+  "Use rg as the primary tool for searching file contents instead of bash with grep.",
+  "Use fd instead of rg when looking for files by name rather than content.",
+  "Set fixed_strings on rg when searching for literal code snippets containing regex metacharacters.",
+  "Keep using bash for complex multi-step workflows that combine searching with other commands.",
+];
+
+export const RG_PARAMETER_DESCRIPTIONS = {
+  pattern: "Regex to search for (literal text when fixed_strings is true).",
+  path: "File or directory to search. Defaults to the current working directory.",
+  glob: "Only search files matching this glob, e.g. '*.ts' or 'src/**'.",
+  file_type:
+    "Only search files of this ripgrep type, e.g. 'ts', 'js', 'py', 'rust'.",
+  case_sensitive:
+    "true forces case-sensitive matching, false forces case-insensitive. Defaults to smart-case.",
+  fixed_strings: "Treat pattern as a literal string instead of a regex.",
+  hidden: "Search hidden files and directories. Defaults to false.",
+  context: "Lines of context to show around each match (0-20).",
+  limit: "Maximum matches per file (1-1000). Defaults to 100.",
+};

package/agent.bak.20260905-190020/extensions/file-search/test/index.spec.ts

@@ -0,0 +1,443 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { Effect, FileSystem } from "effect";
+import { HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import {
+  buildFdArgs,
+  buildRgArgs,
+  FD_DEFAULT_LIMIT,
+  normalizeSearchPath,
+} from "../src/args.ts";
+import {
+  FD_INTEL_DARWIN_VERSION,
+  InstallError,
+  readBoundedResponse,
+  releaseAsset,
+  resolveBinary,
+  TOOL_SPECS,
+  UnsupportedPlatformError,
+  type BinaryEnv,
+  type ReleaseAsset,
+  type ResolvedBinary,
+} from "../src/binaries.ts";
+import { formatCapturedOutput, formatOutput } from "../src/output.ts";
+import { executeSearchProcess } from "../src/process.ts";
+import { installNotifications, makeBinaryInitializers } from "../index.ts";
+
+// --- argument construction -------------------------------------------------
+
+it("fd args: defaults list everything with the default limit", () => {
+  assert.deepEqual(buildFdArgs({}), [
+    "--color=never",
+    "--max-results",
+    String(FD_DEFAULT_LIMIT),
+    "--",
+    "",
+  ]);
+});
+
+it("fd args: all options are translated and pattern stays behind --", () => {
+  const args = buildFdArgs({
+    pattern: "-rf",
+    path: "@src",
+    type: "file",
+    extension: ".ts",
+    glob: true,
+    hidden: true,
+    max_depth: 3,
+    limit: 50,
+  });
+  assert.deepEqual(args, [
+    "--color=never",
+    "--hidden",
+    "--glob",
+    "--type",
+    "f",
+    "--extension",
+    "ts",
+    "--max-depth",
+    "3",
+    "--max-results",
+    "50",
+    "--",
+    "-rf",
+    "src",
+  ]);
+});
+
+it("fd args: out-of-range values are clamped", () => {
+  const args = buildFdArgs({ max_depth: 500, limit: 1_000_000 });
+  assert.deepEqual(args, [
+    "--color=never",
+    "--max-depth",
+    "64",
+    "--max-results",
+    "10000",
+    "--",
+    "",
+  ]);
+});
+
+it("rg args: defaults use smart-case and safe separators", () => {
+  assert.deepEqual(buildRgArgs({ pattern: "--help" }), [
+    "--line-number",
+    "--color=never",
+    "--no-heading",
+    "--with-filename",
+    "--smart-case",
+    "--max-count",
+    "100",
+    "--",
+    "--help",
+  ]);
+});
+
+it("rg args: all options are translated", () => {
+  const args = buildRgArgs({
+    pattern: "TODO",
+    path: "@lib",
+    glob: "*.ts",
+    file_type: "ts",
+    case_sensitive: true,
+    fixed_strings: true,
+    hidden: true,
+    context: 2,
+    limit: 10,
+  });
+  assert.deepEqual(args, [
+    "--line-number",
+    "--color=never",
+    "--no-heading",
+    "--with-filename",
+    "--case-sensitive",
+    "--fixed-strings",
+    "--hidden",
+    "--context",
+    "2",
+    "--glob",
+    "*.ts",
+    "--type",
+    "ts",
+    "--max-count",
+    "10",
+    "--",
+    "TODO",
+    "lib",
+  ]);
+});
+
+it("rg args: case_sensitive false forces ignore-case", () => {
+  const args = buildRgArgs({ pattern: "x", case_sensitive: false });
+  assert.isTrue(args.includes("--ignore-case"));
+  assert.isFalse(args.includes("--smart-case"));
+});
+
+it("path normalization strips leading @ and expands ~", () => {
+  assert.equal(normalizeSearchPath("@src/lib"), "src/lib");
+  assert.equal(normalizeSearchPath("~"), homedir());
+  assert.equal(normalizeSearchPath("~/projects"), join(homedir(), "projects"));
+  assert.equal(normalizeSearchPath(" plain "), "plain");
+});
+
+// --- binary resolution -----------------------------------------------------
+
+function makeEnv(options: {
+  available?: string[];
+  installShouldFail?: boolean;
+}): BinaryEnv & { installs: ReleaseAsset[]; probes: string[] } {
+  const installs: ReleaseAsset[] = [];
+  const probes: string[] = [];
+  const installed = new Set<string>();
+  return {
+    installs,
+    probes,
+    probe: (command) =>
+      Effect.sync(() => {
+        probes.push(command);
+        return (
+          (options.available ?? []).includes(command) || installed.has(command)
+        );
+      }),
+    install: (asset, destination) => {
+      if (options.installShouldFail) {
+        return Effect.fail(new InstallError({ message: "network down" }));
+      }
+      return Effect.sync(() => {
+        installs.push(asset);
+        installed.add(destination);
+      });
+    },
+  };
+}
+
+const darwinArm = { os: "darwin", arch: "arm64" } as const;
+
+it.effect("binary resolution: system fd wins and nothing is installed", () =>
+  Effect.gen(function* () {
+    const env = makeEnv({ available: ["fd"] });
+    const resolved = yield* resolveBinary(
+      TOOL_SPECS.fd,
+      "/repo/bin",
+      darwinArm,
+      env,
+    );
+
+    assert.deepEqual(resolved, {
+      tool: "fd",
+      command: "fd",
+      source: "system",
+    });
+    assert.equal(env.installs.length, 0);
+  }),
+);
+
+it.effect("binary resolution: fdfind is accepted as a system fd", () =>
+  Effect.gen(function* () {
+    const env = makeEnv({ available: ["fdfind"] });
+    const resolved = yield* resolveBinary(
+      TOOL_SPECS.fd,
+      "/repo/bin",
+      darwinArm,
+      env,
+    );
+
+    assert.deepEqual(resolved, {
+      tool: "fd",
+      command: "fdfind",
+      source: "system",
+    });
+    assert.equal(env.installs.length, 0);
+  }),
+);
+
+it.effect("binary resolution: existing bin fallback is used silently", () =>
+  Effect.gen(function* () {
+    const env = makeEnv({ available: ["/repo/bin/rg"] });
+    const resolved = yield* resolveBinary(
+      TOOL_SPECS.rg,
+      "/repo/bin",
+      darwinArm,
+      env,
+    );
+
+    assert.deepEqual(resolved, {
+      tool: "rg",
+      command: "/repo/bin/rg",
+      source: "bundled",
+    });
+    assert.equal(env.installs.length, 0);
+  }),
+);
+
+it.effect(
+  "binary resolution: missing everywhere triggers exactly one install",
+  () =>
+    Effect.gen(function* () {
+      const env = makeEnv({ available: [] });
+      const resolved = yield* resolveBinary(
+        TOOL_SPECS.rg,
+        "/repo/bin",
+        darwinArm,
+        env,
+      );
+
+      assert.equal(resolved.source, "installed");
+      assert.equal(resolved.command, "/repo/bin/rg");
+      assert.equal(env.installs.length, 1);
+      assert.match(
+        env.installs[0].url,
+        /^https:\/\/github\.com\/BurntSushi\/ripgrep\//,
+      );
+    }),
+);
+
+it.effect("binary resolution: install failure surfaces a typed error", () =>
+  Effect.gen(function* () {
+    const env = makeEnv({ available: [], installShouldFail: true });
+    const error = yield* Effect.flip(
+      resolveBinary(TOOL_SPECS.fd, "/repo/bin", darwinArm, env),
+    );
+
+    assert.instanceOf(error, InstallError);
+    assert.equal(error.message, "network down");
+  }),
+);
+
+it.effect(
+  "binary resolution: unsupported platform fails without installing",
+  () =>
+    Effect.gen(function* () {
+      const env = makeEnv({ available: [] });
+      const error = yield* Effect.flip(
+        resolveBinary(
+          TOOL_SPECS.fd,
+          "/repo/bin",
+          { os: "linux", arch: "s390x" },
+          env,
+        ),
+      );
+
+      assert.instanceOf(error, UnsupportedPlatformError);
+      assert.equal(env.installs.length, 0);
+    }),
+);
+
+it.effect("binary resolution: one failed tool does not disable the other", () =>
+  Effect.gen(function* () {
+    const env = makeEnv({
+      available: ["rg"],
+      installShouldFail: true,
+    });
+    const initializers = makeBinaryInitializers("/repo/bin", darwinArm, env);
+
+    const fdError = yield* Effect.flip(initializers.fd);
+    const rg = yield* initializers.rg;
+
+    assert.instanceOf(fdError, InstallError);
+    assert.deepEqual(rg, { tool: "rg", command: "rg", source: "system" });
+  }),
+);
+
+it("release assets cover macOS and Linux on arm64 and x64 over HTTPS", () => {
+  for (const os of ["darwin", "linux"] as const) {
+    for (const arch of ["arm64", "x64"] as const) {
+      for (const tool of ["fd", "rg"] as const) {
+        const asset = releaseAsset(tool, { os, arch });
+        assert.isDefined(asset, `${tool} ${os}/${arch}`);
+        assert.match(asset.url, /^https:\/\//);
+        assert.isTrue(asset.url.endsWith(asset.fileName));
+        assert.match(asset.sha256, /^[a-f0-9]{64}$/);
+      }
+    }
+  }
+});
+
+it("linux assets use statically linked musl builds", () => {
+  const asset = releaseAsset("fd", { os: "linux", arch: "x64" });
+  assert.isTrue(asset?.url.includes("unknown-linux-musl"));
+});
+
+it("Intel macOS uses the latest fd release that publishes that target", () => {
+  const asset = releaseAsset("fd", { os: "darwin", arch: "x64" });
+  assert.equal(asset?.version, FD_INTEL_DARWIN_VERSION);
+});
+
+it.effect(
+  "bounded downloads reject oversized declared and streamed bodies",
+  () =>
+    Effect.gen(function* () {
+      const request = HttpClientRequest.get(
+        "https://example.com/archive.tar.gz",
+      );
+      const declared = HttpClientResponse.fromWeb(
+        request,
+        new Response("small", {
+          headers: { "content-length": "100" },
+        }),
+      );
+      const declaredError = yield* Effect.flip(
+        readBoundedResponse(declared, 10),
+      );
+      assert.match(declaredError.message, /size limit/);
+
+      const streamed = HttpClientResponse.fromWeb(
+        request,
+        new Response("this body is too large"),
+      );
+      const streamedError = yield* Effect.flip(
+        readBoundedResponse(streamed, 5),
+      );
+      assert.match(streamedError.message, /size limit/);
+    }),
+);
+
+// --- notification policy ----------------------------------------------------
+
+it("notifications: only fresh installs notify", () => {
+  const system: ResolvedBinary = {
+    tool: "fd",
+    command: "fd",
+    source: "system",
+  };
+  const bundled: ResolvedBinary = {
+    tool: "rg",
+    command: "/repo/bin/rg",
+    source: "bundled",
+  };
+  const installed: ResolvedBinary = {
+    tool: "rg",
+    command: "/repo/bin/rg",
+    source: "installed",
+    version: "15.2.0",
+  };
+
+  assert.deepEqual(installNotifications([system, bundled]), []);
+  const messages = installNotifications([system, installed]);
+  assert.equal(messages.length, 1);
+  assert.match(messages[0], /downloaded rg 15\.2\.0/);
+});
+
+// --- output truncation -------------------------------------------------------
+
+it.effect("process output is streamed to a complete spill file", () =>
+  Effect.gen(function* () {
+    const result = yield* executeSearchProcess({
+      command: process.execPath,
+      args: ["-e", 'process.stdout.write("line\\n".repeat(3000))'],
+      cwd: process.cwd(),
+      tempPrefix: "pi-search-test-",
+    });
+    const formatted = formatCapturedOutput(result.output);
+
+    assert.equal(result.code, 0);
+    assert.isTrue(formatted.truncated);
+    assert.equal(formatted.lineCount, 3000);
+    assert.match(formatted.text, /2000 of 3000 lines/);
+    assert.isDefined(formatted.fullOutputPath);
+
+    const fs = yield* FileSystem.FileSystem;
+    const fullOutput = yield* fs.readFileString(formatted.fullOutputPath);
+    assert.equal(fullOutput, "line\n".repeat(3000));
+    yield* fs.remove(dirname(formatted.fullOutputPath), {
+      recursive: true,
+      force: true,
+    });
+  }).pipe(Effect.provide(NodeServices.layer)),
+);
+
+it("output: small results pass through untouched", async () => {
+  const formatted = await formatOutput("a.ts\nb.ts\n", {
+    tempPrefix: "pi-fd-",
+    persistFullOutput: () => Promise.reject(new Error("should not persist")),
+  });
+  assert.equal(formatted.text, "a.ts\nb.ts");
+  assert.equal(formatted.lineCount, 2);
+  assert.isFalse(formatted.truncated);
+  assert.isUndefined(formatted.fullOutputPath);
+});
+
+it("output: oversized results are truncated and persisted", async () => {
+  const bigOutput = Array.from({ length: 3000 }, (_, i) => `file-${i}.ts`).join(
+    "\n",
+  );
+  let persisted: string | undefined;
+  const formatted = await formatOutput(bigOutput, {
+    tempPrefix: "pi-fd-",
+    persistFullOutput: async (full) => {
+      persisted = full;
+      return "/tmp/fake/output.txt";
+    },
+  });
+  assert.isTrue(formatted.truncated);
+  assert.equal(formatted.fullOutputPath, "/tmp/fake/output.txt");
+  assert.equal(persisted, bigOutput);
+  assert.match(formatted.text, /\[Output truncated: 2000 of 3000 lines/);
+  assert.match(
+    formatted.text,
+    /Full output saved to: \/tmp\/fake\/output\.txt\]/,
+  );
+  const shownLines = formatted.text.split("\n");
+  assert.equal(shownLines[0], "file-0.ts");
+});

package/agent.bak.20260905-190020/extensions/file-search/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "@effect/language-service" }]
+  },
+  "include": ["index.ts", "src/**/*.ts", "test/**/*.spec.ts"]
+}

package/agent.bak.20260905-190020/extensions/goal/README.md

@@ -0,0 +1,50 @@
+# goal
+
+Keep the agent working until a goal is achieved.
+
+## Command
+
+| Command | Action |
+|---|---|
+| `/goal <prompt>` | Runs the workflow below, looping until you confirm the goal is achieved |
+| `/goal` | Prompts for the goal interactively, then runs the same workflow |
+
+`/goal` with no argument opens an input dialog; if the dialog is cancelled or
+left empty, nothing runs.
+
+## Workflow
+
+`/goal <prompt>` injects an instruction into the main agent that runs four
+phases in order:
+
+1. **Research** — web-search the goal to ground the design.
+2. **Design** — follow the `brainstorming` skill; present the design for
+   approval, then save the design doc to `docs/superpowers/specs/`.
+3. **Plan** — follow the `writing-plans` skill; save a bite-sized plan to
+   `docs/superpowers/plans/`.
+4. **Implement and verify** — write the code, tests, and docs; run them and
+   fix failures until the goal actually works.
+
+### The loop
+
+After the agent settles, `/goal` asks you what to do next:
+
+- **Continue working toward the goal** — re-engages the agent to keep going,
+  respecting the phase gates (it won't skip design approval).
+- **Goal achieved - stop** — ends the loop.
+- **Pause - stop checking** — ends the loop and leaves you to take over
+  manually.
+
+The loop runs in the interactive TUI (it needs to ask you). In RPC and
+print/JSON modes there is no dialog, so the agent works a single pass and the
+loop ends. The workflow always stops after Phase 2 and waits for you to approve
+the design doc before planning and implementing.
+
+## Files
+
+- `index.ts` — registers the `/goal` command, builds the phase instruction,
+  and re-engages the agent on `agent_settled`
+- `README.md` — this file
+
+Nothing is written into the extension folder; the design and plan land in the
+project's `docs/superpowers/` tree (the skills' default locations).