monkeyshape 0.0.0-stage → 0.2.0

package/src/adapters/reviews.ts

@@ -0,0 +1,170 @@
+/**
+ * `mshape review <n>` and `mshape review rm <n>`: a pull request's head in a detached worktree
+ * beside the tracks, with `tracks.sharedPaths` linked in, for the `review-pr` skill. A review is
+ * not a track: no branch, no handoff, no label. Its state lives on the pull request, and the
+ * worktree is scratch, removed when the review ends. Paths come from `src/core/layout.ts`.
+ */
+import { posix } from "node:path";
+import { Effect } from "effect";
+import { PR_NUMBER, reviewPath, reviewRef } from "../core/layout.ts";
+import { sharedPathProblems } from "../core/tracks.ts";
+import { loadConfig } from "./config.ts";
+import { git, gitOk, ignored, lexists, linkTo, locate, refuse, worktrees } from "./tracks.ts";
+
+/** Pull requests are fetched from here, as GitHub publishes them: `refs/pull/<n>/head`. */
+const REMOTE = "origin";
+
+const numberProblem = (pr: string) =>
+  PR_NUMBER.test(pr)
+    ? Effect.void
+    : refuse(`give the pull request's number, e.g. \`mshape review 12\` (got '${pr}')`);
+
+/** Fetch the head into the review's own ref; the commit it names. */
+const fetchHead = (repo: string, pr: string) =>
+  Effect.gen(function* () {
+    const ref = reviewRef(pr);
+    const fetched = yield* git(repo, [
+      "fetch",
+      "--quiet",
+      "--no-write-fetch-head",
+      REMOTE,
+      `+refs/pull/${pr}/head:${ref}`,
+    ]);
+    if (fetched.code !== 0)
+      return yield* refuse(
+        `could not fetch pull request #${pr} from \`${REMOTE}\` (as \`refs/pull/${pr}/head\`, which GitHub publishes): ${fetched.stderr || `exit ${fetched.code}`}`,
+      );
+    return yield* gitOk(repo, ["rev-parse", `${ref}^{commit}`]);
+  });
+
+/**
+ * `tracks.sharedPaths` linked into the review's worktree, after a create or a move alike: a path
+ * the head tracks is the PR's own (git put it there) and only noted; a missing link is made.
+ */
+const linkShared = (repo: string, path: string, pr: string, shared: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const said: Array<string> = [];
+    for (const entry of shared) {
+      const target = `${repo}/${entry}`;
+      if ((yield* git(path, ["cat-file", "-e", `HEAD:${entry}`])).code === 0)
+        said.push(
+          `note: shared path \`${entry}\` is tracked at the head of #${pr}; not linked. A shared path must be gitignored, never tracked`,
+        );
+      else if (yield* lexists(`${path}/${entry}`)) continue;
+      else if (!(yield* lexists(target)))
+        said.push(`note: shared path \`${entry}\` is missing in ${repo}; not linked`);
+      else {
+        yield* linkTo(repo, `${path}/${entry}`, target);
+        said.push(`linked ${path}/${entry} -> ${target}`);
+      }
+    }
+    return said;
+  });
+
+/**
+ * Puts an existing review worktree exactly at `head`. It is scratch, so edits to tracked files
+ * are discarded, after `say` lists them; untracked probes stay, unless `head` tracks the same
+ * path. Never git's "commit or stash" advice: the stash is shared by every worktree.
+ */
+const resetTo = (path: string, head: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    const status = yield* git(path, ["status", "--porcelain", "--untracked-files=all"]);
+    for (const line of status.stdout.split("\n").filter((line) => line.trim() !== "")) {
+      const file = line.slice(3);
+      if (!line.startsWith("??")) yield* say(`discarding in ${path}: ${line.trim()}`);
+      else if ((yield* git(path, ["cat-file", "-e", `${head}:${file}`])).code === 0)
+        yield* say(`overwriting in ${path}: ${file}, which the head tracks`);
+    }
+    yield* gitOk(path, ["checkout", "--quiet", "--force", "--detach", head]);
+  });
+
+/**
+ * Creates the review's worktree at the pull request's head, or puts an existing one there,
+ * printing the previous head: a re-review checks a regression test against both.
+ */
+export const reviewNew = (cwd: string, pr: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    yield* numberProblem(pr);
+    const { repo } = yield* locate(cwd);
+    const shared = (yield* loadConfig(repo)).tracks.sharedPaths;
+    const problems = sharedPathProblems(shared);
+    if (problems.length > 0) return yield* refuse(problems.join("\n"));
+    const path = reviewPath(repo, pr);
+    const registered = (yield* worktrees(repo)).some((worktree) => worktree.path === path);
+    const present = yield* lexists(path);
+    if (registered && !present)
+      return yield* refuse(
+        `git still has a worktree registered at ${path}: run \`git worktree prune\`, then this again`,
+      );
+    if (!registered && present)
+      return yield* refuse(
+        `${path} exists but git has no worktree there: remove it, then this again`,
+      );
+
+    const head = yield* fetchHead(repo, pr);
+    if (registered) {
+      const before = yield* gitOk(path, ["rev-parse", "HEAD"]);
+      yield* resetTo(path, head, say);
+      const linked = yield* linkShared(repo, path, pr, shared);
+      return [
+        ...(before === head
+          ? [`${path} is at the head of #${pr}: ${head}`]
+          : [`moved ${path} to the head of #${pr}: ${head}`, `previous head: ${before}`]),
+        ...linked,
+        `next: cd ${path}`,
+      ].join("\n");
+    }
+
+    const notes: Array<string> = [];
+    if (!(yield* ignored(repo, posix.relative(repo, path))))
+      notes.push(
+        `note: the worktrees directory (\`${posix.relative(repo, path)}\`) is not gitignored; add it to .gitignore`,
+      );
+    yield* gitOk(repo, ["worktree", "add", "--quiet", "--detach", path, head]);
+    const created = `created ${path} at the head of #${pr}: ${head}`;
+    const linked = yield* linkShared(repo, path, pr, shared).pipe(
+      Effect.catch((error) =>
+        refuse(
+          [
+            `review ${pr}: stopped: ${error.message}`,
+            `done: ${created}`,
+            `undo with \`mshape review rm ${pr}\``,
+          ].join("\n  "),
+        ),
+      ),
+    );
+    return [...notes, created, ...linked, `next: cd ${path}`].join("\n");
+  });
+
+/**
+ * Removes the review's worktree and its fetched ref. Everything in a review worktree is scratch,
+ * so changes in it are discarded, after `say` lists them. Shared data is only ever linked, and
+ * removing the worktree removes the links, never their targets.
+ */
+export const reviewRm = (cwd: string, pr: string, say: (line: string) => Effect.Effect<void>) =>
+  Effect.gen(function* () {
+    yield* numberProblem(pr);
+    const { repo } = yield* locate(cwd);
+    const path = reviewPath(repo, pr);
+    const registered = (yield* worktrees(repo)).some((worktree) => worktree.path === path);
+    const present = yield* lexists(path);
+    if (!registered && present)
+      return yield* refuse(
+        `${path} exists but git has no worktree there, so it isn't a review's: left alone`,
+      );
+    const removed: Array<string> = [];
+    if (registered && present) {
+      const status = yield* gitOk(path, ["status", "--porcelain", "--untracked-files=all"]);
+      const changes = status.split("\n").filter((line) => line.trim() !== "");
+      yield* Effect.forEach(changes, (line) => say(`discarding in ${path}: ${line.trim()}`));
+      yield* gitOk(repo, ["worktree", "remove", "--force", path]);
+      removed.push(`removed ${path}`);
+    }
+    const ref = reviewRef(pr);
+    if ((yield* git(repo, ["show-ref", "--verify", "--quiet", ref])).code === 0) {
+      yield* gitOk(repo, ["update-ref", "-d", ref]);
+      removed.push(`removed ${ref}`);
+    }
+    yield* gitOk(repo, ["worktree", "prune"]);
+    return removed.length > 0 ? removed.join("\n") : `no review of #${pr} here; nothing removed`;
+  });

