@pebblehouse/odin-cli 0.14.1 → 0.16.0

package/dist/index.js

@@ -208,7 +208,7 @@ async function apiRequest(path, options = {}) {
   const { method = "GET", body, params } = options;
   const token = await getValidToken();
   let url = `${BASE_URL}/api${path}`;
-  if (params) {
+  if (params && Object.keys(params).length > 0) {
     const searchParams = new URLSearchParams(params);
     url += `?${searchParams.toString()}`;
   }
@@ -262,8 +262,13 @@ pebblesCmd.command("update <slug>").description("Update a pebble").option("--slu
 import { Command as Command2 } from "commander";
 import { readFileSync as readFileSync3 } from "fs";
 var docsCmd = new Command2("docs").description("Manage documents");
-docsCmd.command("list <slug>").description("List documents for a pebble").action(async (slug) => {
-  const res = await apiRequest(`/pebbles/${slug}/documents`);
+docsCmd.command("list <slug>").description("List documents for a pebble").option(
+  "--doc-type <type>",
+  "Filter by document type (architecture, product, api, readme, spec, research, marketing, other, reference, org_chart, design, schema)"
+).action(async (slug, opts) => {
+  const params = {};
+  if (opts.docType) params.doc_type = opts.docType;
+  const res = await apiRequest(`/pebbles/${slug}/documents`, { params });
   process.stdout.write(JSON.stringify(res) + "\n");
   if (res.error) process.exit(1);
 });
@@ -307,11 +312,119 @@ docsCmd.command("update <slug> <type>").description("Update document content").r
 
 // src/commands/decisions.ts
 import { Command as Command3 } from "commander";
-var decisionsCmd = new Command3("decisions").description("Manage decisions");
-decisionsCmd.command("list <slug>").description("List decisions for a pebble").action(async (slug) => {
-  const res = await apiRequest(`/pebbles/${slug}/decisions`);
+
+// src/list-flags.ts
+var LIST_DEFAULT_LIMIT = 50;
+var LIST_MAX_LIMIT = 100;
+function withListFlags(cmd) {
+  return cmd.option("--limit <n>", `Rows per request (max ${LIST_MAX_LIMIT})`).option("--offset <n>", "Rows to skip").option("--page <n>", "1-based page number; shorthand for --offset (page - 1) * limit");
+}
+function parseInteger(raw) {
+  if (raw === void 0 || raw === "") return null;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return null;
+  return Math.trunc(n);
+}
+function resolveListParams(opts) {
+  const notices = [];
+  const params = {};
+  if (opts.page !== void 0 && opts.offset !== void 0) {
+    return {
+      params: {},
+      limit: LIST_DEFAULT_LIMIT,
+      offset: 0,
+      notices: [],
+      fatal: "--page and --offset are mutually exclusive \u2014 use one"
+    };
+  }
+  let effectiveLimit = LIST_DEFAULT_LIMIT;
+  if (opts.limit !== void 0) {
+    const raw = parseInteger(opts.limit);
+    if (raw === null) {
+      notices.push(`--limit "${opts.limit}" is not a number \u2014 ignoring`);
+    } else if (raw > LIST_MAX_LIMIT) {
+      notices.push(`limit ${raw} exceeds the server maximum of ${LIST_MAX_LIMIT} \u2014 using ${LIST_MAX_LIMIT}`);
+      effectiveLimit = LIST_MAX_LIMIT;
+      params.limit = String(LIST_MAX_LIMIT);
+    } else if (raw < 1) {
+      notices.push(`--limit must be 1 or greater \u2014 using 1`);
+      effectiveLimit = 1;
+      params.limit = "1";
+    } else {
+      effectiveLimit = raw;
+      params.limit = String(raw);
+    }
+  }
+  let effectiveOffset = 0;
+  if (opts.offset !== void 0) {
+    const raw = parseInteger(opts.offset);
+    if (raw === null) {
+      notices.push(`--offset "${opts.offset}" is not a number \u2014 ignoring`);
+    } else if (raw < 0) {
+      notices.push(`--offset must be 0 or greater \u2014 using 0`);
+      params.offset = "0";
+    } else {
+      effectiveOffset = raw;
+      params.offset = String(raw);
+    }
+  } else if (opts.page !== void 0) {
+    const raw = parseInteger(opts.page);
+    if (raw === null) {
+      notices.push(`--page "${opts.page}" is not a number \u2014 ignoring`);
+    } else {
+      const page = raw < 1 ? 1 : raw;
+      if (raw < 1) notices.push(`--page must be 1 or greater \u2014 using page 1`);
+      effectiveOffset = (page - 1) * effectiveLimit;
+      params.offset = String(effectiveOffset);
+    }
+  }
+  return { params, limit: effectiveLimit, offset: effectiveOffset, notices, fatal: null };
+}
+function renderListFooter(noun, rowCount, total, offset, limit) {
+  if (total === void 0) {
+    return `\u2014 showing ${rowCount} ${noun} (total unavailable)`;
+  }
+  if (rowCount === 0) {
+    return offset > 0 ? `\u2014 no ${noun} in this window (${total} total) \xB7 try --offset 0` : `\u2014 no ${noun}`;
+  }
+  const first = offset + 1;
+  const last = offset + rowCount;
+  if (offset === 0 && rowCount >= total) {
+    return `\u2014 showing all ${rowCount} ${noun}`;
+  }
+  const nextOffset = offset + limit;
+  const more = last < total ? ` \xB7 more: --offset ${nextOffset}` : "";
+  return `\u2014 showing ${rowCount} of ${total} ${noun} (rows ${first}\u2013${last})${more}`;
+}
+function emitListResult(res, noun, resolved) {
   process.stdout.write(JSON.stringify(res) + "\n");
+  for (const notice of resolved.notices) {
+    process.stderr.write(notice + "\n");
+  }
+  const rowCount = Array.isArray(res.data) ? res.data.length : 0;
+  const footer = renderListFooter(noun, rowCount, res.total, resolved.offset, resolved.limit);
+  if (footer) process.stderr.write(footer + "\n");
   if (res.error) process.exit(1);
+}
+
+// src/commands/decisions.ts
+var decisionsCmd = new Command3("decisions").description("Manage decisions");
+withListFlags(
+  decisionsCmd.command("list <slug>").description("List decisions for a pebble").option(
+    "--status <status>",
+    "Filter by status (active, superseded, all). Defaults to active on the server."
+  )
+).action(async (slug, opts) => {
+  const resolved = resolveListParams(opts);
+  if (resolved.fatal) {
+    process.stderr.write(resolved.fatal + "\n");
+    process.exit(1);
+    return;
+  }
+  const params = { ...resolved.params };
+  if (opts.status) params.status = opts.status;
+  const res = await apiRequest(`/pebbles/${slug}/decisions`, { params });
+  emitListResult(res, "decisions", resolved);
 });
 decisionsCmd.command("get <slug> <id>").description("Get a decision by ID").action(async (slug, id) => {
   const res = await apiRequest(`/pebbles/${slug}/decisions/${id}`);
@@ -379,7 +492,7 @@ decisionsCmd.command("log <slug> <title>").description("Log a decision").option(
     const threeDaysAgo = /* @__PURE__ */ new Date();
     threeDaysAgo.setDate(threeDaysAgo.getDate() - 3);
     const recentRes = await apiRequest(`/pebbles/${slug}/decisions`, {
-      params: { limit: "100" }
+      params: { limit: String(LIST_MAX_LIMIT) }
     });
     if (recentRes.data) {
       const recentActive = recentRes.data.filter(
@@ -444,8 +557,12 @@ var searchCmd = new Command5("search").description("Full-text search across Odin
 import { Command as Command6 } from "commander";
 import { readFileSync as readFileSync4 } from "fs";
 var plansCmd = new Command6("plans").description("Manage plans");
-plansCmd.command("list <slug>").description("List plans for a pebble").action(async (slug) => {
-  const res = await apiRequest(`/pebbles/${slug}/plans`);
+plansCmd.command("list <slug>").description("List plans for a pebble").option("--status <status>", "Filter by status (active, done, archived)").option("--bet <id>", "Filter to plans linked to this bet").option("--task <id>", "Filter to plans linked to this task").action(async (slug, opts) => {
+  const params = {};
+  if (opts.status) params.status = opts.status;
+  if (opts.bet) params.bet_id = opts.bet;
+  if (opts.task) params.task_id = opts.task;
+  const res = await apiRequest(`/pebbles/${slug}/plans`, { params });
   process.stdout.write(JSON.stringify(res) + "\n");
   if (res.error) process.exit(1);
 });
@@ -558,12 +675,19 @@ plansCmd.command("remove-phase-link <slug> <planId> <phaseId> <linkId>").descrip
 import { Command as Command7 } from "commander";
 import { readFileSync as readFileSync5 } from "fs";
 var artifactsCmd = new Command7("artifacts").description("Manage artifacts");
-artifactsCmd.command("list <slug>").description("List artifacts for a pebble").option("--source <source>", "Filter by source (claude-code, superpowers, etc.)").action(async (slug, opts) => {
-  const params = {};
+withListFlags(
+  artifactsCmd.command("list <slug>").description("List artifacts for a pebble").option("--source <source>", "Filter by source (claude-code, superpowers, etc.)")
+).action(async (slug, opts) => {
+  const resolved = resolveListParams(opts);
+  if (resolved.fatal) {
+    process.stderr.write(resolved.fatal + "\n");
+    process.exit(1);
+    return;
+  }
+  const params = { ...resolved.params };
   if (opts.source) params.source = opts.source;
   const res = await apiRequest(`/pebbles/${slug}/artifacts`, { params });
-  process.stdout.write(JSON.stringify(res) + "\n");
-  if (res.error) process.exit(1);
+  emitListResult(res, "artifacts", resolved);
 });
 artifactsCmd.command("get <slug> <id>").description("Get an artifact by ID").action(async (slug, id) => {
   const res = await apiRequest(`/pebbles/${slug}/artifacts/${id}`);
@@ -929,12 +1053,19 @@ depsCmd.command("remove <slug> <bet-id>").description("Remove a blocked-by depen
 
 // src/commands/bets.ts
 var betsCmd = new Command14("bets").description("Manage bets");
-betsCmd.command("list <slug>").description("List bets for a pebble").option("--status <status>", "Filter by status (pitch, shaped, betting, active, blocked, building, done, archived)").action(async (slug, opts) => {
-  const params = {};
+withListFlags(
+  betsCmd.command("list <slug>").description("List bets for a pebble").option("--status <status>", "Filter by status (pitch, shaped, betting, active, blocked, building, done, archived)")
+).action(async (slug, opts) => {
+  const resolved = resolveListParams(opts);
+  if (resolved.fatal) {
+    process.stderr.write(resolved.fatal + "\n");
+    process.exit(1);
+    return;
+  }
+  const params = { ...resolved.params };
   if (opts.status) params.status = opts.status;
   const res = await apiRequest(`/pebbles/${slug}/bets`, { params });
-  process.stdout.write(JSON.stringify(res) + "\n");
-  if (res.error) process.exit(1);
+  emitListResult(res, "bets", resolved);
 });
 betsCmd.command("get <slug> <id>").description("Get a bet by ID").action(async (slug, id) => {
   const res = await apiRequest(`/pebbles/${slug}/bets/${id}`);
@@ -1006,13 +1137,20 @@ betCommentsCmd.command("create <slug> <betId> [body]").description("Post a comme
 // src/commands/tasks.ts
 import { Command as Command16 } from "commander";
 var tasksCmd = new Command16("tasks").description("Manage tasks");
-tasksCmd.command("list <slug>").description("List tasks for a pebble").option("--status <status>", "Filter by status").option("--bet <bet-id>", "Filter by bet ID").action(async (slug, opts) => {
-  const params = {};
+withListFlags(
+  tasksCmd.command("list <slug>").description("List tasks for a pebble").option("--status <status>", "Filter by status").option("--bet <bet-id>", "Filter by bet ID")
+).action(async (slug, opts) => {
+  const resolved = resolveListParams(opts);
+  if (resolved.fatal) {
+    process.stderr.write(resolved.fatal + "\n");
+    process.exit(1);
+    return;
+  }
+  const params = { ...resolved.params };
   if (opts.status) params.status = opts.status;
   if (opts.bet) params.bet_id = opts.bet;
   const res = await apiRequest(`/pebbles/${slug}/tasks`, { params });
-  process.stdout.write(JSON.stringify(res) + "\n");
-  if (res.error) process.exit(1);
+  emitListResult(res, "tasks", resolved);
 });
 tasksCmd.command("get <slug> <id>").description("Get a task by ID").action(async (slug, id) => {
   const res = await apiRequest(`/pebbles/${slug}/tasks/${id}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pebblehouse/odin-cli",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "type": "module",
   "description": "CLI for Odin — the knowledge backbone for Pebble House",
   "bin": {