monkeyshape 0.1.0 → 0.2.0

package/src/core/tracks.ts

@@ -0,0 +1,358 @@
+/**
+ * The decisions behind `mshape track`: which shared paths are allowed, which directory is a
+ * track, what `rm` may delete and in what order, and how `list` reads. Git and the filesystem
+ * are read by `src/adapters/tracks.ts`, which hands the facts here.
+ */
+import type { ResolvedConfig } from "../schemas/config.ts";
+import { beadsBlocker } from "./check.ts";
+import {
+  AGENTS_HANDOFFS_LINK,
+  HANDOFFS_LINK,
+  TRACK_NAME,
+  trackBranch,
+  trackLabel,
+  trackOf,
+  WORKTREES_DIR,
+  worktreePath,
+} from "./layout.ts";
+import type { Integration } from "./model.ts";
+
+/** A worktree as `git worktree list --porcelain` reports it. */
+export interface Worktree {
+  readonly path: string;
+  /** Short name, e.g. `track/docs`; undefined when detached or bare. */
+  readonly branch: string | undefined;
+  /** Registered, but its directory is gone: `git worktree prune` drops it. */
+  readonly prunable: boolean;
+}
+
+export const parseWorktrees = (porcelain: string): ReadonlyArray<Worktree> =>
+  porcelain
+    .split(/\n\n+/)
+    .map((block) => block.split("\n"))
+    .flatMap((lines) => {
+      const path = lines.find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
+      const ref = lines.find((line) => line.startsWith("branch "))?.slice("branch ".length);
+      return path === undefined
+        ? []
+        : [
+            {
+              path,
+              branch: ref?.startsWith("refs/heads/") ? ref.slice(11) : ref,
+              prunable: lines.some((line) => line === "prunable" || line.startsWith("prunable ")),
+            },
+          ];
+    });
+
+export const nameProblem = (track: string): string | undefined =>
+  TRACK_NAME.test(track)
+    ? undefined
+    : `\`${track}\` is not a track name: use lowercase words joined by hyphens, like \`docs\` or \`cross-module\``;
+
+/**
+ * `tracks.sharedPaths` as a whole. The schema has already made each entry normal; here the
+ * entries must not repeat or nest, nor overlap what the track commands manage: `.git`, the
+ * handoff links and the worktrees directory, which linked into a worktree would contain itself.
+ */
+export const sharedPathProblems = (paths: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const within = (path: string, root: string) => path === root || path.startsWith(`${root}/`);
+  const problems: Array<string> = [];
+  paths.forEach((path, index) => {
+    if (paths.indexOf(path) !== index) problems.push(`\`${path}\` is listed twice`);
+    for (const reserved of [".git", HANDOFFS_LINK, AGENTS_HANDOFFS_LINK, WORKTREES_DIR])
+      if (within(path, reserved) || within(reserved, path))
+        problems.push(
+          `\`${path}\` overlaps \`${reserved}\`, which the track commands manage themselves: share something narrower`,
+        );
+    for (const other of paths)
+      if (other !== path && within(path, other))
+        problems.push(`\`${path}\` lies under \`${other}\`: list only \`${other}\``);
+  });
+  return problems.map((problem) => `tracks.sharedPaths in shape.config.ts: ${problem}`);
+};
+
+/** Why the directory `toplevel` is or is not a track: the name, or which check failed. */
+export const currentTrack = (
+  repo: string,
+  toplevel: string,
+  worktrees: ReadonlyArray<Worktree>,
+): { readonly track: string } | { readonly reason: string } => {
+  const track = trackOf(repo, toplevel);
+  if (track === undefined)
+    return {
+      reason: `${toplevel} is not a track worktree: tracks live at ${worktreePath(repo, "<track>")}`,
+    };
+  const registered = worktrees.find((worktree) => worktree.path === toplevel);
+  if (registered === undefined)
+    return {
+      reason: `${toplevel} is named like track \`${track}\`, but git has no worktree registered there for ${repo}`,
+    };
+  if (registered.branch !== trackBranch(track))
+    return {
+      reason: `${toplevel} is on ${registered.branch === undefined ? "a detached HEAD" : `branch \`${registered.branch}\``}, not \`${trackBranch(track)}\``,
+    };
+  return { track };
+};
+
+/** A bead that isn't closed, as `bd list --json` reports it. */
+export interface OpenBead {
+  readonly id: string;
+  readonly title: string;
+  readonly status: string;
+}
+
+/**
+ * Beads that aren't closed, by the track each `track:<name>` label names: a bead labelled for
+ * two tracks belongs to both. Rows that aren't beads are skipped.
+ */
+export const openBeadsByTrack = (
+  rows: ReadonlyArray<unknown>,
+): ReadonlyMap<string, ReadonlyArray<OpenBead>> => {
+  const byTrack = new Map<string, Array<OpenBead>>();
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null) continue;
+    const { id, title, status, labels } = row as Record<string, unknown>;
+    if (typeof id !== "string" || status === "closed" || !Array.isArray(labels)) continue;
+    const bead = {
+      id,
+      title: typeof title === "string" ? title : "",
+      status: typeof status === "string" ? status : "unknown",
+    };
+    for (const label of labels) {
+      const track = typeof label === "string" ? /^track:(.+)$/.exec(label)?.[1] : undefined;
+      if (track !== undefined && TRACK_NAME.test(track))
+        byTrack.set(track, [...(byTrack.get(track) ?? []), bead]);
+    }
+  }
+  return byTrack;
+};
+
+/**
+ * What beads said about a track's open work: the integration state `mshape check` uses, the
+ * config's `beads` setting, and, when the state is ok, the track's beads that aren't closed.
+ */
+export interface BeadsCheck {
+  readonly integration: Integration;
+  readonly setting: ResolvedConfig["beads"];
+  readonly open: ReadonlyArray<OpenBead>;
+}
+
+/** What `track rm` found, before touching anything. */
+export interface RmFacts {
+  readonly track: string;
+  readonly worktreePath: string;
+  /** The worktree git has registered at the track's path, if any. */
+  readonly worktree: Worktree | undefined;
+  /** Something is at the track's path on disk. */
+  readonly pathExists: boolean;
+  /** `git status --porcelain` lines in the worktree; empty when clean or gone. */
+  readonly changes: ReadonlyArray<string>;
+  /** Set when `git status` failed in the worktree: its changes can't be known. */
+  readonly statusError: string | undefined;
+  readonly branchExists: boolean;
+  /** Commits on the branch in none of `mergeTargets`. */
+  readonly unmerged: number;
+  /** The branch's work is in a target anyway: merged, rebased or squashed there. */
+  readonly merged: boolean;
+  /** What counts as merged, as people say them: `main`, and `origin/main` when it exists. */
+  readonly mergeTargets: ReadonlyArray<string>;
+  /** Other checkouts that have the branch checked out. */
+  readonly branchCheckedOutAt: ReadonlyArray<Worktree>;
+  readonly handoffPath: string;
+  readonly handoffExists: boolean;
+  /** Beads labelled `track:<track>` that aren't closed: removing the track would orphan them. */
+  readonly beads: BeadsCheck;
+  readonly force: boolean;
+  readonly keepHandoff: boolean;
+}
+
+export type RmStep =
+  | { readonly kind: "worktree"; readonly path: string; readonly force: boolean }
+  | { readonly kind: "branch"; readonly name: string }
+  | { readonly kind: "handoff"; readonly path: string };
+
+export interface RmPlan {
+  /** Any refusal means nothing is touched. */
+  readonly refusals: ReadonlyArray<string>;
+  /** Said before the steps run: what `--force` is about to discard. */
+  readonly warnings: ReadonlyArray<string>;
+  /** In order: worktree, branch, handoff. `git worktree prune` follows them. */
+  readonly steps: ReadonlyArray<RmStep>;
+  /** What stays, and why, when nothing is wrong with keeping it. */
+  readonly kept: ReadonlyArray<string>;
+  /** Said whether or not it refuses: a check that couldn't run. */
+  readonly notes: ReadonlyArray<string>;
+}
+
+export const describeStep = (step: RmStep): string =>
+  step.kind === "worktree"
+    ? `worktree ${step.path}`
+    : step.kind === "branch"
+      ? `branch \`${step.name}\``
+      : `handoff ${step.path}`;
+
+/**
+ * Only the track's own worktree, branch and handoff are ever candidates, so the main
+ * checkout, other tracks and the handoff store are out of reach by construction. `--force`
+ * overrides exactly two refusals: uncommitted changes and unmerged commits, both as listed.
+ * Changes that can't be read are not changes the user agreed to discard. Open beads are never
+ * overridden: closing or moving each one is a single command, and removing the track would
+ * leave them with no one to do them.
+ */
+export const planRm = (facts: RmFacts): RmPlan => {
+  const branch = trackBranch(facts.track);
+  const refusals: Array<string> = [];
+  const warnings: Array<string> = [];
+  const kept: Array<string> = [];
+  const steps: Array<RmStep> = [];
+  const label = trackLabel(facts.track);
+  const notes: Array<string> = [];
+  const listBeads = `bd list --label ${label} --status open,in_progress,blocked,deferred`;
+  const { integration, setting, open } = facts.beads;
+  const blocker = beadsBlocker(setting, integration);
+  if (blocker === undefined && integration.state === "absent")
+    notes.push("this repo has no beads (no .beads/), so open beads were not checked");
+  if (blocker === undefined && integration.state === "unavailable")
+    notes.push(
+      `open beads were not checked: ${integration.reason}. Check by hand with \`${listBeads}\``,
+    );
+
+  if (
+    facts.worktree === undefined &&
+    !facts.pathExists &&
+    !facts.branchExists &&
+    !facts.handoffExists
+  )
+    return {
+      refusals: [
+        `there is no track \`${facts.track}\`: no worktree, no branch \`${branch}\`, no handoff`,
+      ],
+      warnings,
+      steps,
+      kept,
+      notes: [],
+    };
+
+  if (facts.worktree === undefined && facts.pathExists)
+    refusals.push(
+      `${facts.worktreePath} exists but git has no worktree registered there: look inside and remove it by hand`,
+    );
+  if (facts.worktree !== undefined && facts.worktree.branch !== branch)
+    refusals.push(
+      `the worktree at ${facts.worktreePath} is on ${facts.worktree.branch === undefined ? "a detached HEAD" : `\`${facts.worktree.branch}\``}, not \`${branch}\`: check it out there, or remove it by hand`,
+    );
+  for (const elsewhere of facts.branchCheckedOutAt)
+    refusals.push(
+      elsewhere.prunable
+        ? `\`${branch}\` is still registered as checked out at ${elsewhere.path}, which no longer exists: run \`git worktree prune\`, then retry`
+        : `\`${branch}\` is checked out at ${elsewhere.path}: switch that checkout to another branch first`,
+    );
+  if (integration.state === "ok" && open.length > 0)
+    refusals.push(
+      [
+        `\`${label}\` still labels ${open.length} bead(s) that aren't closed, and removing the track would orphan them:`,
+        ...open.map((bead) => `  ${bead.id} (${bead.status}) ${bead.title}`),
+        `close each one that's done (\`bd close <id>\`), or move it to the track that will do it (\`bd update <id> --remove-label ${label} --add-label track:<other>\`). --force doesn't override this`,
+      ].join("\n    "),
+    );
+  // A failing bd hides the beads, so there is nothing for --force to agree to discard.
+  if (blocker === "failed" && integration.state === "failed")
+    refusals.push(
+      `bd failed, so the open beads labelled \`${label}\` can't be seen: ${integration.reason}. Get \`bd\` working, then retry; --force doesn't override this`,
+    );
+  if (blocker === "required")
+    refusals.push(
+      integration.state === "absent"
+        ? `shape.config.ts requires beads, but the repo has no .beads/config.yaml, so the open beads labelled \`${label}\` can't be checked: set beads up, or set \`beads: "optional"\``
+        : `shape.config.ts requires beads, but ${"reason" in integration ? integration.reason : "it didn't answer"}, so the open beads labelled \`${label}\` can't be checked: get \`bd\` working, then retry`,
+    );
+  if (facts.statusError !== undefined)
+    refusals.push(
+      `can't read the state of ${facts.worktreePath} (\`git status\` failed: ${facts.statusError}), so --force can't know what it would discard: inspect it by hand`,
+    );
+
+  if (facts.changes.length > 0) {
+    const shown = facts.changes.slice(0, 5).join(", ");
+    const more = facts.changes.length > 5 ? ` and ${facts.changes.length - 5} more` : "";
+    if (facts.force)
+      warnings.push(`discarding uncommitted changes in ${facts.worktreePath}: ${shown}${more}`);
+    else
+      refusals.push(
+        `${facts.worktreePath} has uncommitted or untracked changes (${shown}${more}): commit or discard them, or pass --force to discard them`,
+      );
+  }
+  if (facts.branchExists && !facts.merged) {
+    const targets = facts.mergeTargets.map((target) => `\`${target}\``).join(" or ");
+    if (facts.force)
+      warnings.push(`deleting \`${branch}\` with ${facts.unmerged} commit(s) not in ${targets}`);
+    else
+      refusals.push(
+        `\`${branch}\` has ${facts.unmerged} commit(s) not in ${targets}, and its work isn't there by a merge, a rebase or a squash either: merge it first, or pass --force to delete it`,
+      );
+  }
+
+  if (facts.worktree !== undefined)
+    steps.push({ kind: "worktree", path: facts.worktreePath, force: facts.force });
+  if (facts.branchExists) steps.push({ kind: "branch", name: branch });
+  if (facts.handoffExists) {
+    if (facts.keepHandoff) kept.push(`handoff ${facts.handoffPath} (--keep-handoff)`);
+    else steps.push({ kind: "handoff", path: facts.handoffPath });
+  }
+  return refusals.length > 0
+    ? { refusals, warnings: [], steps: [], kept: [], notes }
+    : { refusals, warnings, steps, kept, notes };
+};
+
+/** One line per track in `track list`. */
+export interface TrackRow {
+  readonly track: string;
+  readonly status: "stub" | "active" | "invalid" | "none";
+  /** Beads labelled `track:<track>` that aren't closed; undefined when beads couldn't say. */
+  readonly beads: number | undefined;
+  /** Commits not in `main`; undefined without a branch. */
+  readonly ahead: number | undefined;
+  /** Merged, rebased or squashed into a target; undefined without a branch. */
+  readonly merged?: boolean | undefined;
+  /** Relative to the main checkout; undefined without a worktree. */
+  readonly worktree: string | undefined;
+  /** Set when the worktree is on another branch than `track/<track>`. */
+  readonly worktreeBranch?: string | undefined;
+  /** Why the handoff is `invalid`: `parseHandoff`'s problems, printed under the row. */
+  readonly problems?: ReadonlyArray<string> | undefined;
+}
+
+export const formatTracks = (rows: ReadonlyArray<TrackRow>): string => {
+  if (rows.length === 0) return "no tracks: start one with `mshape track new <name>`";
+  const table = [
+    ["track", "status", "beads", "ahead", "merged", "worktree"],
+    ...rows.map((row) => [
+      row.track,
+      row.status,
+      row.beads === undefined ? "-" : String(row.beads),
+      row.ahead === undefined ? "-" : String(row.ahead),
+      row.merged === undefined ? "-" : row.merged ? "yes" : "no",
+      row.worktree === undefined
+        ? "-"
+        : row.worktreeBranch === undefined
+          ? row.worktree
+          : `${row.worktree} (on ${row.worktreeBranch})`,
+    ]),
+  ];
+  const widths =
+    table[0]?.map((_, column) => Math.max(...table.map((cells) => cells[column]?.length ?? 0))) ??
+    [];
+  const line = (cells: ReadonlyArray<string>) =>
+    cells
+      .map((cell, column) =>
+        column === cells.length - 1 ? cell : cell.padEnd((widths[column] ?? 0) + 2),
+      )
+      .join("");
+  // Each problem names the file through the `.handoffs` link, which every checkout has.
+  return [
+    line(table[0] ?? []),
+    ...rows.flatMap((row, index) => [
+      line(table[index + 1] ?? []),
+      ...(row.problems ?? []).map((problem) => `  ${HANDOFFS_LINK}/${row.track}.md: ${problem}`),
+    ]),
+  ].join("\n");
+};

