@ree-auz/nook 0.0.0-stage → 0.1.1

package/integrations/linear/open-issue.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Opens a Linear issue in a Nook workspace, in a new terminal tab.
+// Linear runs this file through ~/.linear/coding-tools.json
+// (Work on issue -> Custom script). See README.md next to it.
+//
+//   node open-issue.mjs [agent]              started by Linear (no window)
+//   node open-issue.mjs --run <file> ...     inside the new tab
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizeName } from "../../src/names.mjs";
+
+const self = fileURLToPath(import.meta.url);
+const nk = fileURLToPath(new URL("../../bin/nk.mjs", import.meta.url));
+
+/**
+ * Puts this Node's folder first on PATH. With a version manager such as fnm
+ * or nvm, Linear starts without the shell setup that adds it, and global npm
+ * commands (the agent, pnpm for hooks) live next to node.exe.
+ */
+function withNodeOnPath(env = process.env) {
+  const key = Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH";
+  return { ...env, [key]: [dirname(process.execPath), env[key]].filter(Boolean).join(delimiter) };
+}
+
+/** Runs nk with this Node, so the prompt never passes through cmd.exe. */
+function runNk(args, opts = {}) {
+  return spawnSync(process.execPath, [nk, ...args], { stdio: "inherit", env: withNodeOnPath(), ...opts });
+}
+
+/** Creates the issue's workspace and starts the agent, or reopens it. */
+function startWork({ branch, agent, prompt }) {
+  const listed = spawnSync(process.execPath, [nk, "ls", "--json"], { encoding: "utf8", env: withNodeOnPath() });
+  const existing = listed.status === 0 ? JSON.parse(listed.stdout).find((ws) => !ws.main && (ws.branch === branch || ws.name === normalizeName(branch))) : null;
+  // Clicked again for the same issue: reopen the workspace without restarting the task.
+  // -y: the branch name Linear suggests is converted without asking.
+  const result = existing ? runNk([existing.name, agent]) : runNk(["-b", branch, agent, "-y", "-p", prompt]);
+  process.exitCode = result.status ?? 1;
+}
+
+/** Inside a tab another terminal opened: the prompt comes in a file. */
+export function insideTab([file, branch, agent, ...more]) {
+  const prompt = readFileSync(file, "utf8");
+  rmSync(file, { force: true });
+  // A Warp tab config written only for this launch.
+  if (more[0] === "--cleanup" && more[1]) rmSync(more[1], { force: true });
+  startWork({ branch, agent, prompt });
+}
+
+/** Windows Terminal: -w 0 opens a tab in the most recent window (or a new window). */
+function openInWindowsTerminal({ dir, id, inner }) {
+  spawn("wt.exe", ["-w", "0", "new-tab", "-d", dir, "--title", id, ...inner], { detached: true, stdio: "ignore" }).unref();
+}
+
+/** A PowerShell argument in single quotes. */
+const psQuote = (text) => `'${String(text).replaceAll("'", "''")}'`;
+
+/**
+ * Warp: its URI scheme cannot run a command, so write a tab config that
+ * does and open it with warp://tab_config/<name>, as Warp's docs advise.
+ * The tab deletes the config once it starts.
+ */
+export function openInWarp({ dir, id, inner, env = process.env, start = openUri }) {
+  const folder = join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "warp", "Warp", "data", "tab_configs");
+  mkdirSync(folder, { recursive: true });
+  const name = `nk-${id.toLowerCase().replace(/[^a-z0-9-]/g, "-")}-${process.pid}`;
+  const config = join(folder, `${name}.toml`);
+  const [node, ...args] = [...inner, "--cleanup", config];
+  const shell = which("pwsh") ? "pwsh" : "powershell";
+  const command = `& ${[node, ...args].map(psQuote).join(" ")}`;
+  writeFileSync(
+    config,
+    [`name = ${JSON.stringify(name)}`, `title = ${JSON.stringify(id)}`, "", "[[panes]]", 'id = "main"', 'type = "terminal"', `shell = ${JSON.stringify(shell)}`, `directory = ${JSON.stringify(dir)}`, `commands = [${JSON.stringify(command)}]`, ""].join("\n"),
+  );
+  start(`warp://tab_config/${name}`);
+  return config;
+}
+
+/** Opens a URI with its registered app, like PowerShell's Start-Process. */
+function openUri(uri) {
+  spawn("cmd.exe", ["/d", "/c", "start", '""', uri], { detached: true, stdio: "ignore", windowsVerbatimArguments: true }).unref();
+}
+
+/** A command on PATH, without running it. */
+function which(command) {
+  const result = spawnSync("where.exe", [command], { encoding: "utf8", windowsHide: true });
+  return result.status === 0;
+}
+
+const TERMINALS = { wt: openInWindowsTerminal, warp: openInWarp };
+
+/**
+ * Closes the terminal window Linear opened for this script, once the work
+ * runs in another terminal: its shell is this process's parent.
+ */
+function closeLinearWindow() {
+  const parent = spawnSync("tasklist.exe", ["/FI", `PID eq ${process.ppid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", windowsHide: true });
+  if (/^"(powershell|pwsh|cmd)\.exe"/i.test(parent.stdout ?? "")) process.kill(process.ppid);
+}
+
+/**
+ * The agent named by a label in Linear's prompt, which lists the issue's
+ * labels as <label>Group › Name</label>: with group "Agent", an issue
+ * labelled "Agent › Claude" gets `claude`.
+ */
+export function agentFromLabels(prompt, group) {
+  if (!group) return null;
+  for (const [, text] of prompt.matchAll(/<label>([^<]*)<\/label>/g)) {
+    const [labelGroup, name] = text.split("›").map((part) => part.trim());
+    if (name && labelGroup === group) return name.toLowerCase().replace(/\s+/g, "-");
+  }
+  return null;
+}
+
+/** `--name value` from the arguments Linear passes. */
+function option(argv, name) {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : undefined;
+}
+
+function fromLinear(argv) {
+  const terminal = option(argv, "--terminal");
+  const agent = agentFromLabels(process.env.LINEAR_PROMPT ?? "", option(argv, "--agent-label")) ?? option(argv, "--agent") ?? "codex";
+  const { LINEAR_ISSUE_BRANCH_NAME: branch, LINEAR_WORK_DIR: dir, LINEAR_ISSUE_IDENTIFIER: id = "issue", LINEAR_PROMPT: prompt = "" } = process.env;
+  if (!branch || !dir) throw new Error("LINEAR_ISSUE_BRANCH_NAME and LINEAR_WORK_DIR are missing; list them under env in coding-tools.json");
+  // Default: work in the terminal Linear opened for the script.
+  if (!terminal) {
+    process.chdir(dir);
+    return startWork({ branch, agent, prompt });
+  }
+  const open = TERMINALS[terminal];
+  if (!open) throw new Error(`Unknown terminal "${terminal}"; use ${Object.keys(TERMINALS).join(" or ")}, or leave --terminal out`);
+  if (process.platform !== "win32") throw new Error("--terminal only works on Windows so far");
+  // The prompt is long Markdown with quotes and semicolons, so it travels in a file.
+  const file = join(tmpdir(), `nk-linear-${id}-${process.pid}.md`);
+  writeFileSync(file, prompt);
+  open({ dir, id, inner: [process.execPath, self, "--run", file, branch, agent] });
+  closeLinearWindow();
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === self) {
+  const [first, ...rest] = process.argv.slice(2);
+  if (first === "--run") insideTab(rest);
+  else fromLinear(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@ree-auz/nook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One home folder for your git worktrees: create, open and remove workspaces with shared files, ports and hooks.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nk": "bin/nk.mjs",
+    "nook": "bin/nk.mjs"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "integrations",
+    "skills",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1",
+    "corpus": "node scripts/corpus.mjs"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6",
+    "smol-toml": "1.9.1",
+    "yaml": "2.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ree-auz/nook.git"
+  }
+}

package/skills/nook/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: nook
+description: Use when working in a git worktree managed by nk (Nook), when asked to create, list, open, remove or clean up workspaces with nk, or to set up a repository's .nook hooks.
+---
+
+# Working with Nook (`nk`)
+
+Nook keeps one git worktree per task under `~/nook/workspace/<repo>/<name>`.
+The workspace name is also the branch name and the folder name.
+
+## Am I in a workspace?
+
+`NOOK_WORKSPACE` is set when nk started you. These variables are also set:
+
+| Variable | Meaning |
+| --- | --- |
+| `NOOK_WORKSPACE` | workspace and branch name |
+| `NOOK_PATH` | this workspace's folder |
+| `NOOK_REPO` | the main checkout of the repository |
+| `NOOK_SHARED` | the repository's shared folder (holds files such as `.env`) |
+| `NOOK_PORT` | first of ten ports reserved for this workspace (`NOOK_PORT` to `NOOK_PORT + 9`) |
+
+Without the variables, `nk ls --json` lists every workspace with its `path`;
+you are in one when your working directory is inside that path.
+
+## Rules
+
+- Work and commit only inside your own workspace folder. Do not edit the main
+  checkout (`NOOK_REPO`) or another workspace.
+- Use ports from `NOOK_PORT` to `NOOK_PORT + 9` for servers you start, so
+  workspaces do not collide.
+- Files copied from the shared folder (such as `.env`) are local settings.
+  Do not commit them and do not print their contents.
+- Do not run `nk rm` or `nk clean` on your own workspace: nk refuses while
+  you are inside it. Leave removal to the person or the tool that started you.
+- Hooks in `.nook/` run with the person's approval. Do not edit them to get
+  past a failure; report the failure and the log path nk printed. Never pass
+  `--allow-hooks` yourself: the person reads and allows the hooks.
+
+## Setting up hooks
+
+When asked to set up Nook hooks: if you were started by `nk hooks write
+<agent>`, nk has already generated hooks from CI and the Compose file; finish what its prompt lists
+as not translated. Otherwise run `nk hooks write` first. Follow
+[docs/setup-hooks.md](https://github.com/ree-auz/nook/blob/main/docs/setup-hooks.md),
+run `nk hooks test` in the folder you work in and fix the hooks until it
+passes. Delete the first line of a generated hook you edit. Do not commit or
+push unless asked.
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `nk -b <name> [agent] [-p <prompt>]` | Create a workspace from the default branch (or an existing branch of that name) |
+| `nk <name>` | Print a workspace's path; with an agent, start it there |
+| `nk ls --json` | Every workspace of this repository: `name`, `repo`, `path`, `port`, `changes`, `ahead`, `behind`, `pr` (`number`, `state`, `ci`) |
+| `nk rm <name>... -n` | Show what removing would back up and delete, change nothing |
+| `nk clean -n` | Show which workspaces are merged and would be removed |
+| `nk hooks test` | Run this folder's hooks in a temporary workspace; fails on leftovers |
+| `nk hooks` | The repository's hooks: allowed, tested |
+| `nk doctor` | Check nk's tools; exit 1 when something is broken |
+
+Pass `-y` to `nk rm` or `nk clean` only when the person asked for the
+removal. Both back up uncommitted changes and unpushed commits to
+`~/nook/backup/<repo>/` first.
+
+## Reading results
+
+Exit code 0 means success. On failure, stderr starts with `✗ what failed`,
+followed by `○` lines saying why and what to do next. Follow those lines
+instead of guessing.

package/src/agents.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, statSync } from "node:fs";
+import { delimiter, dirname, extname, isAbsolute, join } from "node:path";
+import { NookError } from "./errors.mjs";
+import spawn from "cross-spawn";
+
+/** Command-line coding agents init looks for. Any other command works too. */
+export const KNOWN_AGENTS = ["claude", "codex", "gemini", "grok", "opencode", "pi", "aider", "amp", "cursor-agent", "qwen"];
+
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Finds a command on PATH, like `which` / `where`. */
+export function which(command, env = process.env, platform = process.platform) {
+  const extensions =
+    platform === "win32" ? ["", ...(env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").map((ext) => ext.toLowerCase())] : [""];
+  if (isAbsolute(command) || command.includes("/") || command.includes("\\")) {
+    for (const ext of extensions) if (isFile(command + ext)) return command + ext;
+    return null;
+  }
+  const dirs = (env.PATH || env.Path || "").split(platform === "win32" ? ";" : delimiter).filter(Boolean);
+  for (const dir of dirs)
+    for (const ext of extensions) {
+      if (platform === "win32" && ext === "" && !extname(command)) continue;
+      const full = join(dir, command + ext);
+      if (isFile(full)) return full;
+    }
+  return null;
+}
+
+export function commandVersion(path) {
+  const result = spawn.sync(path, ["--version"], { encoding: "utf8", timeout: 10000, windowsHide: true });
+  if (result.status !== 0 || !result.stdout) return "";
+  return result.stdout.trim().split(/\r?\n/)[0].slice(0, 80);
+}
+
+export function detectAgents(env = process.env, names = KNOWN_AGENTS) {
+  const found = [];
+  for (const name of names) {
+    const path = which(name, env);
+    if (path) found.push({ name, path, version: commandVersion(path) });
+  }
+  return found;
+}
+
+/** Command for `nk <name> <agent> [-p prompt] [-- extra]`. */
+export function agentCommand(config, agent, { prompt, extra = [] } = {}, env = process.env) {
+  const entry = config.agents?.[agent];
+  const command = entry?.path && isFile(entry.path) ? entry.path : which(agent, env) ?? agent;
+  const args = [...(entry?.args ?? []), ...extra];
+  if (prompt) args.push(prompt);
+  return { command, args };
+}
+
+/**
+ * The program behind an npm .cmd shim on Windows, read the way npm's own
+ * read-cmd-shim does: the quoted path after %dp0% (or %~dp0) followed by %*.
+ */
+export function cmdShimTarget(shimPath) {
+  let text;
+  try {
+    text = readFileSync(shimPath, "utf8");
+  } catch {
+    return null;
+  }
+  const match = /"%(?:~dp0|dp0%)\\?([^"]+?)"\s+%\*/.exec(text);
+  return match ? join(dirname(shimPath), ...match[1].split(/[\\/]/)) : null;
+}
+
+/**
+ * cmd.exe ends a command at the first line break, so a .cmd agent would get
+ * only the first line of a multi-line prompt. Run the program behind an npm
+ * shim directly instead.
+ */
+export function windowsDirect({ command, args }, platform = process.platform) {
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(command) || !args.some((arg) => /[\r\n]/.test(arg))) return { command, args };
+  const target = cmdShimTarget(command);
+  if (target && /\.(c|m)?js$/i.test(target) && isFile(target)) return { command: process.execPath, args: [target, ...args] };
+  if (target && /\.exe$/i.test(target) && isFile(target)) return { command: target, args };
+  throw new NookError(`${command} runs through cmd.exe, which cannot pass a prompt with line breaks; put the prompt on one line`);
+}
+
+export function launch(spec, { cwd, env }) {
+  const { command, args } = windowsDirect(spec);
+  const result = spawn.sync(command, args, { cwd, env, stdio: "inherit" });
+  if (result.error) throw result.error;
+  return result.status ?? 1;
+}

package/src/backup.mjs

@@ -0,0 +1,74 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { exists } from "./home.mjs";
+import { git, gitTry, refExists, statusLines } from "./git.mjs";
+import { copyFile } from "./shared.mjs";
+
+/** Commits on `branch` that are on no remote and not in the base branch. */
+export function unpushedCommits(repo, branch, base) {
+  if (!refExists(repo, `refs/heads/${branch}`)) return [];
+  const args = ["rev-list", `refs/heads/${branch}`, "--not", "--remotes"];
+  if (base && base !== branch) args.push(base);
+  const result = gitTry(args, { cwd: repo });
+  return result.ok && result.out ? result.out.split(/\r?\n/) : [];
+}
+
+export function isMerged(repo, branch, base) {
+  if (!refExists(repo, `refs/heads/${branch}`)) return true;
+  return gitTry(["merge-base", "--is-ancestor", `refs/heads/${branch}`, base], { cwd: repo }).ok;
+}
+
+/** What a removal would lose: uncommitted changes, unpushed commits, unmerged branch. */
+export function inspectWorkspace({ repo, path, branch, base }) {
+  const present = exists(path);
+  return {
+    present,
+    changes: present ? statusLines(path) : [],
+    unpushed: unpushedCommits(repo, branch, base),
+    merged: isMerged(repo, branch, base),
+  };
+}
+
+export function needsBackup(state) {
+  return state.changes.length > 0 || state.unpushed.length > 0;
+}
+
+function stamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}`;
+}
+
+export function backupDir(backupRoot, name, date = new Date()) {
+  let dir = join(backupRoot, `${name}-${stamp(date)}`);
+  for (let n = 2; exists(dir); n++) dir = join(backupRoot, `${name}-${stamp(date)}-${n}`);
+  return dir;
+}
+
+/**
+ * Saves what removal would lose:
+ *   changes.patch   tracked changes (staged and unstaged), apply with `git apply`
+ *   untracked/      new files git does not ignore
+ *   commits.bundle  unpushed commits, restore with `git fetch <bundle> <branch>`
+ *   info.txt        workspace, branch, HEAD, time
+ */
+export function createBackup({ repo, path, branch, base, state, dir }) {
+  mkdirSync(dir, { recursive: true });
+  const info = [`workspace: ${branch}`, `path: ${path}`, `time: ${new Date().toISOString()}`];
+  if (state.present) {
+    const head = gitTry(["rev-parse", "HEAD"], { cwd: path });
+    if (head.ok) info.push(`head: ${head.out}`);
+    const diff = gitTry(["diff", "--binary", "HEAD"], { cwd: path });
+    if (diff.ok && diff.out) writeFileSync(join(dir, "changes.patch"), diff.out + "\n");
+    const untracked = git(["ls-files", "-z", "--others", "--exclude-standard"], { cwd: path }).split("\0").filter(Boolean);
+    for (const file of untracked) copyFile(join(path, file), join(dir, "untracked", file));
+    if (untracked.length) info.push(`untracked files: ${untracked.length}`);
+  }
+  if (state.unpushed.length) {
+    const args = ["bundle", "create", join(dir, "commits.bundle"), `refs/heads/${branch}`, "--not", "--remotes"];
+    if (base && base !== branch) args.push(base);
+    git(args, { cwd: repo });
+    info.push(`unpushed commits: ${state.unpushed.length}`);
+  }
+  writeFileSync(join(dir, "info.txt"), info.join("\n") + "\n");
+  return dir;
+}