@ree-auz/nook 0.1.0 → 0.1.2

package/bin/nk.mjs

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { main } from "../src/cli.mjs";
-
-process.exitCode = await main(process.argv.slice(2));
+import { main } from "../src/cli.mjs";
+
+process.exitCode = await main(process.argv.slice(2));

package/docs/setup-hooks.md

@@ -1,107 +1,107 @@
-# Writing hooks
-
-`nk hooks write` turns the repository's CI and Compose file into hooks
-without AI; the README shows what it takes from each and what it leaves out.
-This page is for the parts it cannot translate, and for repositories without
-either: what a person or an agent writing hooks by hand has to follow.
-
-`nk hooks write <agent>` writes the hooks the same way, then starts the agent
-in the folder you ran it in (usually the main checkout) with a
-prompt that lists what nk generated, what it could not translate, the CI and
-setup files, and the shared files with their empty keys (never their values).
-The agent finishes the hooks and runs `nk hooks test` until it passes; it
-leaves the changes uncommitted for you to review. If a repository's rules keep
-agents out of the main checkout, create a workspace first (`nk -b hooks`) and
-run the command inside it.
-
-When you edit a generated hook, delete its first line (`// Generated by nk
-hooks write ...`), so `nk hooks write` will not replace it.
-
-## Rules for the hooks
-
-- One `.mjs` file per moment works on Windows, macOS and Linux. Use
-  `node:child_process` and stop at the first failing command with a non-zero
-  exit code, so nk does not start an agent on a broken workspace.
-- Hooks run inside the workspace with these variables: `NOOK_WORKSPACE`
-  (name), `NOOK_PATH` (folder), `NOOK_REPO` (main checkout), `NOOK_SHARED`
-  (shared folder) and `NOOK_PORT` (first of ten ports for this workspace).
-- `create` runs once, after shared files such as `.env` are copied. `open`
-  runs every time the workspace is opened, so it must be safe to run again.
-  `remove` runs before the folder is deleted; when it fails nothing is deleted.
-- `remove` undoes everything `create` did outside the folder: containers,
-  volumes, networks, built images, databases created in a shared server.
-  `nk rm` also stops programs in the folder and, as a safety net, removes
-  Compose projects started in it; do not rely on that.
-- Never touch the main checkout or its services: do not read or copy its
-  `.env`, and do not stop or remove its containers.
-- Servers and containers use ports from `NOOK_PORT` to `NOOK_PORT + 9`.
-- Do not print secrets. Do not run `docker compose config`: it prints every
-  value from `.env`.
-
-## Examples
-
-A small helper the examples share:
-
-```js
-import { spawnSync } from "node:child_process";
-
-function run(command, ...args) {
-  // shell: true lets Windows find pnpm.cmd and npm.cmd.
-  const result = spawnSync([command, ...args].join(" "), { stdio: "inherit", shell: true });
-  if (result.status !== 0) process.exit(result.status ?? 1);
-}
-```
-
-### Node (pnpm, npm, yarn, bun)
-
-Install with the package manager whose lockfile the repository has:
-`pnpm-lock.yaml` → `pnpm install`, `package-lock.json` → `npm ci`,
-`yarn.lock` → `yarn install`, `bun.lock` → `bun install`.
-
-```js
-// .nook/create.mjs
-run("pnpm", "install");
-```
-
-### Python (uv)
-
-A virtual environment holds absolute paths and cannot be copied from the main
-checkout; create it again:
-
-```js
-// .nook/create.mjs
-run("uv", "sync");
-```
-
-### Docker Compose
-
-Give each workspace its own Compose project, so its containers, volumes and
-networks never mix with the main checkout's. Compose's own rule for a project
-name is lowercase letters, digits, `_` and `-`.
-
-```js
-// .nook/create.mjs
-const project = process.env.NOOK_WORKSPACE.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
-const port = Number(process.env.NOOK_PORT);
-process.env.DB_PORT = String(port); // whatever the compose file reads
-run("docker", "compose", "--project-name", project, "up", "-d", "--wait");
-```
-
-Write the project name and ports into the workspace `.env` as well
-(`COMPOSE_PROJECT_NAME=...`), so a plain `docker compose` typed in the
-workspace later finds the same project.
-
-```js
-// .nook/open.mjs: start the containers again after a restart
-run("docker", "compose", "start");
-```
-
-```js
-// .nook/remove.mjs: everything the project created, volumes and built images too
-const project = process.env.NOOK_WORKSPACE.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
-run("docker", "compose", "--project-name", project, "down", "--volumes", "--rmi", "local", "--remove-orphans");
-```
-
-A fuller setup with a database per workspace also refuses the production
-project name in every hook, so a mistyped name can never start or stop the
-main checkout's services.
+# Writing hooks
+
+`nk hooks write` turns the repository's CI and Compose file into hooks
+without AI; the README shows what it takes from each and what it leaves out.
+This page is for the parts it cannot translate, and for repositories without
+either: what a person or an agent writing hooks by hand has to follow.
+
+`nk hooks write <agent>` writes the hooks the same way, then starts the agent
+in the folder you ran it in (usually the main checkout) with a
+prompt that lists what nk generated, what it could not translate, the CI and
+setup files, and the shared files with their empty keys (never their values).
+The agent finishes the hooks and runs `nk hooks test` until it passes; it
+leaves the changes uncommitted for you to review. If a repository's rules keep
+agents out of the main checkout, create a workspace first (`nk -b hooks`) and
+run the command inside it.
+
+When you edit a generated hook, delete its first line (`// Generated by nk
+hooks write ...`), so `nk hooks write` will not replace it.
+
+## Rules for the hooks
+
+- One `.mjs` file per moment works on Windows, macOS and Linux. Use
+  `node:child_process` and stop at the first failing command with a non-zero
+  exit code, so nk does not start an agent on a broken workspace.
+- Hooks run inside the workspace with these variables: `NOOK_WORKSPACE`
+  (name), `NOOK_PATH` (folder), `NOOK_REPO` (main checkout), `NOOK_SHARED`
+  (shared folder) and `NOOK_PORT` (first of ten ports for this workspace).
+- `create` runs once, after shared files such as `.env` are copied. `open`
+  runs every time the workspace is opened, so it must be safe to run again.
+  `remove` runs before the folder is deleted; when it fails nothing is deleted.
+- `remove` undoes everything `create` did outside the folder: containers,
+  volumes, networks, built images, databases created in a shared server.
+  `nk rm` also stops programs in the folder and, as a safety net, removes
+  Compose projects started in it; do not rely on that.
+- Never touch the main checkout or its services: do not read or copy its
+  `.env`, and do not stop or remove its containers.
+- Servers and containers use ports from `NOOK_PORT` to `NOOK_PORT + 9`.
+- Do not print secrets. Do not run `docker compose config`: it prints every
+  value from `.env`.
+
+## Examples
+
+A small helper the examples share:
+
+```js
+import { spawnSync } from "node:child_process";
+
+function run(command, ...args) {
+  // shell: true lets Windows find pnpm.cmd and npm.cmd.
+  const result = spawnSync([command, ...args].join(" "), { stdio: "inherit", shell: true });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+```
+
+### Node (pnpm, npm, yarn, bun)
+
+Install with the package manager whose lockfile the repository has:
+`pnpm-lock.yaml` → `pnpm install`, `package-lock.json` → `npm ci`,
+`yarn.lock` → `yarn install`, `bun.lock` → `bun install`.
+
+```js
+// .nook/create.mjs
+run("pnpm", "install");
+```
+
+### Python (uv)
+
+A virtual environment holds absolute paths and cannot be copied from the main
+checkout; create it again:
+
+```js
+// .nook/create.mjs
+run("uv", "sync");
+```
+
+### Docker Compose
+
+Give each workspace its own Compose project, so its containers, volumes and
+networks never mix with the main checkout's. Compose's own rule for a project
+name is lowercase letters, digits, `_` and `-`.
+
+```js
+// .nook/create.mjs
+const project = process.env.NOOK_WORKSPACE.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+const port = Number(process.env.NOOK_PORT);
+process.env.DB_PORT = String(port); // whatever the compose file reads
+run("docker", "compose", "--project-name", project, "up", "-d", "--wait");
+```
+
+Write the project name and ports into the workspace `.env` as well
+(`COMPOSE_PROJECT_NAME=...`), so a plain `docker compose` typed in the
+workspace later finds the same project.
+
+```js
+// .nook/open.mjs: start the containers again after a restart
+run("docker", "compose", "start");
+```
+
+```js
+// .nook/remove.mjs: everything the project created, volumes and built images too
+const project = process.env.NOOK_WORKSPACE.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+run("docker", "compose", "--project-name", project, "down", "--volumes", "--rmi", "local", "--remove-orphans");
+```
+
+A fuller setup with a database per workspace also refuses the production
+project name in every hook, so a mistyped name can never start or stop the
+main checkout's services.

