palcli1 1.0.2

package/README.md

@@ -0,0 +1,101 @@
+# `pal-cli` (npm package)
+
+Thin command-line client for **PAL**: it calls your **hosted** PAL API (`/api/me`, `/api/conversations`, …). It does **not** connect to Postgres or load `GOOGLE_API_KEY` locally—those stay on the server.
+
+**Package name:** the unscoped name `palcli` is blocked by npm (too close to the existing package `pal-cli`). This package is published as **`palcli`**. To use your own scope, change the `name` field in `package.json` to `@your-npm-username/palcli` before publishing.
+
+## Prerequisites
+
+- **Node.js 20+**
+- A running PAL **server** (`server/` in this repo) with Postgres, migrations, and env vars set (see `server/.env.example`).
+- A **GitHub OAuth App** with the callback URL matching your server, e.g. `https://your-api.example.com/api/auth/callback/github`, and **Device flow** enabled where GitHub requires it.
+
+## Global command name: `pal-cli`
+
+The npm **binary** is **`pal-cli`** (with a hyphen), not `palcli`. That avoids a common **Windows** problem: the server package exposes **`palCLI`**, and on a case-insensitive filesystem `palCLI` and `palcli` are treated as the same global shim, so `npm link` can hit **EEXIST** and `palcli` in your PATH may run the **wrong** CLI.
+
+## Install from this monorepo (development)
+
+```bash
+cd packages/palcli
+npm install
+node ./bin/palcli.js --help
+```
+
+### `npm link` on Windows (EEXIST)
+
+1. See what is using the name (often the server CLI): `npm ls -g --depth=0`
+2. Unlink the old tool if needed: `npm unlink -g server` (or whatever package installed the conflicting bin)
+3. Remove stale shims if they remain, e.g. delete `palcli`, `palcli.cmd`, `palCLI`, `palCLI.cmd` under `%AppData%\Roaming\npm\` **only if** you know they are leftovers
+4. Link this package: `npm link` (creates **`pal-cli`** globally)
+5. Run: `pal-cli --help`
+
+If npm still complains, use **`npm link --force`** after backing up/removing the conflicting file it names in the error.
+
+## Configure before publishing to npm
+
+1. Edit **`src/publish-config.js`**:
+   - Set **`PUBLISH_API_URL`** to your public API base URL (same value as server `BETTER_AUTH_URL` / `API_PUBLIC_URL`).
+   - Set **`PUBLISH_GITHUB_CLIENT_ID`** to the GitHub OAuth App’s **Client ID** (public). Never put the **client secret** in this file or in the published package.
+
+2. On the **server**, set matching env (see `server/.env.example`):
+   - `BETTER_AUTH_URL`, `TRUSTED_ORIGINS`, `CLIENT_APP_URL`, `CORS_ORIGIN`, `GITHUB_*`, `GOOGLE_API_KEY`, `DATABASE_URL`, etc.
+
+3. Optional overrides for testers (no publish needed):
+   - `PALCLI_API_URL` — API base URL
+   - `PALCLI_GITHUB_CLIENT_ID` — GitHub Client ID
+
+## Publish to npm
+
+The package is **scoped** (`pal-cli`) so it does not collide with the existing **`pal-cli`** package on the registry.
+
+```bash
+cd packages/palcli
+npm whoami   # must be logged in; scope must match your npm user/org
+npm publish
+# publishConfig.access is already "public" in package.json
+```
+
+### `403 Forbidden` — “Two-factor authentication … is required to publish”
+
+npm now requires **either**:
+
+- **2FA on your account** with **“Authorization and publishing”** (not “Auth only”), then publish again with `npm publish` (you may be prompted for an OTP), **or**
+- A **granular access token** with permission to **write/publish** packages (and “bypass 2FA” if your org policy requires it), then:  
+  `npm config set //registry.npmjs.org/:_authToken=YOUR_TOKEN`
+
+Configure this at [npmjs.com](https://www.npmjs.com/) → **Access Tokens** / **Two-Factor Authentication**.
+
+Optional: run `npm pkg fix` in this folder if `npm publish` warns about `package.json`.
+
+**Private package (invite-only):** use an npm org private package or GitHub Packages; add collaborators in npm UI.
+
+## Device login and `localhost:3000`
+
+`pal-cli login` opens the **web app** URL (usually `http://localhost:3000/device?...`) so you can enter the device code. That page is **Next.js** (`client/`), not Express. If Edge shows **connection refused**, start the client:
+
+```bash
+cd client
+npm run dev
+```
+
+Keep the **API** running on port 3005 (`cd server && npm run dev`) and set the client’s API base URL (e.g. `NEXT_PUBLIC_*` / `auth-client` `baseURL`) to match.
+
+## End-user commands
+
+```bash
+pal-cli login     # device flow; opens browser
+pal-cli whoami    # GET /api/me
+pal-cli chat      # create conversation + chat via POST .../messages
+pal-cli wakeup    # menu → chat
+pal-cli logout    # delete ~/.palcli/credentials.json
+```
+
+After `npm install -g pal-cli`, the command is still **`pal-cli`** (see `package.json` → `bin`).
+
+Credentials are stored under **`~/.palcli/credentials.json`**.
+
+## Security reminders
+
+- Do **not** ship database URLs, Google keys, or GitHub **client secrets** in this package.
+- Publishing with real `PUBLISH_API_URL` + `PUBLISH_GITHUB_CLIENT_ID` only tells the world **where** to authenticate; access is still gated by your server and OAuth.

package/bin/palcli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/main.js";

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "palcli1",
+  "version": "1.0.2",
+  "description": "Thin CLI for PAL — talks to your hosted PAL API (no local database).",
+  "type": "module",
+  "main": "./src/main.js",
+  "bin": {
+    "pal-cli": "bin/palcli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pal-cli",
+    "cli",
+    "ai",
+    "chat"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "better-auth": "^1.5.6",
+    "boxen": "^8.0.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "figlet": "^1.11.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "open": "^11.0.0",
+    "yocto-spinner": "^1.1.0",
+    "zod": "^4.3.6"
+  }
+}

