haunter 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haunter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# Haunter CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Capture notes, find pages, and manage tasks in [Haunter](https://www.haunter.app)
+from your terminal. Requires Node.js 22 or later and a Haunter account.
+
+## Get started
+
+Install the CLI and sign in:
+
+```bash
+npm install -g haunter
+haunter login
+haunter workspaces list
+haunter workspaces use WORKSPACE_ID
+```
+
+Your browser opens Haunter's sign-in and consent screen. Choose the workspaces
+and permissions the CLI can use. Replace `WORKSPACE_ID` with an ID from the list.
+If you approve exactly one workspace, commands use it automatically.
+
+You can also run commands without a global install using `npx haunter --help`.
+
+## Capture notes
+
+Create a page from quoted text, a Markdown file, or piped input:
+
+```bash
+haunter capture "An idea for later"
+haunter capture --file meeting.md --title "Meeting notes"
+cat meeting.md | haunter capture --title "Meeting notes"
+```
+
+Without `--title`, the first nonempty line becomes the title, up to 120
+characters. Each command prints the page title and ID. Input is limited to
+100,000 characters.
+
+To add content to an existing page, use `--page`. To create a child page, use
+`--parent`. Replace `PAGE_ID` with the page's ID:
+
+```bash
+haunter capture "Another thought" --page PAGE_ID
+haunter capture --file notes.md --parent PAGE_ID --title "Follow-up"
+```
+
+Appending preserves existing content. `--page` cannot be combined with `--title`
+or `--parent`.
+
+## Find and read pages
+
+```bash
+haunter pages list
+haunter pages search "meeting notes"
+haunter pages read PAGE_ID
+```
+
+Lists show page IDs and titles. Reading a page prints its Markdown. Quote search
+phrases and task titles containing spaces.
+
+## Manage tasks
+
+```bash
+haunter tasks list
+haunter tasks list --due today
+haunter tasks add "Review proposal" --due 2026-12-12
+haunter tasks done TASK_ID
+```
+
+Task lists default to your open tasks, with a limit of 50. Use
+`--filter open|completed|all`, `--scope mine|everyone`,
+`--due today|overdue|upcoming`, and `--limit 1..200` to change the selection.
+Creating and completing tasks prints the task ID.
+
+## Use the CLI in scripts
+
+Add `--json` to get one JSON value on stdout:
+
+```bash
+haunter pages search "meeting" --json
+haunter tasks list --filter all --json
+haunter capture "An idea for later" --json
+```
+
+Errors go to stderr as `{"error":"…"}` in JSON mode. Successful commands exit
+with code 0, errors with 1, and cancellation with 130. Sign-in instructions go to
+stderr, including when `login --json` is used.
+
+Commands use saved credentials and refresh them when needed. Only `login` opens
+a browser. If a write times out, check Haunter before repeating it: the change
+may have been saved.
+
+## Choose a workspace or server
+
+Pass `--workspace WORKSPACE_ID` (or `-w WORKSPACE_ID`) to a page, capture, or task
+command to override the saved workspace.
+
+| Setting | Flag | Environment variable | Default |
+| --- | --- | --- | --- |
+| Workspace | `--workspace` | `HAUNTER_WORKSPACE` | Saved selection, or the only approved workspace |
+| Server | `--server` | `HAUNTER_SERVER` | `https://www.haunter.app/mcp` |
+| Configuration directory | — | `HAUNTER_CONFIG_DIR` | `$XDG_CONFIG_HOME/haunter` or `~/.config/haunter`; `%APPDATA%\haunter` on Windows |
+
+Flags take precedence over environment variables. Credentials and workspace
+selections are separate for each server. A bare server origin gets `/mcp`
+appended. HTTPS is required except for local development:
+
+```bash
+haunter login --server http://localhost:3000
+haunter pages list --server http://localhost:3000
+```
+
+## Sign-in and troubleshooting
+
+- Run `haunter status` to see whether credentials are saved and which workspace
+  is selected. This checks local settings, not whether the session is still valid.
+- Run `haunter login` again if a session is revoked or you need different access.
+  Choose permissions that allow creating pages or managing tasks to use those commands.
+- Use `haunter login --no-browser` to open the printed URL yourself. Complete
+  sign-in in a browser on the same computer as the CLI; the callback uses
+  `127.0.0.1`. Sign-in times out after five minutes.
+- If the callback port is busy, use `haunter login --port 43822`. The default is
+  43821; a chosen port is remembered for that server.
+- Commands for the same server run one at a time to protect token refresh.
+  If a process is forcibly terminated, verify that it has stopped before removing
+  the `.lock` file named in the error.
+
+Credentials are stored locally in a file with owner-only permissions on Unix.
+Treat the configuration directory as sensitive. `haunter logout` removes local
+tokens. To revoke access on the server, disconnect **Haunter CLI** in
+**Haunter → Settings → Agents**.
+
+Run `haunter --help` for the complete command list.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/index.js