package/integrations/linear/README.md

@@ -1,84 +1,94 @@
-# Open Linear issues in Nook
-
-Linear's **Work on issue → Custom script** can run a local command for an
-issue. With the files here, one click creates a Nook workspace on the
-issue's branch (running the repository's hooks) and starts your agent in it
-with Linear's prompt, in the terminal Linear opens for the script. Nook
-itself knows nothing about Linear: this folder only connects the two.
-
-Tested on Windows. `--terminal` (Windows Terminal or Warp) is Windows only.
-
-## Set up once
-
-1. Install Nook and run `nk init` in each repository you work on.
-2. In Linear, open **Settings → Code & reviews → Configure coding tools** and
-   enable **Custom script**.
-3. Put this in `~/.linear/coding-tools.json` (on Windows,
-   `C:\Users\<you>\.linear\coding-tools.json`). If Linear already wrote a
-   starter file there, replace its `openIssue` block with this one:
-
-   ```json
-   {
-     "openIssue": {
-       "path": "C:\\Program Files\\nodejs\\node.exe",
-       "args": ["<nook folder>\\integrations\\linear\\open-issue.mjs", "--agent", "codex"],
-       "env": ["LINEAR_ISSUE_IDENTIFIER", "LINEAR_ISSUE_BRANCH_NAME", "LINEAR_PROMPT", "LINEAR_WORK_DIR"]
-     }
-   }
-   ```
-
-   - `path` is the absolute path of Node (`where node` prints it). With a
-     version manager, use a path that stays put: for fnm,
-     `%APPDATA%\fnm\aliases\default\node.exe` written out in full (it follows
-     `fnm default`), not the temporary `fnm_multishells` folder. The script
-     puts that Node's folder first on PATH, so global npm commands such as
-     `codex` and `pnpm` are found even though Linear starts without your
-     shell setup.
-   - `<nook folder>` is where Nook is installed: the cloned folder, or
-     `npm root -g` + `\@ree-auz\nook`.
-   - `--agent` is the agent to start: `codex` (the default), `claude` or any
-     command `nk -b <name> <agent>` accepts.
-   - Linear runs the script in a terminal of its own (on Windows, Windows
-     Terminal; the terminal choice in Linear's settings is macOS only). To
-     work in Warp instead, add `"--terminal", "warp"` to `args`: the script
-     opens a tab in Warp and closes Linear's window.
-   - To let each issue pick its agent, label issues from one label group
-     (say `Agent › Codex`, `Agent › Claude`) and add `"--agent-label", "Agent"`
-     to `args`. Linear's prompt lists the issue's labels, and the script starts
-     the agent named by that group's label (lowercased, spaces as `-`), or the
-     `--agent` one when the issue has none.
-   - `env` is an allowlist: Linear only passes the variables listed here.
-
-## Use
-
-On an issue, choose **Work on issue → Custom script**. The first time, Linear
-asks you to **Choose a directory**: pick the repository's main checkout (the
-folder where you ran `nk init`). Nook uses it only to know which repository
-the issue belongs to; nothing runs there.
-
-The terminal runs `nk -b <issue branch> <agent> -y -p <Linear's prompt>` in
-that folder (`-y` keeps the converted workspace name without asking).
-Choosing the same issue again reopens its workspace and starts the agent
-without the prompt.
-
-Linear's GitHub integration moves the issue along as the branch and its pull
-request change, because the branch name holds the issue identifier. After the
-pull request is merged, `nk clean` removes the workspace.
-
-## How it works
-
-- Linear opens a terminal, runs `open-issue.mjs` in it and passes the issue
-  through the `LINEAR_*` variables.
-- By default the script runs `nk` right there, with the same Node.
-- With `--terminal`, the prompt is long Markdown with quotes and semicolons,
-  so the script writes it to a temporary file and opens a tab in the chosen
-  folder that runs the same script again: Windows Terminal with
-  `wt.exe -w 0 new-tab -d <folder>`; Warp, whose `warp://` links cannot run a
-  command, through a
-  [tab config](https://docs.warp.dev/terminal/windows/tab-configs/) written to
-  `%APPDATA%\warp\Warp\data\tab_configs\` and opened with
-  `warp://tab_config/<name>` (the tab deletes it when it starts). A
-  minimized Warp window stays minimized. It then
-  closes the window Linear opened.
-- `nk` runs with the same Node, never through `cmd.exe`, which would cut a
-  multi-line prompt at its first line break.
+# Open Linear issues in Nook
+
+Linear's **Work on issue → Custom script** can run a local command for an
+issue. With the files here, one click creates a Nook workspace on the
+issue's branch (running the repository's hooks) and starts your agent in it
+with Linear's prompt, in the terminal Linear opens for the script. Nook
+itself knows nothing about Linear: this folder only connects the two.
+
+Tested on Windows. `--terminal wt` and `--terminal warp` are Windows only.
+
+## Set up once
+
+1. Install Nook and run `nk init` in each repository you work on.
+2. In Linear, open **Settings → Code & reviews → Configure coding tools** and
+   enable **Custom script**.
+3. Put this in `~/.linear/coding-tools.json` (on Windows,
+   `C:\Users\<you>\.linear\coding-tools.json`). If Linear already wrote a
+   starter file there, replace its `openIssue` block with this one:
+
+   ```json
+   {
+     "openIssue": {
+       "path": "C:\\Program Files\\nodejs\\node.exe",
+       "args": ["<nook folder>\\integrations\\linear\\open-issue.mjs", "--agent", "codex"],
+       "env": ["LINEAR_ISSUE_IDENTIFIER", "LINEAR_ISSUE_BRANCH_NAME", "LINEAR_PROMPT", "LINEAR_WORK_DIR"]
+     }
+   }
+   ```
+
+   - `path` is the absolute path of Node (`where node` prints it). With a
+     version manager, use a path that stays put: for fnm,
+     `%APPDATA%\fnm\aliases\default\node.exe` written out in full (it follows
+     `fnm default`), not the temporary `fnm_multishells` folder. The script
+     puts that Node's folder first on PATH, so global npm commands such as
+     `codex` and `pnpm` are found even though Linear starts without your
+     shell setup.
+   - `<nook folder>` is where Nook is installed: the cloned folder, or
+     `npm root -g` + `\@ree-auz\nook`.
+   - `--agent` is the agent to start: `codex` (the default), `claude` or any
+     command `nk -b <name> <agent>` accepts.
+   - Linear runs the script in a terminal of its own (on Windows, Windows
+     Terminal; the terminal choice in Linear's settings is macOS only). To
+     work in Warp instead, add `"--terminal", "warp"` to `args`: the script
+     opens a tab in Warp and closes Linear's window.
+   - To keep agents in [Orca](https://www.onorca.dev) (its accounts and
+     sessions), add `"--terminal", "orca"`: Nook creates the workspace and
+     runs its hooks in Linear's window, then
+     `orca agent launch --agent <agent> --worktree path:<workspace> --prompt <Linear's prompt> --focus`
+     starts the agent in Orca. Orca shows worktrees it did not create, and
+     `nk rm` / `nk clean` still remove them with their containers and
+     volumes. Orca's command-line tool must be installed; if Linear cannot
+     find it on PATH, add `"--orca", "<full path to orca>"`. Linear's window
+     closes when Orca has the agent, and stays open with the error otherwise.
+   - To let each issue pick its agent, label issues from one label group
+     (say `Agent › Codex`, `Agent › Claude`) and add `"--agent-label", "Agent"`
+     to `args`. Linear's prompt lists the issue's labels, and the script starts
+     the agent named by that group's label (lowercased, spaces as `-`), or the
+     `--agent` one when the issue has none.
+   - `env` is an allowlist: Linear only passes the variables listed here.
+
+## Use
+
+On an issue, choose **Work on issue → Custom script**. The first time, Linear
+asks you to **Choose a directory**: pick the repository's main checkout (the
+folder where you ran `nk init`). Nook uses it only to know which repository
+the issue belongs to; nothing runs there.
+
+The terminal runs `nk -b <issue branch> <agent> -y -p <Linear's prompt>` in
+that folder (`-y` keeps the converted workspace name without asking).
+Choosing the same issue again reopens its workspace and starts the agent
+without the prompt (with `--terminal orca`, a new agent session in Orca;
+earlier sessions stay in Orca's list).
+
+Linear's GitHub integration moves the issue along as the branch and its pull
+request change, because the branch name holds the issue identifier. After the
+pull request is merged, `nk clean` removes the workspace.
+
+## How it works
+
+- Linear opens a terminal, runs `open-issue.mjs` in it and passes the issue
+  through the `LINEAR_*` variables.
+- By default the script runs `nk` right there, with the same Node.
+- With `--terminal`, the prompt is long Markdown with quotes and semicolons,
+  so the script writes it to a temporary file and opens a tab in the chosen
+  folder that runs the same script again: Windows Terminal with
+  `wt.exe -w 0 new-tab -d <folder>`; Warp, whose `warp://` links cannot run a
+  command, through a
+  [tab config](https://docs.warp.dev/terminal/windows/tab-configs/) written to
+  `%APPDATA%\warp\Warp\data\tab_configs\` and opened with
+  `warp://tab_config/<name>` (the tab deletes it when it starts). A
+  minimized Warp window stays minimized. It then
+  closes the window Linear opened.
+- `nk` runs with the same Node, never through `cmd.exe`, which would cut a
+  multi-line prompt at its first line break.

package/integrations/linear/coding-tools.json

@@ -1,7 +1,7 @@
-{
-  "openIssue": {
-    "path": "C:\\Program Files\\nodejs\\node.exe",
-    "args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@ree-auz\\nook\\integrations\\linear\\open-issue.mjs", "--agent", "codex"],
-    "env": ["LINEAR_ISSUE_IDENTIFIER", "LINEAR_ISSUE_BRANCH_NAME", "LINEAR_PROMPT", "LINEAR_WORK_DIR"]
-  }
-}
+{
+  "openIssue": {
+    "path": "C:\\Program Files\\nodejs\\node.exe",
+    "args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@ree-auz\\nook\\integrations\\linear\\open-issue.mjs", "--agent", "codex"],
+    "env": ["LINEAR_ISSUE_IDENTIFIER", "LINEAR_ISSUE_BRANCH_NAME", "LINEAR_PROMPT", "LINEAR_WORK_DIR"]
+  }
+}