@logicpanel/lphub 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# @logicpanel/lphub
+
+A thin command-line client for the LogicPanel Hub `/api/v1`. It authenticates with a
+Personal Access Token (PAT) and forwards requests — the **API is the source of truth**.
+The command tree (commands, options, help) is generated from a server **manifest**
+(`GET /api/v1/cli-manifest`) and cached locally, so the CLI needs almost no maintenance:
+when the API changes, you run `lphub sync`, not a rebuild.
+
+## Install
+
+Requires Node.js >= 18.
+
+```bash
+# Global install — exposes the `lphub` command
+npm i -g @logicpanel/lphub
+lphub --help
+
+# …or run it without installing
+npx @logicpanel/lphub --help
+```
+
+### From source (this monorepo)
+
+```bash
+pnpm install                                 # once — workspace dependencies
+pnpm --filter @logicpanel/lphub build        # compile → packages/lphub/dist/index.js
+cd packages/lphub && pnpm link --global      # expose `lphub` globally (symlink to dist/)
+```
+
+## First-time setup
+
+```bash
+lphub auth login   # prompts for profile name, base URL and PAT token (validates via /auth/me)
+lphub sync         # downloads the real manifest → ~/.lphub/manifest.json
+lphub ticket list  # now the real, API-driven commands work
+```
+
+## Updating
+
+There are **two different updates** — don't confuse them:
+
+| What changed | What to run |
+| --- | --- |
+| **The API** (new endpoint, field or filter) | `lphub sync` — no reinstall; commands are manifest-driven |
+| **The CLI itself** (new release on npm) | `npm i -g @logicpanel/lphub@latest` |
+| **The CLI from source** (local dev) | `pnpm --filter @logicpanel/lphub build` (the global symlink picks up the new `dist/`) |
+
+For active development, `pnpm --filter @logicpanel/lphub dev` runs `tsup --watch`.
+
+90% of the time, keeping up with the backend is just `lphub sync`.
+
+## Uninstall
+
+```bash
+npm uninstall -g @logicpanel/lphub          # or, if linked from source:
+pnpm uninstall --global @logicpanel/lphub
+```
+
+## Profiles & servers (prod vs local)
+
+Each **profile** bundles a server (`baseUrl`) and its token, stored in `~/.lphub/config.json`.
+Multiple servers = multiple profiles — no need to edit anything by hand.
+
+```bash
+lphub auth login            # e.g. profile "prod"  → https://api-hub.hrplane.com/api/v1
+lphub auth login            # e.g. profile "local" → http://localhost:8484/api/v1
+lphub auth list             # lists profiles, marks the current one
+lphub auth switch local     # set the default profile
+lphub --profile prod ticket list   # one-off override
+```
+
+Two optional escape hatches override the active profile's base URL (precedence:
+flag > env > profile):
+
+```bash
+lphub --base-url http://localhost:8484/api/v1 ticket list
+export LPHUB_BASE_URL=http://localhost:8484/api/v1
+```
+
+## Directory context (`lphub init`)
+
+Pin a profile + project to the current directory so commands auto-scope to it — like
+`gh` inferring the repo from the folder. The file is **personal**, keep it out of git.
+
+```bash
+echo .lphub.json >> .gitignore
+lphub init                  # choose profile + project → writes .lphub.json { profile, projectId }
+
+lphub ticket list           # auto-scoped to the pinned project
+lphub ticket create --title "Bug X"          # project_id injected from context
+lphub ticket create --title "Y" --project-id 99   # an explicit flag always wins
+```
+
+Resolution — project: `--project-id` flag > `.lphub.json` > error if required.
+Profile: `--profile` > `LPHUB_PROFILE` env > `.lphub.json` > current profile.
+
+## Output
+
+The default is a human-friendly table (like `gh`). Use flags for machine-readable output:
+
+```bash
+lphub ticket list                                   # table
+lphub ticket list --json                            # raw JSON
+lphub ticket list --fields id,title,status,project.name   # projected columns (dot-paths)
+```
+
+## Long / Markdown fields
+
+For any string option you can read the value from a file or STDIN, instead of a flag
+(useful for Markdown ticket descriptions — like `gh issue create --body-file`):
+
+```bash
+lphub ticket create --title "..." --description-file ./body.md
+lphub ticket create --title "..." --description-file -   # read from STDIN
+```
+
+## Other commands
+
+```bash
+lphub me              # the authenticated user (whoami)
+lphub auth status     # active profile + whoami
+lphub docs            # list topics;  `lphub docs tickets`  prints a topic's examples
+lphub agent setup     # fetch the agent skill from the API and install it via skills.sh
+```
+
+`lphub agent setup` downloads the SKILL.md from the API and hands it to
+[`skills.sh`](https://www.skills.sh) (`npx skills add`), which installs it into your agent
+(Claude Code, Cursor, …). Forward flags through, e.g. `lphub agent setup --agent claude-code -y`.
+
+Destructive commands (HTTP `DELETE`) ask for confirmation; pass `-y`/`--yes` to skip
+(also skipped automatically when not running in a TTY).
+
+## Exit codes
+
+`0` success · `4` auth failure (401/403) · `1` any other error.
+
+## Publishing
+
+```bash
+cd packages/lphub
+npm version patch          # bump the version
+npm publish                # `prepack` builds dist/ first; only dist/ + README ship
+```
+
+To verify what would ship without publishing:
+
+```bash
+npm pack --dry-run         # lists the tarball contents (dist/index.js, package.json, README)
+```
+
+The package is scoped (`@logicpanel/lphub`). To publish to a **private registry** (e.g. the
+GitLab npm registry) instead of public npm, point npm at it — drop the public default with
+`--access restricted` or a `.npmrc` `@logicpanel:registry=...` entry.

package/dist/index.js

@@ -0,0 +1,936 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/auth.ts
+import * as readline from "readline";
+
+// src/config.ts
+import { homedir } from "os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+function getConfigPath() {
+  return join(homedir(), ".lphub", "config.json");
+}
+function getManifestPath() {
+  return join(homedir(), ".lphub", "manifest.json");
+}
+function ensureDir(p) {
+  mkdirSync(p, { recursive: true });
+}
+function loadConfig() {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveConfig(config) {
+  const configPath = getConfigPath();
+  ensureDir(dirname(configPath));
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+var baseUrlOverride;
+var contextProfile;
+function setBaseUrlOverride(url) {
+  baseUrlOverride = url?.trim() || void 0;
+}
+function setContextProfile(name) {
+  contextProfile = name?.trim() || void 0;
+}
+function resolveBaseUrl(profile) {
+  return baseUrlOverride ?? process.env["LPHUB_BASE_URL"] ?? profile.baseUrl;
+}
+function getActiveProfile(profileOverride) {
+  const config = loadConfig();
+  if (!config) return null;
+  const profileName = profileOverride ?? process.env["LPHUB_PROFILE"] ?? contextProfile ?? config.currentProfile ?? "default";
+  const profile = config.profiles[profileName];
+  if (!profile) return null;
+  return { ...profile, baseUrl: resolveBaseUrl(profile) };
+}
+function saveManifest(data) {
+  const manifestPath = getManifestPath();
+  ensureDir(dirname(manifestPath));
+  writeFileSync(manifestPath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(status, body) {
+    super(`HTTP ${status}`);
+    this.status = status;
+    this.body = body;
+  }
+};
+var NetworkError = class extends Error {
+  constructor(origin, code) {
+    super(`Cannot reach ${origin}${code ? ` (${code})` : ""}`);
+    this.origin = origin;
+    this.code = code;
+    this.name = "NetworkError";
+  }
+};
+function exitCodeFor(status) {
+  return status === 401 || status === 403 ? 4 : 1;
+}
+async function apiRequest(profile, method, path, body, query) {
+  const base = profile.baseUrl.replace(/\/$/, "");
+  let url;
+  const invalidBaseUrl = () => new Error(
+    `Invalid base URL "${profile.baseUrl}" \u2014 must start with http:// or https:// (fix it with \`lphub auth login\` or --base-url)`
+  );
+  try {
+    url = new URL(`${base}${path}`);
+  } catch {
+    throw invalidBaseUrl();
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw invalidBaseUrl();
+  }
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  const headers = {
+    Authorization: `Bearer ${profile.token}`,
+    Accept: "application/json",
+    "Content-Type": "application/json"
+  };
+  let response;
+  try {
+    response = await fetch(url.toString(), {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+  } catch (err) {
+    const cause = err?.cause;
+    const code = cause?.code ?? cause?.errors?.find((e) => e?.code)?.code;
+    throw new NetworkError(url.origin, code);
+  }
+  let responseBody;
+  try {
+    responseBody = await response.json();
+  } catch {
+    responseBody = await response.text().catch(() => "");
+  }
+  if (!response.ok) {
+    throw new ApiError(response.status, responseBody);
+  }
+  return responseBody;
+}
+
+// src/render.ts
+var MAX_CELL = 40;
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isScalar(v) {
+  return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+function getPath(obj, path) {
+  let cur = obj;
+  for (const seg of path.split(".")) {
+    if (!isPlainObject(cur) && !Array.isArray(cur)) return void 0;
+    cur = cur[seg];
+    if (cur === void 0) return void 0;
+  }
+  return cur;
+}
+function objectLabel(obj) {
+  for (const key of ["name", "title", "full_name", "label"]) {
+    const v = obj[key];
+    if (isScalar(v) && v !== null) return String(v);
+  }
+  const id = obj["id"];
+  if (isScalar(id) && id !== null) return `#${String(id)}`;
+  return "{\u2026}";
+}
+function cellValue(v) {
+  if (v === void 0 || v === null) return "";
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (isScalar(v)) return String(v);
+  if (isPlainObject(v)) return objectLabel(v);
+  if (Array.isArray(v)) return `[${v.length}]`;
+  return String(v);
+}
+function truncate(s, max = MAX_CELL) {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "\u2026";
+}
+function inferColumns(rows) {
+  const cols = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const [key, val] of Object.entries(row)) {
+      if (seen.has(key)) continue;
+      if (Array.isArray(val)) continue;
+      if (isScalar(val) || isPlainObject(val)) {
+        seen.add(key);
+        cols.push(key);
+      }
+    }
+  }
+  return cols;
+}
+function renderTable(headers, rows) {
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const fmtRow = (cells) => cells.map((c, i) => (c ?? "").padEnd(widths[i])).join("  ").trimEnd();
+  const lines = [];
+  lines.push(fmtRow(headers.map((h) => h.toUpperCase())));
+  for (const r of rows) lines.push(fmtRow(r));
+  return lines.join("\n");
+}
+function renderKeyValue(obj) {
+  const keys = Object.keys(obj);
+  const width = Math.max(0, ...keys.map((k) => k.length));
+  return keys.map((k) => `${k.padEnd(width)}  ${truncate(cellValue(obj[k]))}`).join("\n");
+}
+function projectRow(item, fields) {
+  return fields.map((f) => truncate(cellValue(getPath(item, f))));
+}
+function renderHuman(data, fields) {
+  let payload = data;
+  if (isPlainObject(data) && "data" in data) {
+    payload = data["data"];
+  }
+  if (Array.isArray(payload)) {
+    const objRows = payload.filter(isPlainObject);
+    if (objRows.length === 0) {
+      if (payload.length === 0) return "(no results)";
+      return payload.map((v) => cellValue(v)).join("\n");
+    }
+    const cols = fields && fields.length > 0 ? fields : inferColumns(objRows);
+    const rows = objRows.map(
+      (item) => fields && fields.length > 0 ? projectRow(item, fields) : cols.map((c) => truncate(cellValue(item[c])))
+    );
+    return renderTable(cols, rows);
+  }
+  if (isPlainObject(payload)) {
+    if (fields && fields.length > 0) {
+      const projected = {};
+      for (const f of fields) projected[f] = getPath(payload, f);
+      return renderKeyValue(projected);
+    }
+    return renderKeyValue(payload);
+  }
+  return cellValue(payload);
+}
+
+// src/output.ts
+function printJson(data, raw = false) {
+  if (raw) {
+    process.stdout.write(JSON.stringify(data) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  }
+}
+function printResult(data, opts = {}) {
+  if (opts.json) {
+    printJson(data, true);
+    return;
+  }
+  process.stdout.write(renderHuman(data, opts.fields) + "\n");
+}
+function printError(msg, detail) {
+  process.stderr.write(`Error: ${msg}
+`);
+  if (detail !== void 0) {
+    process.stderr.write(JSON.stringify(detail, null, 2) + "\n");
+  }
+}
+function printValidationError(body) {
+  if (typeof body !== "object" || body === null) return false;
+  const b = body;
+  const errors = b["errors"];
+  if (typeof errors !== "object" || errors === null) {
+    if (typeof b["message"] === "string") {
+      process.stderr.write(`Error: ${b["message"]}
+`);
+      return true;
+    }
+    return false;
+  }
+  if (typeof b["message"] === "string") {
+    process.stderr.write(`Error: ${b["message"]}
+`);
+  } else {
+    process.stderr.write("Error: validation failed\n");
+  }
+  for (const [field, msgs] of Object.entries(errors)) {
+    const list = Array.isArray(msgs) ? msgs : [msgs];
+    for (const m of list) {
+      process.stderr.write(`  - ${field}: ${String(m)}
+`);
+    }
+  }
+  return true;
+}
+
+// src/commands/auth.ts
+function prompt(rl, question) {
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => resolve2(answer));
+  });
+}
+async function authLogin() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const profileName = (await prompt(rl, "Profile name (default): ")).trim() || "default";
+    const baseUrl = (await prompt(rl, "Base URL (https://api-hub.hrplane.com/api/v1): ")).trim() || "https://api-hub.hrplane.com/api/v1";
+    const token = (await prompt(rl, "Token: ")).trim();
+    rl.close();
+    const config = loadConfig() ?? { currentProfile: profileName, profiles: {} };
+    config.profiles[profileName] = { baseUrl, token, profileName };
+    config.currentProfile = profileName;
+    saveConfig(config);
+    console.log(`
+Profile "${profileName}" saved and set as current.`);
+    try {
+      const profile = { baseUrl, token, profileName };
+      const me = await apiRequest(profile, "GET", "/auth/me");
+      console.log("\nAuthenticated successfully:");
+      printJson(me);
+    } catch (err) {
+      printError(
+        "Could not validate token (config saved anyway)",
+        err instanceof Error ? err.message : err
+      );
+    }
+  } catch (err) {
+    rl.close();
+    printError("Auth failed", err);
+    process.exit(1);
+  }
+}
+async function authStatus(profileOverride) {
+  const profile = getActiveProfile(profileOverride);
+  if (!profile) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  console.log(`Active profile: ${profile.profileName}`);
+  console.log(`Base URL:       ${profile.baseUrl}`);
+  try {
+    const me = await apiRequest(profile, "GET", "/auth/me");
+    console.log("\nLogged in as:");
+    printJson(me);
+  } catch (err) {
+    if (err instanceof ApiError) {
+      printError(`Token check failed (HTTP ${err.status})`, err.body);
+      process.exit(exitCodeFor(err.status));
+    }
+    printError("Could not reach the API", err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function authList() {
+  const config = loadConfig();
+  if (!config || Object.keys(config.profiles).length === 0) {
+    printError("No profiles configured. Run `lphub auth login`.");
+    process.exit(1);
+  }
+  for (const name of Object.keys(config.profiles)) {
+    const marker = name === config.currentProfile ? "*" : " ";
+    const p = config.profiles[name];
+    console.log(`${marker} ${name}  (${p.baseUrl})`);
+  }
+}
+function authSwitch(name) {
+  const config = loadConfig();
+  if (!config) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  if (!config.profiles[name]) {
+    printError(`Profile "${name}" not found. Run \`lphub auth list\` to see profiles.`);
+    process.exit(1);
+  }
+  config.currentProfile = name;
+  saveConfig(config);
+  console.log(`Switched to profile "${name}".`);
+}
+function authLogout(name) {
+  const config = loadConfig();
+  if (!config) {
+    printError("No config found.");
+    process.exit(1);
+  }
+  const target = name ?? config.currentProfile;
+  if (!config.profiles[target]) {
+    printError(`Profile "${target}" not found.`);
+    process.exit(1);
+  }
+  delete config.profiles[target];
+  if (config.currentProfile === target) {
+    const remaining = Object.keys(config.profiles);
+    config.currentProfile = remaining[0] ?? "";
+  }
+  saveConfig(config);
+  console.log(`Removed profile "${target}".`);
+  if (config.currentProfile) {
+    console.log(`Current profile is now "${config.currentProfile}".`);
+  } else {
+    console.log("No profiles remain. Run `lphub auth login` to add one.");
+  }
+}
+
+// src/commands/sync.ts
+async function syncCommand(profileOverride) {
+  const profile = getActiveProfile(profileOverride);
+  if (!profile) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  try {
+    const manifest = await apiRequest(profile, "GET", "/cli-manifest");
+    saveManifest(manifest);
+    const count = Array.isArray(manifest.commands) ? manifest.commands.length : 0;
+    console.log(`Manifest synced. ${count} top-level command(s) loaded.`);
+  } catch (err) {
+    if (err instanceof ApiError) {
+      printError(`Sync failed (HTTP ${err.status})`, err.body);
+      process.exit(exitCodeFor(err.status));
+    }
+    printError(err instanceof Error ? err.message : "Sync failed");
+    process.exit(1);
+  }
+}
+
+// src/commands/me.ts
+async function meCommand(profileOverride, opts = {}) {
+  const profile = getActiveProfile(profileOverride);
+  if (!profile) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  try {
+    const result = await apiRequest(profile, "GET", "/auth/me");
+    printResult(result, opts);
+  } catch (err) {
+    if (err instanceof ApiError) {
+      printError(`Request failed (HTTP ${err.status})`, err.body);
+      process.exit(exitCodeFor(err.status));
+    }
+    printError(err instanceof Error ? err.message : "Request failed");
+    process.exit(1);
+  }
+}
+
+// src/commands/agent-setup.ts
+import { spawnSync } from "child_process";
+import { mkdtempSync, writeFileSync as writeFileSync2 } from "fs";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+async function agentSetupCommand(passthrough = [], profileOverride) {
+  const profile = getActiveProfile(profileOverride);
+  if (!profile) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  let content;
+  try {
+    const res2 = await apiRequest(profile, "GET", "/cli-skill");
+    content = res2.content ?? "";
+    if (!content.trim()) {
+      printError("The API returned an empty skill.");
+      process.exit(1);
+    }
+  } catch (err) {
+    if (err instanceof ApiError) {
+      printError(`Could not fetch the skill (HTTP ${err.status})`, err.body);
+      process.exit(exitCodeFor(err.status));
+    }
+    printError(err instanceof Error ? err.message : "Could not fetch the skill");
+    process.exit(1);
+  }
+  const dir = mkdtempSync(join2(tmpdir(), "lphub-skill-"));
+  writeFileSync2(join2(dir, "SKILL.md"), content, "utf-8");
+  const args = ["skills", "add", dir, ...passthrough];
+  console.log(`Installing the lphub skill via skills.sh:
+  npx ${args.join(" ")}
+`);
+  const res = spawnSync("npx", args, { stdio: "inherit" });
+  if (res.error) {
+    printError(
+      "Could not run `npx skills add` (is Node/npx available?)",
+      res.error.message
+    );
+    process.exit(1);
+  }
+  process.exit(res.status ?? 0);
+}
+
+// src/dynamic.ts
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
+import { homedir as homedir2 } from "os";
+
+// src/context.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join3, dirname as dirname2 } from "path";
+var cachedContext = void 0;
+function loadLocalContext() {
+  if (cachedContext !== void 0) return cachedContext;
+  let dir = process.cwd();
+  while (true) {
+    const candidate = join3(dir, ".lphub.json");
+    if (existsSync2(candidate)) {
+      try {
+        cachedContext = JSON.parse(readFileSync2(candidate, "utf-8"));
+        return cachedContext;
+      } catch {
+        break;
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  cachedContext = null;
+  return null;
+}
+function getLocalContext() {
+  return cachedContext ?? null;
+}
+function getContextPath() {
+  return join3(process.cwd(), ".lphub.json");
+}
+
+// src/interactive.ts
+import * as readline2 from "readline";
+import { readFileSync as readFileSync3 } from "fs";
+import { resolve } from "path";
+function readBodyFromFile(path) {
+  if (path === "-") {
+    return readFileSync3(0, "utf-8");
+  }
+  return readFileSync3(resolve(process.cwd(), path), "utf-8");
+}
+async function confirm(question) {
+  if (!process.stdin.isTTY) return true;
+  const rl = readline2.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  try {
+    const answer = await new Promise(
+      (res) => rl.question(`${question} `, (a) => res(a))
+    );
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+// src/dynamic.ts
+var CONTEXT_FILLABLE = {
+  "project-id": "projectId"
+};
+function loadManifestSync() {
+  const manifestPath = join4(homedir2(), ".lphub", "manifest.json");
+  if (!existsSync3(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync4(manifestPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function optKey(flagName) {
+  return flagName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function wireKey(name) {
+  return name.replace(/-/g, "_");
+}
+function registerDynamicCommands(program2, jsonMode2) {
+  const manifest = loadManifestSync();
+  if (!manifest) return;
+  for (const cmd of manifest.commands) {
+    const parentCmd = program2.command(cmd.name).description(cmd.description ?? "");
+    for (const sub of cmd.subcommands) {
+      let subCmd = parentCmd.command(sub.name).description(sub.description ?? "");
+      for (const param of sub.pathParams ?? []) {
+        subCmd = subCmd.argument(`<${param.name}>`);
+      }
+      const method = sub.method.toUpperCase();
+      for (const opt of sub.options ?? []) {
+        let flag;
+        if (opt.type === "boolean") {
+          flag = `--${opt.name}`;
+        } else if (opt.type === "array") {
+          flag = `--${opt.name} <values...>`;
+        } else {
+          flag = `--${opt.name} <value>`;
+        }
+        const description = opt.enum && opt.enum.length > 0 ? `Choices: ${opt.enum.join(", ")}` : "";
+        if (opt.required && !(opt.name in CONTEXT_FILLABLE)) {
+          subCmd = subCmd.requiredOption(flag, description);
+        } else {
+          subCmd = subCmd.option(flag, description);
+        }
+        if (opt.type === "string") {
+          subCmd = subCmd.option(
+            `--${opt.name}-file <path>`,
+            `Read --${opt.name} from a file (use - for STDIN)`
+          );
+        }
+      }
+      subCmd = subCmd.option("--json", "Output raw JSON instead of a table").option(
+        "--fields <list>",
+        "Comma-separated dot-paths to project (e.g. id,title,project.name)"
+      );
+      if (method === "DELETE") {
+        subCmd = subCmd.option("-y, --yes", "Skip the confirmation prompt");
+      }
+      const capturedSub = sub;
+      const capturedResource = cmd.name;
+      subCmd.action(async (...args) => {
+        const profileOverride = program2.opts()["profile"];
+        const profile = getActiveProfile(profileOverride);
+        if (!profile) {
+          printError("No config found. Run `lphub auth login` to configure.");
+          process.exit(1);
+        }
+        const pathParams = capturedSub.pathParams ?? [];
+        const positionalArgs = args.slice(0, pathParams.length);
+        const opts = args[pathParams.length] ?? {};
+        let resolvedPath = capturedSub.path;
+        for (let i = 0; i < pathParams.length; i++) {
+          resolvedPath = resolvedPath.replace(
+            `{${pathParams[i].name}}`,
+            positionalArgs[i] ?? ""
+          );
+        }
+        const useJson = !!opts["json"] || jsonMode2();
+        const fieldsRaw = opts["fields"];
+        const fields = fieldsRaw ? fieldsRaw.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+        const skipConfirm = !!opts["yes"];
+        const manifestOpts = capturedSub.options ?? [];
+        const pathParamNames = new Set(pathParams.map((p) => p.name));
+        const payload = {};
+        for (const mo of manifestOpts) {
+          if (pathParamNames.has(mo.name)) continue;
+          const key = optKey(mo.name);
+          if (mo.type === "string") {
+            const fileKey = optKey(`${mo.name}-file`);
+            const direct = opts[key];
+            const fromFile = opts[fileKey];
+            if (direct !== void 0 && fromFile !== void 0) {
+              printError(`--${mo.name} and --${mo.name}-file are mutually exclusive.`);
+              process.exit(1);
+            }
+            if (fromFile !== void 0) {
+              try {
+                payload[mo.name] = readBodyFromFile(fromFile);
+              } catch (err) {
+                printError(
+                  `Could not read --${mo.name}-file`,
+                  err instanceof Error ? err.message : err
+                );
+                process.exit(1);
+              }
+            } else if (direct !== void 0) {
+              payload[mo.name] = direct;
+            }
+          } else if (mo.type === "boolean") {
+            if (opts[key] !== void 0) payload[mo.name] = !!opts[key];
+          } else {
+            const v = opts[key];
+            if (v !== void 0) payload[mo.name] = v;
+          }
+        }
+        const ctx = getLocalContext();
+        for (const [optName, ctxField] of Object.entries(CONTEXT_FILLABLE)) {
+          const mo = manifestOpts.find((o) => o.name === optName);
+          if (!mo) continue;
+          const key = optKey(optName);
+          if (payload[optName] === void 0 && opts[key] === void 0) {
+            const ctxValue = ctx?.[ctxField];
+            if (ctxValue !== void 0) {
+              payload[optName] = String(ctxValue);
+            } else if (mo.required) {
+              printError(
+                `--${optName} is required (or run \`lphub init\` to set a default project)`
+              );
+              process.exit(1);
+            }
+          }
+        }
+        if (method === "DELETE" && !skipConfirm) {
+          const id = positionalArgs[positionalArgs.length - 1] ?? "";
+          const ok = await confirm(`Delete ${capturedResource} ${id}? (y/N)`);
+          if (!ok) {
+            process.stderr.write("Aborted.\n");
+            process.exit(1);
+          }
+        }
+        try {
+          let result;
+          if (method === "GET") {
+            const query = {};
+            for (const [k, v] of Object.entries(payload)) {
+              if (v === void 0 || v === null) continue;
+              query[wireKey(k)] = Array.isArray(v) ? v.join(",") : String(v);
+            }
+            result = await apiRequest(
+              profile,
+              method,
+              resolvedPath,
+              void 0,
+              Object.keys(query).length > 0 ? query : void 0
+            );
+          } else if (method === "DELETE") {
+            result = await apiRequest(profile, method, resolvedPath);
+          } else {
+            const body = Object.fromEntries(
+              Object.entries(payload).map(([k, v]) => [wireKey(k), v])
+            );
+            result = await apiRequest(
+              profile,
+              method,
+              resolvedPath,
+              Object.keys(body).length > 0 ? body : void 0
+            );
+          }
+          printResult(result, { json: useJson, fields });
+        } catch (err) {
+          if (err instanceof ApiError) {
+            if (err.status === 422 && printValidationError(err.body)) {
+              process.exit(1);
+            }
+            printError(`${err.status} ${method} ${resolvedPath}`, err.body);
+            process.exit(exitCodeFor(err.status));
+          }
+          printError(err instanceof Error ? err.message : "Request failed");
+          process.exit(1);
+        }
+      });
+    }
+  }
+}
+
+// src/commands/init.ts
+import * as readline3 from "readline";
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3, appendFileSync } from "fs";
+import { join as join5 } from "path";
+function prompt2(rl, question) {
+  return new Promise((resolve2) => {
+    rl.question(question, (answer) => resolve2(answer));
+  });
+}
+async function initCommand() {
+  const config = loadConfig();
+  if (!config || Object.keys(config.profiles).length === 0) {
+    printError("No profiles configured. Run `lphub auth login` first.");
+    process.exit(1);
+  }
+  const rl = readline3.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const profileNames = Object.keys(config.profiles);
+    console.log("\nAvailable profiles:");
+    for (const name of profileNames) {
+      const marker = name === config.currentProfile ? "* " : "  ";
+      console.log(`${marker}${name}`);
+    }
+    const profileAnswer = (await prompt2(rl, `
+Profile [${config.currentProfile}]: `)).trim();
+    const chosenProfile = profileAnswer || config.currentProfile;
+    if (!config.profiles[chosenProfile]) {
+      printError(`Profile "${chosenProfile}" not found.`);
+      rl.close();
+      process.exit(1);
+    }
+    const profile = getActiveProfile(chosenProfile);
+    if (!profile) {
+      printError("Could not load profile. Run `lphub auth login`.");
+      rl.close();
+      process.exit(1);
+    }
+    let projects;
+    try {
+      const res = await apiRequest(profile, "GET", "/projects");
+      projects = Array.isArray(res) ? res : res.data ?? [];
+    } catch (err) {
+      rl.close();
+      if (err instanceof ApiError) {
+        printError(`Failed to fetch projects (HTTP ${err.status})`, err.body);
+        process.exit(1);
+      }
+      if (err instanceof NetworkError) {
+        printError(err.message);
+        process.exit(1);
+      }
+      printError(err instanceof Error ? err.message : "Request failed");
+      process.exit(1);
+    }
+    if (projects.length === 0) {
+      printError("No projects found for this profile.");
+      rl.close();
+      process.exit(1);
+    }
+    console.log("\nAvailable projects:");
+    for (let i = 0; i < projects.length; i++) {
+      console.log(`  ${i + 1}.  ${projects[i].id}	${projects[i].name}`);
+    }
+    const projectAnswer = (await prompt2(rl, "\nEnter project ID (or list number): ")).trim();
+    let chosenProjectId;
+    const asNumber = Number(projectAnswer);
+    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= projects.length) {
+      const byId = projects.find((p) => p.id === asNumber);
+      if (byId) {
+        chosenProjectId = byId.id;
+      } else {
+        chosenProjectId = projects[asNumber - 1].id;
+      }
+    } else if (!Number.isNaN(asNumber) && Number.isInteger(asNumber)) {
+      chosenProjectId = asNumber;
+    }
+    if (chosenProjectId === void 0 || !projects.find((p) => p.id === chosenProjectId)) {
+      printError(`"${projectAnswer}" is not a valid project ID or list number.`);
+      rl.close();
+      process.exit(1);
+    }
+    const chosenProject = projects.find((p) => p.id === chosenProjectId);
+    const contextPath = getContextPath();
+    const contextData = { profile: chosenProfile, projectId: chosenProjectId };
+    writeFileSync3(contextPath, JSON.stringify(contextData, null, 2) + "\n", "utf-8");
+    const gitignorePath = join5(process.cwd(), ".gitignore");
+    if (existsSync4(gitignorePath)) {
+      const gitignoreContent = readFileSync5(gitignorePath, "utf-8");
+      if (!gitignoreContent.split("\n").some((l) => l.trim() === ".lphub.json")) {
+        const addToGitignore = (await prompt2(rl, "Add .lphub.json to .gitignore? (Y/n): ")).trim().toLowerCase();
+        if (addToGitignore !== "n" && addToGitignore !== "no") {
+          const separator = gitignoreContent.endsWith("\n") ? "" : "\n";
+          appendFileSync(gitignorePath, `${separator}.lphub.json
+`, "utf-8");
+          console.log("Added .lphub.json to .gitignore.");
+        }
+      }
+    } else {
+      console.log(
+        "\nNote: .lphub.json is personal and should not be committed. Add it to your .gitignore."
+      );
+    }
+    rl.close();
+    console.log(`
+Initialized: profile "${chosenProfile}", project "${chosenProject.name}" (id: ${chosenProjectId})`);
+    console.log(`Commands in this directory now auto-scope to project ${chosenProjectId}.`);
+  } catch (err) {
+    rl.close();
+    printError("Init failed", err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
+// src/commands/docs.ts
+async function docsCommand(profileOverride, topic) {
+  const profile = getActiveProfile(profileOverride);
+  if (!profile) {
+    printError("No config found. Run `lphub auth login` to configure.");
+    process.exit(1);
+  }
+  try {
+    if (!topic) {
+      const res = await apiRequest(profile, "GET", "/cli-docs");
+      const topics = res.topics ?? [];
+      if (topics.length === 0) {
+        console.log("No docs topics available.");
+        return;
+      }
+      const width = Math.max(...topics.map((t) => t.name.length));
+      console.log("Available docs topics (use `lphub docs <topic>`):\n");
+      for (const t of topics) {
+        console.log(`  ${t.name.padEnd(width)}  ${t.title}`);
+      }
+    } else {
+      const res = await apiRequest(
+        profile,
+        "GET",
+        `/cli-docs/${encodeURIComponent(topic)}`
+      );
+      process.stdout.write((res.content ?? "") + "\n");
+    }
+  } catch (err) {
+    if (err instanceof ApiError) {
+      if (err.status === 404) {
+        printError(
+          `Unknown docs topic "${topic}". Run \`lphub docs\` to list topics.`
+        );
+        process.exit(1);
+      }
+      printError(`Docs failed (HTTP ${err.status})`, err.body);
+      process.exit(exitCodeFor(err.status));
+    }
+    printError(err instanceof Error ? err.message : "Docs failed");
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("lphub").description("LogicPanel Hub CLI").option("--profile <name>", "Override active profile").option("--base-url <url>", "Override the API base URL (or set LPHUB_BASE_URL)").option("--json", "Compact JSON output");
+program.hook("preAction", () => {
+  setBaseUrlOverride(program.opts()["baseUrl"]);
+  const ctx = loadLocalContext();
+  setContextProfile(ctx?.profile);
+});
+var globalOpts = () => program.opts();
+var jsonMode = () => !!globalOpts()["json"];
+var parseFields = (raw) => raw ? raw.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+registerDynamicCommands(program, jsonMode);
+var authCmd = program.command("auth").description("Authenticate and manage profiles").action(async () => {
+  await authLogin();
+});
+authCmd.command("login").description("Interactively configure a profile (base URL + PAT token)").action(async () => {
+  await authLogin();
+});
+authCmd.command("status").description("Show the active profile and whoami").action(async () => {
+  await authStatus(globalOpts()["profile"]);
+});
+authCmd.command("list").description("List configured profiles").action(() => {
+  authList();
+});
+authCmd.command("switch <profile>").description("Set the current profile").action((name) => {
+  authSwitch(name);
+});
+authCmd.command("logout [profile]").description("Remove a profile (default: current)").action((name) => {
+  authLogout(name);
+});
+program.command("sync").description("Refresh the local command manifest from the API").action(async () => {
+  await syncCommand(globalOpts()["profile"]);
+});
+program.command("me").description("Print the authenticated user").option("--json", "Output raw JSON instead of a table").option("--fields <list>", "Comma-separated dot-paths to project").action(async (opts) => {
+  await meCommand(globalOpts()["profile"], {
+    json: !!opts.json || jsonMode(),
+    fields: parseFields(opts.fields)
+  });
+});
+var agentCmd = program.command("agent").description("Agent integration utilities");
+agentCmd.command("setup").description("Fetch the agent skill from the API and install it via skills.sh").allowUnknownOption(true).helpOption(false).action(async () => {
+  const i = process.argv.lastIndexOf("setup");
+  const passthrough = i >= 0 ? process.argv.slice(i + 1) : [];
+  await agentSetupCommand(
+    passthrough,
+    globalOpts()["profile"]
+  );
+});
+program.command("init").description("Pin a profile and project to this directory (.lphub.json)").action(async () => {
+  await initCommand();
+});
+program.command("docs [topic]").description("Show LogicPanel Hub guides (list topics, or print one in full)").action(async (topic) => {
+  await docsCommand(globalOpts()["profile"], topic);
+});
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@logicpanel/lphub",
+  "version": "0.1.0",
+  "description": "Thin CLI client for the LogicPanel Hub API — manifest-driven, gh-style.",
+  "keywords": [
+    "logicpanel",
+    "lphub",
+    "cli",
+    "tickets",
+    "issues",
+    "api-client"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "lphub": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/logicpanel/logicpanel-hub-client.git",
+    "directory": "packages/lphub"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "tsup"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "@types/node": "^22.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}