package/src/commands/chat-session.js

@@ -0,0 +1,154 @@
+import { intro, isCancel, outro, text } from "@clack/prompts";
+import chalk from "chalk";
+import boxen from "boxen";
+import yoctoSpinner from "yocto-spinner";
+import { getApiUrl } from "../config.js";
+import { apiRequest } from "../lib/api.js";
+import { renderMarkdown } from "../lib/markdown.js";
+import {
+  getStoredToken,
+  isTokenExpired,
+} from "../lib/token-store.js";
+
+async function getBearer() {
+  const token = await getStoredToken();
+  if (!token?.access_token || (await isTokenExpired())) {
+    throw new Error("Not signed in. Run: pal-cli login");
+  }
+  return token.access_token;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {string} mode
+ */
+export async function runChatSession(baseUrl, mode = "chat") {
+  const tokenGetter = getBearer;
+
+  const spin = yoctoSpinner({ text: "Starting conversation…" }).start();
+  let conversation;
+  try {
+    const created = await apiRequest(baseUrl, tokenGetter, "/api/conversations", {
+      method: "POST",
+      body: JSON.stringify({ mode }),
+    });
+    conversation = created?.data;
+    if (!conversation?.id) throw new Error("Could not create conversation");
+    spin.success("Ready");
+  } catch (e) {
+    spin.error("Failed");
+    throw e;
+  }
+
+  console.log(
+    boxen(
+      `${chalk.bold("Conversation")}: ${conversation.title}\n${chalk.gray("ID: " + conversation.id)}`,
+      {
+        padding: 1,
+        margin: { top: 1, bottom: 1 },
+        borderStyle: "round",
+        borderColor: "cyan",
+        title: "PAL chat",
+        titleAlignment: "center",
+      },
+    ),
+  );
+
+  const help = boxen(
+    `${chalk.gray("Enter message · exit or quit to leave · Ctrl+C to abort")}`,
+    {
+      padding: 1,
+      margin: { bottom: 1 },
+      borderStyle: "round",
+      borderColor: "gray",
+      dimBorder: true,
+    },
+  );
+  console.log(help);
+
+  let firstExchange = true;
+
+  while (true) {
+    const userInput = await text({
+      message: chalk.blue("You"),
+      placeholder: "Message…",
+      validate(value) {
+        if (!value || !value.trim()) return "Message cannot be empty";
+      },
+    });
+
+    if (isCancel(userInput)) {
+      console.log(chalk.yellow("Bye."));
+      process.exit(0);
+    }
+
+    const trimmed = userInput.trim();
+    const lower = trimmed.toLowerCase();
+    if (lower === "exit" || lower === "quit") break;
+
+    const wait = yoctoSpinner({ text: "Thinking…" }).start();
+    try {
+      const res = await apiRequest(
+        baseUrl,
+        tokenGetter,
+        `/api/conversations/${conversation.id}/messages`,
+        {
+          method: "POST",
+          body: JSON.stringify({ content: trimmed, role: "user" }),
+        },
+      );
+      wait.stop();
+
+      const assistantContent = res?.data?.assistantMessage?.content;
+      if (assistantContent == null) {
+        throw new Error("No assistant reply in response");
+      }
+
+      if (firstExchange) {
+        firstExchange = false;
+        const title =
+          trimmed.slice(0, 50) + (trimmed.length > 50 ? "…" : "");
+        try {
+          await apiRequest(
+            baseUrl,
+            tokenGetter,
+            `/api/conversations/${conversation.id}`,
+            {
+              method: "PUT",
+              body: JSON.stringify({ title }),
+            },
+          );
+        } catch {
+          /* title update is best-effort */
+        }
+      }
+
+      const rendered = renderMarkdown(assistantContent);
+      console.log(
+        boxen(rendered.trim(), {
+          padding: 1,
+          margin: { left: 0, bottom: 1 },
+          borderStyle: "round",
+          borderColor: "green",
+          title: "Assistant",
+          titleAlignment: "left",
+        }),
+      );
+    } catch (e) {
+      wait.stop();
+      console.log(boxen(chalk.red(e.message), { padding: 1, borderColor: "red" }));
+    }
+  }
+
+  outro(chalk.green("Session ended."));
+}
+
+export async function startChatFromCli() {
+  intro(boxen(chalk.bold.cyan("PAL CLI chat"), { padding: 1, borderStyle: "double" }));
+  try {
+    await runChatSession(getApiUrl(), "chat");
+  } catch (e) {
+    console.log(boxen(chalk.red(e.message), { padding: 1, borderColor: "red" }));
+    process.exit(1);
+  }
+}

package/src/commands/login.js

@@ -0,0 +1,240 @@
+import { cancel, confirm, intro, isCancel, outro } from "@clack/prompts";
+import { createAuthClient } from "better-auth/client";
+import { deviceAuthorizationClient } from "better-auth/client/plugins";
+import chalk from "chalk";
+import { Command } from "commander";
+import open from "open";
+import yoctoSpinner from "yocto-spinner";
+import * as z from "zod";
+import { getApiUrl, getGithubClientId } from "../config.js";
+import {
+  getCredentialsPath,
+  getStoredToken,
+  isTokenExpired,
+  storeToken,
+} from "../lib/token-store.js";
+
+async function pollForToken(authClient, deviceCode, clientId, initialInterval) {
+  let pollingInterval = initialInterval;
+  const spinner = yoctoSpinner({ text: "", color: "cyan" });
+  let dots = 0;
+
+  return new Promise((resolve, reject) => {
+    const poll = async () => {
+      dots = (dots + 1) % 4;
+      spinner.text = chalk.gray(
+        `Polling for authorization${".".repeat(dots)}${" ".repeat(3 - dots)}`,
+      );
+      if (!spinner.isSpinning) spinner.start();
+
+      try {
+        const { data, error } = await authClient.device.token({
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: deviceCode,
+          client_id: clientId,
+          fetchOptions: {
+            headers: { "user-agent": "palcli" },
+          },
+        });
+
+        if (data?.access_token) {
+          spinner.stop();
+          resolve(data);
+          return;
+        }
+
+        if (error) {
+          switch (error.error) {
+            case "authorization_pending":
+              break;
+            case "slow_down":
+              pollingInterval += 5;
+              break;
+            case "access_denied":
+              spinner.stop();
+              reject(new Error("Access denied"));
+              return;
+            case "expired_token":
+              spinner.stop();
+              reject(new Error("Device code expired"));
+              return;
+            default:
+              spinner.stop();
+              reject(
+                new Error(error.error_description || error.error || "Token error"),
+              );
+              return;
+          }
+        }
+      } catch (err) {
+        spinner.stop();
+        reject(err);
+        return;
+      }
+
+      setTimeout(poll, pollingInterval * 1000);
+    };
+
+    setTimeout(poll, pollingInterval * 1000);
+  });
+}
+
+export async function loginAction(opts) {
+  const options = z
+    .object({
+      serverUrl: z.string().optional(),
+      clientId: z.string().optional(),
+    })
+    .parse(opts);
+
+  const serverUrl = options.serverUrl || getApiUrl();
+  const clientId = options.clientId || getGithubClientId();
+
+  intro(chalk.bold("PAL CLI — sign in"));
+
+  if (!clientId) {
+    console.log(
+      chalk.red(
+        "GitHub OAuth Client ID is not configured.\nThe package maintainer must set PUBLISH_GITHUB_CLIENT_ID in src/publish-config.js before publish,\nor set PALCLI_GITHUB_CLIENT_ID for local use.",
+      ),
+    );
+    process.exit(1);
+  }
+
+  const existingToken = await getStoredToken();
+  if (existingToken && !(await isTokenExpired())) {
+    const again = await confirm({
+      message: "Already signed in. Sign in again?",
+      initialValue: false,
+    });
+    if (isCancel(again) || !again) {
+      cancel("Cancelled");
+      process.exit(0);
+    }
+  }
+
+  const authClient = createAuthClient({
+    baseURL: serverUrl,
+    plugins: [deviceAuthorizationClient()],
+  });
+
+  const spinner = yoctoSpinner({ text: "Requesting device authorization" });
+  spinner.start();
+
+  try {
+    const { data, error } = await authClient.device.code({
+      client_id: clientId,
+      scope: "openid profile email",
+    });
+
+    spinner.stop();
+
+    if (error || !data) {
+      console.log(
+        chalk.red(
+          error?.error_description || error?.message || "Device code request failed",
+        ),
+      );
+      if (error?.status === 404) {
+        console.log(chalk.yellow("Is the server running at " + serverUrl + "?"));
+      }
+      process.exit(1);
+    }
+
+    const {
+      device_code,
+      user_code,
+      verification_uri,
+      verification_uri_complete,
+      interval = 5,
+      expires_in,
+    } = data;
+
+    console.log("");
+    console.log(chalk.cyan("Device sign-in"));
+    console.log(
+      chalk.white("Open: ") +
+        chalk.underline.blue(verification_uri_complete || verification_uri),
+    );
+    console.log(chalk.white("Code: ") + chalk.bold.green(user_code));
+    console.log("");
+    const verifyUrl = verification_uri_complete || verification_uri;
+    if (typeof verifyUrl === "string" && verifyUrl.includes("localhost:3000")) {
+      console.log(
+        chalk.yellow(
+          "Tip: this URL is served by the Next.js app, not the API. If the browser says connection refused, run:\n  cd client && npm run dev\n",
+        ),
+      );
+    }
+
+    const shouldOpen = await confirm({
+      message: "Open browser automatically?",
+      initialValue: true,
+    });
+
+    if (!isCancel(shouldOpen) && shouldOpen) {
+      await open(verification_uri_complete || verification_uri);
+    }
+
+    console.log(
+      chalk.gray(
+        `Waiting (expires in ~${Math.floor(expires_in / 60)} min)…`,
+      ),
+    );
+
+    const token = await pollForToken(
+      authClient,
+      device_code,
+      clientId,
+      interval,
+    );
+
+    await storeToken(token);
+
+    const { data: session } = await authClient.getSession({
+      fetchOptions: {
+        headers: { Authorization: `Bearer ${token.access_token}` },
+      },
+    });
+
+    outro(
+      chalk.green(
+        `Signed in as ${session?.user?.name || session?.user?.email || "user"}`,
+      ),
+    );
+    console.log(chalk.gray(`Credentials: ${getCredentialsPath()}\n`));
+  } catch (err) {
+    spinner.stop();
+    console.error(chalk.red("Login failed:"), err.message);
+    process.exit(1);
+  }
+}
+
+export async function logoutAction() {
+  intro(chalk.bold("Sign out"));
+  const token = await getStoredToken();
+  if (!token) {
+    console.log(chalk.yellow("Not signed in."));
+    process.exit(0);
+  }
+  const ok = await confirm({
+    message: "Clear saved credentials?",
+    initialValue: true,
+  });
+  if (isCancel(ok) || !ok) {
+    cancel("Cancelled");
+    process.exit(0);
+  }
+  await clearStoredToken();
+  outro(chalk.green("Signed out."));
+}
+
+export const login = new Command("login")
+  .description("Sign in with GitHub (device flow)")
+  .option("--server-url <url>", "PAL API base URL (Better Auth)")
+  .option("--client-id <id>", "GitHub OAuth App client ID")
+  .action(loginAction);
+
+export const logout = new Command("logout")
+  .description("Remove saved credentials")
+  .action(logoutAction);

package/src/commands/wakeup.js

@@ -0,0 +1,73 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { select, isCancel, cancel } from "@clack/prompts";
+import yoctoSpinner from "yocto-spinner";
+import { getApiUrl } from "../config.js";
+import { apiRequest } from "../lib/api.js";
+import {
+  getStoredToken,
+  isTokenExpired,
+} from "../lib/token-store.js";
+import { runChatSession } from "./chat-session.js";
+
+async function getBearer() {
+  const token = await getStoredToken();
+  if (!token?.access_token || (await isTokenExpired())) {
+    console.log(chalk.red("Not signed in. Run: pal-cli login"));
+    process.exit(1);
+  }
+  return token.access_token;
+}
+
+async function wakeupAction() {
+  const baseUrl = getApiUrl();
+  const spin = yoctoSpinner({ text: "Loading profile…" }).start();
+  try {
+    const json = await apiRequest(baseUrl, getBearer, "/api/me", {
+      method: "GET",
+    });
+    spin.stop();
+    const user = json?.data;
+    if (!user) {
+      console.log(chalk.red("Unexpected /api/me response"));
+      process.exit(1);
+    }
+    console.log(chalk.green(`\nHi, ${user.name}!\n`));
+  } catch (e) {
+    spin.stop();
+    console.log(chalk.red(e.message));
+    process.exit(1);
+  }
+
+  const choice = await select({
+    message: "What do you want to do?",
+    options: [
+      { value: "chat", label: "Chat", hint: "Talk to the assistant (uses your hosted API)" },
+      {
+        value: "tools",
+        label: "Tool / agent mode",
+        hint: "Use the web app for tool & agent flows for now",
+      },
+    ],
+  });
+
+  if (isCancel(choice)) {
+    cancel("Cancelled");
+    process.exit(0);
+  }
+
+  if (choice === "tools") {
+    console.log(
+      chalk.yellow(
+        "\nTool and agent modes are not exposed in this CLI yet. Use the Next.js app or the in-repo server CLI.\n",
+      ),
+    );
+    process.exit(0);
+  }
+
+  await runChatSession(baseUrl, "chat");
+}
+
+export const wakeup = new Command("wakeup")
+  .description("Open the PAL menu (chat via API)")
+  .action(wakeupAction);

package/src/commands/whoami.js

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { getApiUrl } from "../config.js";
+import { apiRequest } from "../lib/api.js";
+import {
+  getStoredToken,
+  isTokenExpired,
+} from "../lib/token-store.js";
+
+async function getBearer() {
+  const token = await getStoredToken();
+  if (!token?.access_token || (await isTokenExpired())) {
+    console.log(chalk.red("Not signed in. Run: pal-cli login"));
+    process.exit(1);
+  }
+  return token.access_token;
+}
+
+export async function whoamiAction(opts) {
+  const baseUrl = opts.serverUrl || getApiUrl();
+  try {
+    const json = await apiRequest(baseUrl, getBearer, "/api/me", {
+      method: "GET",
+    });
+    const user = json?.data;
+    if (!user) {
+      console.log(chalk.red("Unexpected response from /api/me"));
+      process.exit(1);
+    }
+    console.log(
+      chalk.bold.green(`\n${user.name}\n`) +
+        chalk.gray(`email: ${user.email}\nid:   ${user.id}\n`),
+    );
+  } catch (e) {
+    console.log(chalk.red(e.message));
+    process.exit(1);
+  }
+}
+
+export const whoami = new Command("whoami")
+  .description("Show signed-in user (from API)")
+  .option("--server-url <url>", "PAL API base URL")
+  .action(whoamiAction);

package/src/config.js

@@ -0,0 +1,16 @@
+import {
+  PUBLISH_API_URL,
+  PUBLISH_GITHUB_CLIENT_ID,
+} from "./publish-config.js";
+
+/** @returns {string} */
+export function getApiUrl() {
+  const fromEnv = process.env.PALCLI_API_URL;
+  if (fromEnv) return fromEnv.replace(/\/$/, "");
+  return PUBLISH_API_URL.replace(/\/$/, "");
+}
+
+/** @returns {string} */
+export function getGithubClientId() {
+  return process.env.PALCLI_GITHUB_CLIENT_ID || PUBLISH_GITHUB_CLIENT_ID;
+}

package/src/lib/api.js

@@ -0,0 +1,41 @@
+/**
+ * @param {string} baseUrl
+ * @param {() => Promise<string|null>} getBearerToken
+ * @param {string} path
+ * @param {RequestInit} [init]
+ */
+export async function apiRequest(baseUrl, getBearerToken, path, init = {}) {
+  const root = baseUrl.replace(/\/$/, "");
+  const url = `${root}${path.startsWith("/") ? path : `/${path}`}`;
+  const headers = new Headers(init.headers || {});
+  if (!headers.has("Content-Type") && init.body) {
+    headers.set("Content-Type", "application/json");
+  }
+  const token = await getBearerToken();
+  if (token) headers.set("Authorization", `Bearer ${token}`);
+
+  const res = await fetch(url, { ...init, headers });
+  const text = await res.text();
+  let json = null;
+  if (text) {
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`Non-JSON response (${res.status}): ${text.slice(0, 200)}`);
+    }
+  }
+
+  if (!res.ok) {
+    const msg =
+      json?.error?.message ||
+      json?.message ||
+      (typeof json === "string" ? json : null) ||
+      `Request failed (${res.status})`;
+    const err = new Error(msg);
+    err.status = res.status;
+    err.body = json;
+    throw err;
+  }
+
+  return json;
+}