package/src/schemas/config.ts

@@ -36,6 +36,14 @@ export const RuleSetting = Schema.Struct({
   allow: Schema.optionalKey(Schema.Array(Allowance)),
 });
 
+/**
+ * Repo-relative and already normal: segments joined by single `/`, none empty, `.` or `..`.
+ * So `cases` and `data/large` pass; `/abs`, `../x`, `.`, `./x`, `data//large`, `cases/` don't.
+ */
+export const SharedPath = Schema.String.check(
+  Schema.isPattern(/^(?!\.\.?(?:\/|$))[^/\0]+(?:\/(?!\.\.?(?:\/|$))[^/\0]+)*$/),
+);
+
 export const ForbiddenPattern = Schema.Struct({
   /** A regular expression source, matched against docs and code comments. */
   pattern: Schema.String,
@@ -61,6 +69,16 @@ export const ShapeConfig = Schema.Struct({
   rules: Schema.optionalKey(Schema.Record(Schema.String, RuleSetting)),
   /** `required` fails the check when bd can't answer, so a green CI run means beads was checked. */
   beads: Schema.optionalKey(Schema.Literals(["optional", "required"])),
+  tracks: Schema.optionalKey(
+    Schema.Struct({
+      /**
+       * Gitignored paths every track worktree shares with the main checkout, such as a large
+       * dataset: repo-relative, no `..`. `mshape track new` links `<worktree>/<path>` to
+       * `<main>/<path>`. The semantics are in plan/MILESTONE.md, "Interfaces the tracks share".
+       */
+      sharedPaths: Schema.optionalKey(Schema.Array(SharedPath)),
+    }),
+  ),
   refs: Schema.optionalKey(
     Schema.Struct({
       docs: Schema.optionalKey(Globs),
@@ -101,6 +119,7 @@ export interface ResolvedConfig {
   };
   readonly entry: ReadonlyArray<string>;
   readonly beads: "optional" | "required";
+  readonly tracks: { readonly sharedPaths: ReadonlyArray<string> };
   readonly arch:
     | {
         readonly root: string;
@@ -154,6 +173,7 @@ export const resolveConfig = (config: ShapeConfig): ResolvedConfig => ({
   },
   entry: config.entry ?? ["src/cli/**", "tools/**"],
   beads: config.beads ?? "optional",
+  tracks: { sharedPaths: config.tracks?.sharedPaths ?? [] },
   arch:
     config.arch === undefined
       ? undefined

package/src/schemas/errors.ts

@@ -20,3 +20,12 @@ export class ConfigError extends Schema.TaggedError<ConfigError>()("ConfigError"
     return `${this.path}: ${this.reason}`;
   }
 }
+
+/** A track command refused, or stopped partway; the message says which, and what to do. */
+export class TrackError extends Schema.TaggedError<TrackError>()("TrackError", {
+  reason: Schema.String,
+}) {
+  override get message(): string {
+    return this.reason;
+  }
+}

package/template/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What changed, and why
+
+## Gate
+
+<!-- The tail of `bun run check`. -->
+
+## Bug class a new check closes
+
+<!-- Or "none". -->
+
+## Not done

package/template/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+      - run: bun install --frozen-lockfile
+      - run: bun run check

package/template/AGENTS.md

@@ -0,0 +1,37 @@
+# {{name}}
+
+What this repo is, in two sentences. `/roadmap` fills this in from the first brain-dump.
+
+## Commands
+
+| Command | What |
+|---|---|
+| `bun install --frozen-lockfile` | Install (pinned toolchain) |
+| `bun run check` | The gate: typecheck, biome, `mshape check`, tests. Green before every PR. |
+| `bun run fix` | Apply biome formatting and safe fixes |
+| `bd ready` | Work that is ready to pick up |
+
+## Where to start
+
+- `shape.config.ts`: the module map. It is the layout; nothing else restates it.
+- `DECISIONS.md`: live decisions, each with the check that enforces it.
+- `docs/roadmap.md`: direction, with a status table first. Direction, not rules: never cite
+  its sections from code or here.
+- `plan/`: the current milestone. In a track worktree, your handoff is `.handoffs/<track>.md`.
+
+## Gotchas
+
+None yet. Add one when a mistake is worth a line, and replace it with a check when it can be.
+
+## Decision authority
+
+Needs the maintainer: priorities, publishing, a new runtime dependency, anything public
+beyond a PR. Agents decide everything else and explain it in the PR body.
+
+## Working agreements
+
+- Written text is a hypothesis; code and tests are the truth. When a doc, decision or bead
+  disagrees with the code, fix the text and carry on.
+- One fact, one home. Link to `DECISIONS.md` entries by slug; never restate them.
+- Agents commit, push and open PRs; the maintainer merges. The PR body is the narrative.
+- Work is tracked in beads (`bd ready`). A bead is a pointer to intent, not a spec.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/DECISIONS.md

@@ -0,0 +1,8 @@
+# Decisions
+
+Live decisions only. Overwrite an entry to change it; git keeps the history.
+
+Each entry is a heading `## D-<slug>: <the decision, as a sentence>` followed by five lines:
+`Decision:` what we do; `Tempting wrong fix:` what looks right and isn't, and why;
+`Evidence:` how it was verified, or `policy`; `Enforced by:` the check or test that keeps it
+true; `Revisit when:` the condition that would change it.

package/template/README.md

@@ -0,0 +1,14 @@
+# {{name}}
+
+What it is and who it is for, in a paragraph.
+
+## Develop
+
+```sh
+bun install --frozen-lockfile
+bun run check
+```
+
+Built with [monkeyshape](https://github.com/clinsky/monkeyshape): where it's going is in
+[docs/roadmap.md](docs/roadmap.md), and how humans and agents work here is in
+[AGENTS.md](AGENTS.md).

package/template/docs/roadmap.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+Where {{name}} is heading, and how far it has got. The status table answers "does X exist
+yet?". This file is direction, not a rule source: rewrite it in place when a piece ships.
+
+## Status
+
+| Piece | Status |
+|---|---|
+| The gate: typecheck, biome, `mshape check`, tests | **Shipped** |
+
+## Direction
+
+Not written yet. Run `/roadmap` with a brain-dump of what you want to build.

package/template/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.private/
+
+# Tracks and reviews: worktrees, and links to the handoffs store under .git (no trailing slash on links)
+.agents/worktrees/
+.agents/handoffs
+.handoffs

package/template/shape.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "monkeyshape";
+
+export default defineConfig({
+  // The module map is the layout: every directory under src/ is a module, and nothing else
+  // restates it. Add modules as the code grows; `mshape check` keeps imports to these edges.
+  arch: {
+    modules: {
+      core: { description: "Deterministic logic over plain data. No host I/O." },
+      adapters: {
+        description: "Host I/O (disk, network, processes) behind services.",
+        mayImport: ["core"],
+        hostAccess: true,
+      },
+      cli: {
+        description: "The entry point and composition root: where effects run.",
+        mayImport: ["core", "adapters"],
+        hostAccess: true,
+      },
+    },
+  },
+  tracks: {
+    // Gitignored data every track worktree shares with the main checkout, such as a large
+    // dataset: repo-relative paths like "data/large". `mshape track new` links each one.
+    sharedPaths: [],
+  },
+});

package/template/test/toolchain.test.ts

@@ -0,0 +1,7 @@
+/** The first test: bun test, TypeScript and effect run together. Replace it with your own. */
+import { expect, test } from "bun:test";
+import { Effect } from "effect";
+
+test("the toolchain runs an effect", () => {
+  expect(Effect.runSync(Effect.succeed(1 + 1))).toBe(2);
+});