@@ -0,0 +1,746 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { createReadStream } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { z as z2 } from "zod";
+// package.json
+var version = "0.1.0";
+
+// src/args.ts
+import { parseArgs } from "node:util";
+var options = {
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+  json: { type: "boolean" },
+  server: { type: "string" },
+  workspace: { type: "string", short: "w" },
+  title: { type: "string" },
+  page: { type: "string" },
+  parent: { type: "string" },
+  file: { type: "string" },
+  due: { type: "string" },
+  filter: { type: "string" },
+  scope: { type: "string" },
+  limit: { type: "string" },
+  port: { type: "string" },
+  "no-browser": { type: "boolean" }
+};
+var commands = {
+  login: { args: 0, flags: ["port", "no-browser"] },
+  logout: { args: 0, flags: [] },
+  status: { args: 0, flags: [] },
+  "workspaces list": { args: 0, flags: [] },
+  "workspaces use": { args: 1, flags: [] },
+  "pages list": { args: 0, flags: ["workspace"] },
+  "pages search": { args: 1, flags: ["workspace"] },
+  "pages read": { args: 1, flags: ["workspace"] },
+  capture: { args: 1, flags: ["workspace", "title", "page", "parent", "file"] },
+  "tasks list": {
+    args: 0,
+    flags: ["workspace", "filter", "scope", "limit", "due"]
+  },
+  "tasks add": { args: 1, flags: ["workspace", "due"] },
+  "tasks done": { args: 1, flags: ["workspace"] }
+};
+function parseArguments(args) {
+  const parsed = parseArgs({
+    args,
+    options,
+    allowPositionals: true,
+    strict: true,
+    tokens: true
+  });
+  const { values, positionals, tokens } = parsed;
+  const group = positionals[0];
+  const grouped = ["pages", "tasks", "workspaces"].includes(group);
+  const command = grouped ? `${group} ${positionals[1] ?? ""}`.trim() : group;
+  const operands = positionals.slice(grouped ? 2 : 1);
+  if (values.help || values.version || !group)
+    return { command, operands, values, help: !values.version };
+  const spec = commands[command];
+  if (!spec)
+    throw new Error(`Unknown command: ${command}. Run haunter --help.`);
+  if (operands.length > spec.args || command !== "capture" && operands.length !== spec.args) {
+    throw new Error(`${command} expects ${spec.args ? "one argument (quote text containing spaces)" : "no arguments"}. Run haunter --help.`);
+  }
+  const seen = new Set;
+  for (const token of tokens) {
+    if (token.kind !== "option")
+      continue;
+    if (seen.has(token.name))
+      throw new Error(`Specify --${token.name} only once.`);
+    seen.add(token.name);
+    if (!["json", "server", ...spec.flags].includes(token.name))
+      throw new Error(`--${token.name} is not supported by ${command}.`);
+    if (typeof token.value === "string" && !token.value.trim())
+      throw new Error(`--${token.name} cannot be empty.`);
+  }
+  if (operands.some((value) => !value.trim()))
+    throw new Error("Arguments cannot be empty.");
+  if (command === "capture") {
+    if (values.page && (values.title || values.parent))
+      throw new Error("--page appends to an existing page; do not combine it with --title or --parent.");
+    if (operands.length && values.file)
+      throw new Error("Pass capture text or --file, not both.");
+  }
+  if (values.port)
+    integer(values.port, "port", 1, 65535);
+  if (values.limit)
+    integer(values.limit, "limit", 1, 200);
+  if (values.filter && !["open", "completed", "all"].includes(values.filter))
+    throw new Error("--filter must be open, completed, or all.");
+  if (values.scope && !["mine", "everyone"].includes(values.scope))
+    throw new Error("--scope must be mine or everyone.");
+  if (values.due) {
+    if (command === "tasks list") {
+      if (!["today", "overdue", "upcoming"].includes(values.due))
+        throw new Error("--due must be today, overdue, or upcoming for tasks list.");
+    } else if (!/^\d{4}-\d{2}-\d{2}$/.test(values.due) || Number.isNaN(Date.parse(values.due)) || new Date(values.due).toISOString().slice(0, 10) !== values.due) {
+      throw new Error("--due must be a valid date in YYYY-MM-DD format for tasks add.");
+    }
+  }
+  return { command, operands, values, help: false };
+}
+function integer(value, flag, min, max) {
+  if (!/^\d+$/.test(value) || Number(value) < min || Number(value) > max)
+    throw new Error(`--${flag} must be an integer from ${min} to ${max}.`);
+}
+var HELP = `Haunter — pages, notes, and tasks from your terminal
+
+Usage: haunter <command> [options]
+
+  login                         Sign in through your browser
+    --no-browser                Print the sign-in URL without opening it
+    --port <port>               Loopback callback port (default: 43821)
+  logout                        Remove locally saved sign-in credentials
+  status                        Show local sign-in and workspace settings
+  workspaces list               List workspaces you approved
+  workspaces use <id>            Save the default workspace for this server
+  pages list                    List pages
+  pages search <query>           Search pages (quote phrases)
+  pages read <id>                Print a page as Markdown
+  capture [text]                Create a page from text, a file, or stdin
+    --title <title>              New page title (default: first nonempty line)
+    --file <path>               Read Markdown from a file; use - for stdin
+    --parent <id>               Create under an existing page
+    --page <id>                 Append to an existing page instead
+  tasks list                    List your open tasks
+    --filter <open|completed|all>
+    --scope <mine|everyone>
+    --due <today|overdue|upcoming>
+    --limit <1-200>              Maximum tasks (default: 50)
+  tasks add <title>              Create a task; optional --due YYYY-MM-DD
+  tasks done <id>                Complete a task
+
+Options:
+  -w, --workspace <id>           Override the saved workspace for a command
+  --server <url>                Haunter URL (default: https://www.haunter.app/mcp)
+  --json                        Write JSON to stdout; errors go to stderr
+  -h, --help                    Show this help
+  -v, --version                 Show the CLI version
+
+Examples:
+  haunter login
+  haunter workspaces use <id>
+  haunter capture "An idea for later"
+  cat meeting.md | haunter capture --title "Meeting notes"
+  haunter capture --file notes.md --page <id>
+  haunter tasks list --due today --json
+
+Environment: HAUNTER_SERVER, HAUNTER_WORKSPACE, HAUNTER_CONFIG_DIR
+`;
+
+// src/auth.ts
+import { spawn } from "node:child_process";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import {
+  auth
+} from "@modelcontextprotocol/sdk/client/auth.js";
+var LOGIN_REQUIRED = "Sign in with haunter login, then try again.";
+
+class AuthProvider {
+  store;
+  profile;
+  authorize;
+  oauthState;
+  verifier;
+  constructor(store, profile, authorize, oauthState = randomBytes(32).toString("base64url")) {
+    this.store = store;
+    this.profile = profile;
+    this.authorize = authorize;
+    this.oauthState = oauthState;
+  }
+  get redirectUrl() {
+    return this.profile.redirectUrl ?? "http://127.0.0.1:43821/callback";
+  }
+  get clientMetadata() {
+    return {
+      client_name: "Haunter CLI",
+      client_uri: "https://www.haunter.app",
+      redirect_uris: [this.redirectUrl],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+      scope: "haunter:mcp offline_access"
+    };
+  }
+  state() {
+    return this.oauthState;
+  }
+  clientInformation() {
+    return this.profile.client;
+  }
+  async saveClientInformation(client) {
+    this.profile.client = { ...this.clientMetadata, ...client };
+    await this.store.save(this.profile);
+  }
+  tokens() {
+    return this.profile.tokens;
+  }
+  async saveTokens(tokens) {
+    this.profile.tokens = tokens;
+    await this.store.save(this.profile);
+  }
+  async redirectToAuthorization(url) {
+    if (!this.authorize)
+      throw new Error(LOGIN_REQUIRED);
+    await this.authorize(url);
+  }
+  saveCodeVerifier(verifier) {
+    if (!this.authorize)
+      throw new Error(LOGIN_REQUIRED);
+    this.verifier = verifier;
+  }
+  codeVerifier() {
+    if (!this.verifier)
+      throw new Error("The sign-in attempt expired. Run haunter login again.");
+    return this.verifier;
+  }
+  async invalidateCredentials(scope) {
+    if (scope === "all" || scope === "client")
+      delete this.profile.client;
+    if (scope === "all" || scope === "tokens")
+      delete this.profile.tokens;
+    if (scope === "all" || scope === "verifier")
+      this.verifier = undefined;
+    await this.store.save(this.profile);
+  }
+}
+async function oauthCallback(state, port, signal) {
+  let succeed;
+  let fail;
+  const code = new Promise((resolve, reject) => {
+    succeed = resolve;
+    fail = reject;
+  });
+  code.catch(() => {});
+  let accepted = false;
+  const server = createServer((request, response) => {
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Content-Type", "text/plain; charset=utf-8");
+    let url;
+    try {
+      url = new URL(request.url ?? "/", "http://127.0.0.1");
+    } catch {
+      response.writeHead(400).end("Invalid callback URL");
+      return;
+    }
+    const address = server.address();
+    if (request.method !== "GET" || url.pathname !== "/callback" || !address || typeof address === "string" || request.headers.host !== `127.0.0.1:${address.port}`) {
+      response.writeHead(404).end("Not found");
+      return;
+    }
+    const received = Buffer.from(url.searchParams.get("state") ?? "");
+    const expected = Buffer.from(state);
+    if (accepted || received.length !== expected.length || !timingSafeEqual(received, expected)) {
+      response.writeHead(400).end("Invalid sign-in state. Return to the terminal and try again.");
+      return;
+    }
+    if (url.searchParams.has("error")) {
+      accepted = true;
+      response.writeHead(400).end("Sign-in was not approved. Return to your terminal.");
+      fail(new Error("Sign-in was not approved."));
+      return;
+    }
+    const value = url.searchParams.get("code");
+    if (!value || value.length > 8192) {
+      response.writeHead(400).end("Missing authorization code");
+      return;
+    }
+    accepted = true;
+    response.end("Authorization received. You can return to your terminal.");
+    succeed(value);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      server.removeListener("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string")
+    throw new Error("Could not start the sign-in callback.");
+  const timer = setTimeout(() => fail(new Error("Sign-in timed out. Run haunter login again.")), 5 * 60000);
+  const abort = () => fail(new Error("Sign-in cancelled."));
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted)
+    abort();
+  return {
+    url: `http://127.0.0.1:${address.port}/callback`,
+    code,
+    close: async () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      server.closeAllConnections();
+      await new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
+function openBrowser(url) {
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) {
+    throw new Error("The sign-in server returned an unsafe authorization URL.");
+  }
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url.href] : [url.href];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "ignore", shell: false });
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? resolve() : reject(new Error("Could not open a browser.")));
+  });
+}
+function boundedFetch(signal) {
+  return (input, init) => fetch(input, {
+    ...init,
+    signal: AbortSignal.any([
+      AbortSignal.timeout(30000),
+      ...signal ? [signal] : [],
+      ...init?.signal ? [init.signal] : []
+    ])
+  });
+}
+async function login(store, profile, options) {
+  const state = randomBytes(32).toString("base64url");
+  const port = options.port ?? (profile.redirectUrl ? Number(new URL(profile.redirectUrl).port) : 43821);
+  const callback = await oauthCallback(state, port, options.signal).catch((error) => {
+    throw new Error("Could not listen for sign-in. Try haunter login --port 43822.", { cause: error });
+  });
+  try {
+    if (profile.redirectUrl !== callback.url)
+      delete profile.client;
+    profile.redirectUrl = callback.url;
+    delete profile.tokens;
+    delete profile.workspaceId;
+    await store.save(profile);
+    const provider = new AuthProvider(store, profile, async (url) => {
+      options.notice(`Open this URL to sign in and choose workspace access:
+${url.href}`);
+      if (!options.noBrowser)
+        await (options.open ?? openBrowser)(url).catch(() => options.notice("Open the URL above in your browser to continue."));
+    }, state);
+    const fetchFn = boundedFetch(options.signal);
+    const result = await auth(provider, {
+      serverUrl: store.server,
+      scope: "haunter:mcp offline_access",
+      fetchFn
+    });
+    if (result === "REDIRECT") {
+      const authorizationCode = await callback.code;
+      const finished = await auth(provider, {
+        serverUrl: store.server,
+        authorizationCode,
+        fetchFn
+      });
+      if (finished !== "AUTHORIZED")
+        throw new Error("Sign-in did not finish. Run haunter login again.");
+    }
+    if (!profile.tokens)
+      throw new Error("Sign-in returned no credentials.");
+  } finally {
+    await callback.close();
+  }
+}
+
+// src/client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+async function connect(store, profile, signal) {
+  if (!profile.tokens)
+    throw new Error(LOGIN_REQUIRED);
+  const client = new Client({ name: "haunter-cli", version }, { capabilities: {} });
+  const transport = new StreamableHTTPClientTransport(new URL(store.server), {
+    authProvider: new AuthProvider(store, profile),
+    fetch: boundedFetch(signal),
+    reconnectionOptions: {
+      maxRetries: 0,
+      initialReconnectionDelay: 1000,
+      maxReconnectionDelay: 1000,
+      reconnectionDelayGrowFactor: 1
+    }
+  });
+  try {
+    await client.connect(transport, { timeout: 30000, signal });
+  } catch (error) {
+    await client.close();
+    throw error;
+  }
+  return {
+    async call(name, args) {
+      const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 30000, signal });
+      const text = Array.isArray(result.content) ? result.content.filter((item) => item.type === "text").map((item) => item.text).join(`
+`) : "";
+      if (result.isError)
+        throw new Error(text || `Haunter could not complete ${name}.`);
+      if (result.structuredContent)
+        return result.structuredContent;
+      try {
+        return JSON.parse(text);
+      } catch {
+        throw new Error(`Haunter returned an unexpected response for ${name}.`);
+      }
+    },
+    close: () => client.close()
+  };
+}
+
+// src/config.ts
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  OAuthClientInformationFullSchema,
+  OAuthTokensSchema
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { z } from "zod";
+var DEFAULT_SERVER = "https://www.haunter.app/mcp";
+var profileSchema = z.object({
+  version: z.literal(1),
+  server: z.string(),
+  workspaceId: z.string().optional(),
+  redirectUrl: z.string().optional(),
+  client: OAuthClientInformationFullSchema.optional(),
+  tokens: OAuthTokensSchema.optional()
+});
+function serverUrl(value) {
+  const url = new URL(value);
+  const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback) || url.username || url.password || url.search || url.hash) {
+    throw new Error("Use an HTTPS server URL (HTTP is allowed only on localhost), without credentials, a query, or a fragment.");
+  }
+  if (url.pathname === "/")
+    url.pathname = "/mcp";
+  return url.toString().replace(/\/$/, "");
+}
+function configDirectory(env = process.env) {
+  if (env.HAUNTER_CONFIG_DIR)
+    return resolve(env.HAUNTER_CONFIG_DIR);
+  const base = process.platform === "win32" ? env.APPDATA ?? join(homedir(), "AppData", "Roaming") : env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(base, "haunter");
+}
+
+class ProfileStore {
+  directory;
+  server;
+  path;
+  constructor(directory, server) {
+    this.directory = directory;
+    this.server = server;
+    this.path = join(directory, `${createHash("sha256").update(server).digest("hex")}.json`);
+  }
+  async load() {
+    try {
+      const profile = profileSchema.parse(JSON.parse(await readFile(this.path, "utf8")));
+      if (profile.server !== this.server)
+        throw new Error("Server mismatch");
+      return profile;
+    } catch (error) {
+      if (isFileError(error, "ENOENT"))
+        return { version: 1, server: this.server };
+      throw new Error(`Could not read CLI configuration at ${this.path}. Move it aside and run haunter login again.`, { cause: error });
+    }
+  }
+  async save(profile) {
+    profileSchema.parse(profile);
+    await mkdir(this.directory, { recursive: true, mode: 448 });
+    await chmod(this.directory, 448);
+    const temporary = `${this.path}.${randomUUID()}.tmp`;
+    const file = await open(temporary, "wx", 384);
+    try {
+      await file.writeFile(`${JSON.stringify(profile, null, 2)}
+`);
+      await file.sync();
+      await file.close();
+      await rename(temporary, this.path);
+    } finally {
+      await file.close();
+      await unlink(temporary).catch((error) => {
+        if (!isFileError(error, "ENOENT"))
+          throw error;
+      });
+    }
+  }
+  async lock() {
+    await mkdir(this.directory, { recursive: true, mode: 448 });
+    const lockPath = `${this.path}.lock`;
+    try {
+      const file = await open(lockPath, "wx", 384);
+      await file.writeFile(String(process.pid));
+      await file.close();
+    } catch (error) {
+      if (!isFileError(error, "EEXIST"))
+        throw error;
+      throw new Error(`Another Haunter command is using this server. Wait for it to finish. If it was interrupted, remove ${lockPath} before retrying.`);
+    }
+    return () => unlink(lockPath).catch((error) => {
+      if (!isFileError(error, "ENOENT"))
+        throw error;
+    });
+  }
+}
+function isFileError(error, code) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+// src/cli.ts
+var workspaceResult = z2.object({
+  workspaces: z2.array(z2.object({ id: z2.string(), name: z2.string(), role: z2.string() }).passthrough())
+});
+var pagesResult = z2.object({
+  pages: z2.array(z2.object({ pageId: z2.string(), title: z2.string() }).passthrough())
+});
+var pageResult = z2.object({ title: z2.string(), markdown: z2.string() });
+var taskRow = z2.object({
+  taskId: z2.string(),
+  title: z2.string(),
+  completed: z2.boolean(),
+  dueDate: z2.string().nullable().optional()
+}).passthrough();
+var tasksResult = z2.object({ tasks: z2.array(taskRow), hasMore: z2.boolean() });
+var savedPage = z2.object({ pageId: z2.string(), title: z2.string() });
+async function runCli(args, io, dependencies = { connect, login }) {
+  let secrets = [];
+  let release;
+  let client;
+  let json = args.includes("--json");
+  const write = (data, text) => io.stdout(json ? `${JSON.stringify(data)}
+` : `${safeText(text)}
+`);
+  try {
+    const { command, operands, values, help } = parseArguments(args);
+    json = Boolean(values.json);
+    if (values.version) {
+      write({ version }, version);
+      return 0;
+    }
+    if (help) {
+      write({ help: HELP }, HELP.trimEnd());
+      return 0;
+    }
+    const server = serverUrl(values.server ?? io.env.HAUNTER_SERVER ?? DEFAULT_SERVER);
+    const store = new ProfileStore(configDirectory(io.env), server);
+    release = await store.lock();
+    const profile = await store.load();
+    secrets = [
+      profile.tokens?.access_token,
+      profile.tokens?.refresh_token,
+      profile.client?.client_secret
+    ].filter((value) => Boolean(value));
+    if (command === "status") {
+      const status = {
+        server,
+        signedIn: Boolean(profile.tokens),
+        workspaceId: profile.workspaceId ?? null
+      };
+      write(status, `${status.signedIn ? "Credentials saved" : "Signed out"}
+Server: ${server}
+Workspace: ${status.workspaceId ?? "not selected"}`);
+      return 0;
+    }
+    if (command === "logout") {
+      delete profile.tokens;
+      delete profile.workspaceId;
+      await store.save(profile);
+      write({ signedIn: false, server }, "Local credentials removed. To revoke the connection, disconnect Haunter CLI in Haunter → Settings → Agents.");
+      return 0;
+    }
+    if (command === "login") {
+      await dependencies.login(store, profile, {
+        port: values.port ? Number(values.port) : undefined,
+        noBrowser: values["no-browser"],
+        signal: io.signal,
+        notice: (text) => io.stderr(`${safeText(text)}
+`)
+      });
+      write({ signedIn: true, server }, "Signed in. Run haunter workspaces list, then haunter workspaces use <id>.");
+      return 0;
+    }
+    const markdown = command === "capture" ? await captureText(operands[0], values.file, io) : undefined;
+    client = await dependencies.connect(store, profile, io.signal);
+    if (command === "workspaces list" || command === "workspaces use") {
+      const result = workspaceResult.parse(await client.call("list_workspaces", {}));
+      if (command === "workspaces list")
+        write(result, result.workspaces.map((w) => `${w.id}	${oneLine(w.name)}	${w.role}`).join(`
+`) || "No workspaces available. Run haunter login to review access.");
+      else {
+        const selected = result.workspaces.find((w) => w.id === operands[0]);
+        if (!selected)
+          throw new Error("Workspace not available. Choose an ID from haunter workspaces list.");
+        profile.workspaceId = selected.id;
+        await store.save(profile);
+        write(selected, `Using ${oneLine(selected.name)} (${selected.id}).`);
+      }
+      return 0;
+    }
+    let workspaceId = values.workspace ?? io.env.HAUNTER_WORKSPACE ?? profile.workspaceId;
+    if (!workspaceId) {
+      const result = workspaceResult.parse(await client.call("list_workspaces", {}));
+      if (result.workspaces.length !== 1)
+        throw new Error("Select a workspace with haunter workspaces use <id>, or pass --workspace <id>.");
+      workspaceId = result.workspaces[0].id;
+    }
+    const workspace = { workspaceId };
+    if (command === "pages list" || command === "pages search") {
+      const result = pagesResult.parse(await client.call(command === "pages list" ? "list_pages" : "search_pages", {
+        ...workspace,
+        ...command === "pages search" ? { query: operands[0] } : {}
+      }));
+      write(result, result.pages.map((p) => `${p.pageId}	${oneLine(p.title || "Untitled")}`).join(`
+`) || "No pages found.");
+    } else if (command === "pages read") {
+      const result = await client.call("read_page", {
+        ...workspace,
+        pageId: uuid(operands[0]),
+        format: "markdown"
+      });
+      write(result, pageResult.parse(result).markdown);
+    } else if (command === "capture") {
+      const title = (values.title ?? markdown?.split(/\r?\n/).find((line) => line.trim())?.replace(/^#+\s*/, "").trim().slice(0, 120)) || "Untitled";
+      const result = await client.call(values.page ? "append_to_page" : "create_page", {
+        ...workspace,
+        markdown,
+        ...values.page ? { pageId: uuid(values.page) } : {
+          title,
+          ...values.parent ? { parentPageId: uuid(values.parent) } : {}
+        }
+      });
+      const page = savedPage.parse(result);
+      write(result, `${values.page ? "Appended to" : "Created"} ${oneLine(page.title)}
+${page.pageId}`);
+    } else if (command === "tasks list") {
+      const result = tasksResult.parse(await client.call("list_tasks", {
+        ...workspace,
+        filter: values.filter ?? "open",
+        scope: values.scope ?? "mine",
+        limit: values.limit ? Number(values.limit) : 50,
+        ...values.due ? { due: values.due } : {}
+      }));
+      write(result, result.tasks.map((t) => `${t.completed ? "[x]" : "[ ]"} ${t.taskId}	${oneLine(t.title)}${t.dueDate ? `	${t.dueDate}` : ""}`).join(`
+`) || "No tasks found.");
+      if (result.hasMore && !json)
+        io.stderr(`More tasks are available. Narrow the filters or increase --limit (maximum 200).
+`);
+    } else {
+      const result = await client.call(command === "tasks add" ? "create_task" : "complete_task", {
+        ...workspace,
+        ...command === "tasks add" ? {
+          title: operands[0],
+          ...values.due ? { dueDate: values.due } : {}
+        } : { taskId: uuid(operands[0]) }
+      });
+      const task = taskRow.parse(result);
+      write(result, `${command === "tasks add" ? "Created" : "Completed"} ${oneLine(task.title)}
+${task.taskId}`);
+    }
+    return 0;
+  } catch (error) {
+    let message = io.signal?.aborted ? "Cancelled." : error instanceof z2.ZodError ? "Haunter returned an unexpected response. Update the CLI and try again." : error instanceof Error ? error.message : "Haunter could not complete the command.";
+    for (const secret of secrets)
+      message = message.replaceAll(secret, "[redacted]");
+    io.stderr(json ? `${JSON.stringify({ error: safeText(message) })}
+` : `haunter: ${safeText(message)}
+`);
+    return io.signal?.aborted ? 130 : 1;
+  } finally {
+    await client?.close().catch(() => {});
+    await release?.().catch(() => {
+      const error = "Could not remove the command lock. Check the configuration directory before retrying.";
+      io.stderr(json ? `${JSON.stringify({ error })}
+` : `haunter: ${error}
+`);
+    });
+  }
+}
+function uuid(value) {
+  if (!z2.uuid().safeParse(value).success)
+    throw new Error("Expected a page or task ID in UUID format.");
+  return value;
+}
+async function captureText(text, file, io) {
+  if (text !== undefined) {
+    if (text.length > 1e5)
+      throw new Error("Capture text exceeds 100,000 characters.");
+    return text;
+  }
+  if (!file && io.isTTY)
+    throw new Error("Provide capture text, --file <path>, or pipe Markdown into haunter capture.");
+  const input = file && file !== "-" ? createReadStream(file) : io.stdin;
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of input) {
+    io.signal?.throwIfAborted();
+    const buffer = Buffer.from(chunk);
+    bytes += buffer.length;
+    if (bytes > 400000)
+      throw new Error("Capture text exceeds 100,000 characters.");
+    chunks.push(buffer);
+  }
+  const markdown = Buffer.concat(chunks).toString("utf8");
+  if (!markdown.trim())
+    throw new Error("There is no text to capture.");
+  if (markdown.length > 1e5)
+    throw new Error("Capture text exceeds 100,000 characters.");
+  return markdown;
+}
+function safeText(value) {
+  return stripVTControlCharacters(value).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
+function oneLine(value) {
+  return safeText(value).replace(/\s+/g, " ");
+}
+
+// src/index.ts
+var controller = new AbortController;
+var brokenPipe = false;
+var cancel = () => {
+  controller.abort();
+  process.stdin.destroy();
+};
+process.once("SIGINT", cancel);
+process.once("SIGTERM", cancel);
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") {
+    brokenPipe = true;
+    controller.abort();
+    process.exitCode = 0;
+  } else
+    throw error;
+});
+process.exitCode = await runCli(process.argv.slice(2), {
+  stdout: (text) => {
+    process.stdout.write(text);
+  },
+  stderr: (text) => {
+    process.stderr.write(text);
+  },
+  stdin: process.stdin,
+  isTTY: Boolean(process.stdin.isTTY),
+  env: process.env,
+  signal: controller.signal
+});
+process.removeListener("SIGINT", cancel);
+process.removeListener("SIGTERM", cancel);
+if (brokenPipe)
+  process.exitCode = 0;

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "haunter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "haunter",
+	"version": "0.1.0",
+	"description": "Pages, notes, and tasks in Haunter from your terminal.",
+	"type": "module",
+	"bin": {
+		"haunter": "dist/index.js"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"packageManager": "bun@1.4.2",
+	"license": "MIT",
+	"author": "Haunter contributors",
+	"homepage": "https://www.haunter.app",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/taylorbryant/haunter.git",
+		"directory": "packages/cli"
+	},
+	"bugs": {
+		"url": "https://github.com/taylorbryant/haunter/issues"
+	},
+	"keywords": [
+		"haunter",
+		"cli",
+		"notes",
+		"tasks",
+		"markdown"
+	],
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"scripts": {
+		"build": "bun scripts/build.ts",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test tests",
+		"check": "bun run typecheck && bun run test && bun run build",
+		"verify:package": "bun scripts/verify-package.ts",
+		"prepack": "bun run check"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "1.32.1",
+		"zod": "4.6.7"
+	},
+	"devDependencies": {
+		"@types/bun": "1.4.3",
+		"@types/node": "26.6.5",
+		"typescript": "7.0.2"
+	}
+}