package/src/lib/markdown.js

@@ -0,0 +1,26 @@
+import chalk from "chalk";
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+
+marked.use(
+  markedTerminal({
+    code: chalk.cyan,
+    blockquote: chalk.gray.italic,
+    heading: chalk.green.bold,
+    firstHeading: chalk.magenta.underline.bold,
+    hr: chalk.reset,
+    listitem: chalk.reset,
+    list: chalk.reset,
+    paragraph: chalk.reset,
+    strong: chalk.bold,
+    em: chalk.italic,
+    codespan: chalk.yellow.bgBlack,
+    del: chalk.dim.gray.strikethrough,
+    link: chalk.blue.underline,
+    href: chalk.blue.underline,
+  }),
+);
+
+export function renderMarkdown(text) {
+  return marked.parse(text || "");
+}

package/src/lib/token-store.js

@@ -0,0 +1,55 @@
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+const CONFIG_DIR = path.join(os.homedir(), ".palcli");
+const TOKEN_FILE = path.join(CONFIG_DIR, "credentials.json");
+
+export async function getStoredToken() {
+  try {
+    const data = await fs.readFile(TOKEN_FILE, "utf-8");
+    return JSON.parse(data);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      console.warn("Could not read credentials:", error.message);
+    }
+    return null;
+  }
+}
+
+export async function storeToken(token) {
+  await fs.mkdir(CONFIG_DIR, { recursive: true });
+  const tokenData = {
+    access_token: token.access_token,
+    refresh_token: token.refresh_token,
+    token_type: token.token_type || "Bearer",
+    scope: token.scope,
+    expires_at: token.expires_in
+      ? new Date(Date.now() + token.expires_in * 1000).toISOString()
+      : null,
+    created_at: new Date().toISOString(),
+  };
+  await fs.writeFile(TOKEN_FILE, JSON.stringify(tokenData, null, 2), "utf-8");
+  return true;
+}
+
+export async function clearStoredToken() {
+  try {
+    await fs.unlink(TOKEN_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isTokenExpired() {
+  const token = await getStoredToken();
+  if (!token?.expires_at) return true;
+  const expiresAt = new Date(token.expires_at);
+  const now = new Date();
+  return expiresAt.getTime() - now.getTime() < 5 * 60 * 1000;
+}
+
+export function getCredentialsPath() {
+  return TOKEN_FILE;
+}

package/src/main.js

@@ -0,0 +1,47 @@
+import chalk from "chalk";
+import figlet from "figlet";
+import { Command } from "commander";
+import { login, logout } from "./commands/login.js";
+import { whoami } from "./commands/whoami.js";
+import { wakeup } from "./commands/wakeup.js";
+import { startChatFromCli } from "./commands/chat-session.js";
+
+async function main() {
+  console.log(
+    chalk.cyan(
+      figlet.textSync("PAL CLI", {
+        font: "Standard",
+        horizontalLayout: "default",
+      }),
+    ),
+  );
+  console.log(chalk.gray("Thin client — your API holds secrets & data.\n"));
+
+  const program = new Command("pal-cli");
+
+  program
+    .name("pal-cli")
+    .version("1.0.2")
+    .description("PAL command-line client (hosted API)");
+
+  program
+    .command("chat")
+    .description("Start a chat session (creates a conversation on the server)")
+    .action(() => startChatFromCli());
+
+  program.addCommand(login);
+  program.addCommand(logout);
+  program.addCommand(whoami);
+  program.addCommand(wakeup);
+
+  program.action(() => {
+    program.help();
+  });
+
+  await program.parseAsync(process.argv);
+}
+
+main().catch((err) => {
+  console.error(chalk.red("pal-cli error:"), err);
+  process.exit(1);
+});

package/src/publish-config.js

@@ -0,0 +1,11 @@
+/**
+ * Maintainer: set these values before `npm publish` so end users need no environment variables.
+ *
+ * - PUBLISH_API_URL: public HTTPS URL of your deployed PAL server (same origin as Better Auth).
+ * - PUBLISH_GITHUB_CLIENT_ID: GitHub OAuth App "Client ID" only (public). Never put the client secret here.
+ */
+
+export const PUBLISH_API_URL = "http://localhost:3005";
+
+export const PUBLISH_GITHUB_CLIENT_ID = "Ov23lidEB9IMI5wCN9Nq";
+