package/src/adapters/skills.ts

@@ -0,0 +1,113 @@
+/** Installs the package's shared skills into a repo, and links them where Claude Code looks. */
+import { lstat, mkdir, readlink, rm, symlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { Effect } from "effect";
+import {
+  CLAUDE_SKILLS_LINK,
+  CLAUDE_SKILLS_TARGET,
+  SKILLS_DIR,
+  SKILLS_MANIFEST,
+} from "../core/layout.ts";
+import type { SkillFiles, SkillsLink, SkillsSnapshot } from "../core/model.ts";
+import { parseManifest, type SkillSync, syncSkills } from "../core/skills.ts";
+import { WorkspaceError } from "../schemas/errors.ts";
+
+/** Whether anything is at `path`, a dangling link included. */
+const present = (path: string): Promise<boolean> =>
+  lstat(path).then(
+    () => true,
+    () => false,
+  );
+
+/**
+ * Every file under `dir` as bytes, by relative path; a missing directory has none. Symlinks
+ * are followed, so a skill linked in from elsewhere is read like any other.
+ */
+export const readTree = (dir: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const files = new Map<string, Uint8Array>();
+      if (!(await present(dir))) return files as SkillFiles;
+      const glob = new Bun.Glob("**").scan({ cwd: dir, dot: true, followSymlinks: true });
+      for await (const path of glob) files.set(path, await Bun.file(`${dir}/${path}`).bytes());
+      return files as SkillFiles;
+    },
+    catch: (cause) => new WorkspaceError({ operation: "read", path: dir, reason: String(cause) }),
+  });
+
+export interface SkillsInstall {
+  readonly sync: SkillSync;
+  /** Whether `.claude/skills` had to be created. */
+  readonly linked: boolean;
+}
+
+/**
+ * Brings `<repo>/.agents/skills` up to the package's `skills/`, and creates the
+ * `.claude/skills` link if it is missing. An existing link or directory there is left alone:
+ * `mshape check` says what is wrong with it.
+ */
+export const installSkills = (shippedDir: string, repo: string) =>
+  Effect.gen(function* () {
+    const installedDir = `${repo}/${SKILLS_DIR}`;
+    const installed = yield* readTree(installedDir);
+    const manifest = installed.get(SKILLS_MANIFEST);
+    // An unreadable manifest can't tell shared skills from the repo's own: touch nothing.
+    if (manifest !== undefined && parseManifest(manifest) === undefined)
+      return yield* Effect.fail(
+        new WorkspaceError({
+          operation: "sync skills",
+          path: `${SKILLS_DIR}/${SKILLS_MANIFEST}`,
+          reason: `is not the list sync writes, so nothing was changed. Restore it with \`git checkout -- ${SKILLS_DIR}/${SKILLS_MANIFEST}\``,
+        }),
+      );
+    const sync = syncSkills(yield* readTree(shippedDir), installed);
+    const link = `${repo}/${CLAUDE_SKILLS_LINK}`;
+    const linked = yield* Effect.tryPromise({
+      try: async () => {
+        await mkdir(installedDir, { recursive: true });
+        for (const path of sync.remove) await rm(`${installedDir}/${path}`);
+        for (const skill of sync.retired) {
+          const target = resolve(installedDir, skill);
+          // Belt and braces: syncSkills only retires installed skill directories.
+          if (dirname(target) !== resolve(installedDir))
+            throw new Error(`refusing to remove ${target}: not a skill directory`);
+          await rm(target, { recursive: true });
+        }
+        for (const [path, bytes] of sync.write) {
+          await mkdir(dirname(`${installedDir}/${path}`), { recursive: true });
+          await Bun.write(`${installedDir}/${path}`, bytes);
+        }
+        if (await present(link)) return false;
+        await mkdir(dirname(link), { recursive: true });
+        await symlink(CLAUDE_SKILLS_TARGET, link);
+        return true;
+      },
+      catch: (cause) =>
+        new WorkspaceError({ operation: "install skills", path: repo, reason: String(cause) }),
+    });
+    return { sync, linked } satisfies SkillsInstall;
+  });
+
+const linkAt = (path: string): Promise<SkillsLink> =>
+  lstat(path).then(
+    async (info): Promise<SkillsLink> =>
+      info.isSymbolicLink()
+        ? { kind: "link", target: await readlink(path) }
+        : info.isDirectory()
+          ? { kind: "directory" }
+          : { kind: "other" },
+    (): SkillsLink => ({ kind: "missing" }),
+  );
+
+/** What `mshape check` needs to verify the install, read from disk as agents will see it. */
+export const loadSkills = (shippedDir: string, repo: string) =>
+  Effect.gen(function* () {
+    const link = yield* Effect.promise(() => linkAt(`${repo}/${CLAUDE_SKILLS_LINK}`));
+    return {
+      link,
+      installed: yield* readTree(`${repo}/${SKILLS_DIR}`),
+      claudeDirectory:
+        link.kind === "directory" ? yield* readTree(`${repo}/${CLAUDE_SKILLS_LINK}`) : new Map(),
+      shipped: yield* readTree(shippedDir),
+    } satisfies SkillsSnapshot;
+  });