@ghl-ai/aw 0.1.85 → 0.1.88

package/cli.mjs

@@ -183,8 +183,9 @@ function printHelp() {
     cmd('aw integrations add <key>', 'Install a specific tool (e.g. codex, caveman, context-mode)'),
     cmd('aw integrations remove <key>', 'Remove a tool'),
     cmd('aw integrations bundle <name>', 'Install a preset bundle'),
-    cmd('aw clickup-sync <items.json> --list <id>', 'Sync JSON items into a ClickUp list (create new, comment recurring; input-validated, fail-closed)'),
+    cmd('aw clickup-sync <items.json> --list <id>', 'Sync JSON items into a ClickUp list via the ghl-ai MCP proxy using your GitHub PAT (no CLICKUP_API_TOKEN needed; create new, comment recurring; optional per-item tags + priority 1-4; input-validated, fail-closed)'),
     cmd('aw clickup-sync <items.json> --list <id> --dry-run', 'Preview the create/comment plan without any writes'),
+    cmd('aw clickup-sync <items.json> --list <id> --direct', 'Bypass the proxy and call ClickUp directly with a local CLICKUP_API_TOKEN'),
     cmd('aw drop <path>', 'Stop syncing or delete local content'),
     cmd('aw nuke', 'Remove entire .aw_registry/ & start fresh'),
     cmd('aw daemon install', 'Auto-pull on a schedule (macOS launchd / Linux cron)'),

package/clickup-sync.mjs

@@ -25,7 +25,14 @@ export const LEGACY_NAME_KEY_RE = /key:(\S+)\s*$/;
 export const TITLE_MAX = 255;
 export const DESC_MAX = 8000;
 
-const ALLOWED_FIELDS = new Set(['key', 'title', 'description']);
+// Tier 1 enrichment bounds. Tags are ClickUp tag names (attached at create);
+// priority is ClickUp's fixed 1..4 scale (1=Urgent, 2=High, 3=Normal, 4=Low).
+export const TAG_MAX = 100;
+export const TAGS_MAX = 20;
+export const PRIORITY_MIN = 1;
+export const PRIORITY_MAX = 4;
+
+const ALLOWED_FIELDS = new Set(['key', 'title', 'description', 'tags', 'priority']);
 
 /**
  * Validate untrusted, already-parsed JSON into a normalized item list.
@@ -78,7 +85,43 @@ export function parseAndValidateItems(raw) {
       throw new Error(`Invalid item ${index}: "description" exceeds ${DESC_MAX} characters.`);
     }
 
-    return { key, title, description };
+    const normalized = { key, title, description };
+
+    // Optional tags: array of non-empty tag-name strings, deduped, bounded.
+    if (item.tags !== undefined) {
+      if (!Array.isArray(item.tags)) {
+        throw new Error(`Invalid item ${index}: "tags" must be an array of strings when present.`);
+      }
+      const tags = [];
+      const seenTags = new Set();
+      for (const tag of item.tags) {
+        if (typeof tag !== 'string' || tag.trim().length === 0) {
+          throw new Error(`Invalid item ${index}: every "tag" must be a non-empty string.`);
+        }
+        if (tag.length > TAG_MAX) {
+          throw new Error(`Invalid item ${index}: a "tag" exceeds ${TAG_MAX} characters.`);
+        }
+        if (seenTags.has(tag)) continue;
+        seenTags.add(tag);
+        tags.push(tag);
+      }
+      if (tags.length > TAGS_MAX) {
+        throw new Error(`Invalid item ${index}: "tags" exceeds ${TAGS_MAX} entries.`);
+      }
+      normalized.tags = tags;
+    }
+
+    // Optional priority: integer on ClickUp's 1..4 scale.
+    if (item.priority !== undefined) {
+      const { priority } = item;
+      if (typeof priority !== 'number' || !Number.isInteger(priority)
+        || priority < PRIORITY_MIN || priority > PRIORITY_MAX) {
+        throw new Error(`Invalid item ${index}: "priority" must be an integer ${PRIORITY_MIN}..${PRIORITY_MAX} (1=Urgent, 2=High, 3=Normal, 4=Low).`);
+      }
+      normalized.priority = priority;
+    }
+
+    return normalized;
   });
 
   return items;

package/commands/clickup-sync.mjs

@@ -11,14 +11,14 @@
 import { readFileSync } from 'node:fs';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { createClickUpClient } from '../integrations/clickup.mjs';
+import { resolveClickUpClient } from '../integrations/clickup.mjs';
 import { parseAndValidateItems, embedSentinel, computeSyncPlan } from '../clickup-sync.mjs';
 
 const RECURRING_COMMENT = 'Recurred via `aw clickup-sync` — item seen again in the source list.';
 
 export async function clickupSyncCommand(args, deps = {}) {
   const readFile = deps.readFile ?? ((path) => readFileSync(path, 'utf8'));
-  const makeClient = deps.createClient ?? (() => createClickUpClient());
+  const makeClient = deps.createClient ?? (() => resolveClickUpClient(args));
 
   fmt.configureInteractionMode(args);
   fmt.intro('aw clickup-sync');
@@ -91,10 +91,15 @@ export async function clickupSyncCommand(args, deps = {}) {
   let created = 0;
   for (const item of toCreate) {
     try {
-      await client.createTask(listId, {
+      const payload = {
         name: item.title,
         description: embedSentinel(item.description, item.key),
-      });
+      };
+      // Enrichment fields are create-time only and included solely when present,
+      // so items without them behave exactly as before (no empty tags / undefined priority).
+      if (item.tags !== undefined) payload.tags = item.tags;
+      if (item.priority !== undefined) payload.priority = item.priority;
+      await client.createTask(listId, payload);
       created++;
     } catch (err) {
       fmt.cancel(`Failed creating task for "${item.key}" after ${created} created (re-run to resume): ${errMessage(err)}`);

package/commands/push.mjs

@@ -550,6 +550,20 @@ async function getGitStatus(repoDir) {
   return stdout;
 }
 
+/**
+ * Hard-restore a reused docs cache clone to a clean tree. The clone is a
+ * disposable publish staging area (re-checked-out from origin and re-populated
+ * on every publish), so discarding local working-tree changes is safe and
+ * prevents a single aborted publish from permanently wedging the cache.
+ * Best-effort: swallow git errors so recovery never itself blocks a publish.
+ */
+async function recoverDirtyDocsCache(cloneDir) {
+  await execFile('git', ['reset', '--hard'], { cwd: cloneDir, encoding: 'utf8' })
+    .catch((e) => fmt.logWarn(`AW docs cache reset failed: ${(e?.stderr || e?.message || '').toString().trim()}`));
+  await execFile('git', ['clean', '-fd'], { cwd: cloneDir, encoding: 'utf8' })
+    .catch((e) => fmt.logWarn(`AW docs cache clean failed: ${(e?.stderr || e?.message || '').toString().trim()}`));
+}
+
 function parseGitHubRepo(remoteUrl) {
   const match = remoteUrl.trim().match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/);
   if (!match) return null;
@@ -654,8 +668,21 @@ async function ensureAwDocsRepoClone(home, publishConfig, sparseIncludePaths = [
       status = await getGitStatus(cloneDir);
     }
     if (status.trim()) {
+      // The cached docs clone is a disposable staging area — below we re-checkout
+      // the publish branch from origin and write fresh content, so any remaining
+      // local dirt is safe to discard. This is most often leftover staged/modified
+      // files from a PRIOR aborted publish; without recovery that dirt would
+      // permanently wedge every subsequent publish (isOnlyManagedAwCacheDirtiness
+      // only self-heals pure `.aw` dirt). Recover instead of hard-failing.
+      fmt.logWarn(`AW docs cache had leftover changes; recovering ${cloneDir}`);
+      await recoverDirtyDocsCache(cloneDir);
+      status = await getGitStatus(cloneDir);
+    }
+    if (status.trim()) {
+      // Still dirty after a hard reset+clean → genuinely unexpected (permissions,
+      // index corruption). Surface it rather than push from an unknown state.
       throw new Error([
-        `AW docs repo worktree is dirty: ${cloneDir}`,
+        `AW docs repo worktree is dirty and could not be auto-recovered: ${cloneDir}`,
         status.trim(),
         'Clean the cached docs repo or set AW_DOCS_WORKTREE to a clean clone before publishing.',
       ].join('\n'));

package/integrations/clickup-proxy.mjs

@@ -0,0 +1,63 @@
+// integrations/clickup-proxy.mjs — ClickUp client that proxies through the
+// deployed ghl-ai MCP instead of calling api.clickup.com directly.
+//
+// Exposes the same interface as integrations/clickup.mjs
+// ({ listAllTasks, createTask, addComment }) so commands/clickup-sync.mjs can
+// use either client behind one seam. Auth is the caller's GitHub PAT (Bearer);
+// the shared ClickUp token lives server-side, so no CLICKUP_API_TOKEN is needed
+// locally.
+//
+// Retry discipline mirrors the direct client: get-tasks (a read) is retryable;
+// create-task and add-comment (writes) are never auto-retried, so a transport
+// failure after a server-side success cannot duplicate a task or comment. The
+// sync is cross-run resumable via the description sentinel.
+
+import { createMcpRpcClient } from './mcp-rpc.mjs';
+
+// Matches integrations/clickup.mjs MAX_PAGES — a hard cap so a list that never
+// reports last_page aborts instead of paging forever.
+export const MAX_PAGES = 200;
+
+/**
+ * @param {{ mcpUrl: string, token: string, rpc?: { callTool: Function } }} opts
+ */
+export function createClickUpProxyClient(opts = {}) {
+  const { mcpUrl, token } = opts;
+  const rpc = opts.rpc ?? createMcpRpcClient({ url: mcpUrl, token });
+
+  // Page through every task in a list via the proxy tool. include_closed so
+  // completed prior tasks are not recreated; subtasks so nested tasks match too.
+  // This is an idempotent read → retryable.
+  async function listAllTasks(listId) {
+    const tasks = [];
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const body = await rpc.callTool(
+        'clickup_get-tasks',
+        { list_id: listId, page, include_closed: true, subtasks: true },
+        { retryable: true },
+      );
+      const pageTasks = Array.isArray(body?.tasks) ? body.tasks : [];
+      if (pageTasks.length === 0) return tasks;
+      tasks.push(...pageTasks);
+      if (body?.last_page === true) return tasks;
+    }
+    throw new Error(`ClickUp list ${listId} exceeded the ${MAX_PAGES}-page cap; aborting to avoid duplicate creates.`);
+  }
+
+  // Write — never retried (a retried POST could duplicate the task).
+  // tags/priority are create-time enrichment, forwarded only when present so
+  // the payload stays identical to the direct client for the same item.
+  async function createTask(listId, { name, description, tags, priority }) {
+    const args = { list_id: listId, name, description };
+    if (tags !== undefined) args.tags = tags;
+    if (priority !== undefined) args.priority = priority;
+    return rpc.callTool('clickup_create-task', args);
+  }
+
+  // Write — never retried (a retried POST could duplicate the comment).
+  async function addComment(taskId, commentText) {
+    return rpc.callTool('clickup_add-comment', { task_id: taskId, comment_text: commentText });
+  }
+
+  return { listAllTasks, createTask, addComment };
+}

package/integrations/clickup.mjs

@@ -1,3 +1,6 @@
+import { resolveGitHubToken, DEFAULT_MCP_URL } from '../mcp.mjs';
+import { createClickUpProxyClient } from './clickup-proxy.mjs';
+
 // integrations/clickup.mjs — ClickUp v2 HTTP client for the aw CLI.
 //
 // Faithful .mjs port of apps/api/src/mcp/integrations/clickup.handler.ts, which
@@ -119,10 +122,15 @@ export function createClickUpClient(opts = {}) {
     throw new Error(`ClickUp list ${listId} exceeded the ${MAX_PAGES}-page cap; aborting to avoid duplicate creates.`);
   }
 
-  async function createTask(listId, { name, description }) {
+  async function createTask(listId, { name, description, tags, priority }) {
+    // tags/priority are create-time enrichment, included only when present so the
+    // body matches the proxy client for the same item (identical outcome invariant).
+    const body = { name, description };
+    if (tags !== undefined) body.tags = tags;
+    if (priority !== undefined) body.priority = priority;
     return clickupFetch(`/list/${encodeURIComponent(listId)}/task`, {
       method: 'POST',
-      body: JSON.stringify({ name, description }),
+      body: JSON.stringify(body),
     });
   }
 
@@ -135,3 +143,35 @@ export function createClickUpClient(opts = {}) {
 
   return { clickupFetch, listAllTasks, createTask, addComment };
 }
+
+/**
+ * Pick the ClickUp client for `aw clickup-sync`. Proxy-by-default: route through
+ * the deployed ghl-ai MCP using the developer's GitHub PAT (no local ClickUp
+ * token). `--direct` or AW_CLICKUP_DIRECT=1 opts back into the direct
+ * api.clickup.com client (which requires CLICKUP_API_TOKEN).
+ *
+ * deps are injectable for tests; the CLI passes none.
+ * @param {Record<string, unknown>} [args] parsed CLI args
+ * @param {{ env?: NodeJS.ProcessEnv, resolveGitHubToken?: Function,
+ *   createClickUpClient?: Function, createClickUpProxyClient?: Function }} [deps]
+ */
+export function resolveClickUpClient(args = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const resolveToken = deps.resolveGitHubToken ?? resolveGitHubToken;
+  const makeDirect = deps.createClickUpClient ?? (() => createClickUpClient());
+  const makeProxy = deps.createClickUpProxyClient ?? ((cfg) => createClickUpProxyClient(cfg));
+
+  const wantsDirect = args['--direct'] === true || env.AW_CLICKUP_DIRECT === '1';
+  if (wantsDirect) {
+    return makeDirect();
+  }
+
+  const token = resolveToken(true);
+  if (!token) {
+    throw new Error(
+      'No GitHub PAT for the ghl-ai MCP proxy. Run `gh auth login` or set GITHUB_TOKEN, or use --direct with CLICKUP_API_TOKEN.',
+    );
+  }
+  const mcpUrl = env.GHL_MCP_URL || DEFAULT_MCP_URL;
+  return makeProxy({ mcpUrl, token });
+}

package/integrations/mcp-rpc.mjs

@@ -0,0 +1,218 @@
+// integrations/mcp-rpc.mjs — minimal MCP JSON-RPC session client for the aw CLI.
+//
+// A standalone-ESM port of the subset of apps/api/src/mcp/integrations/
+// remote-mcp.client.ts that the CLI needs: open a session (initialize ->
+// notifications/initialized), then call tools (tools/call) over Streamable
+// HTTP, carrying Mcp-Session-Id and unwrapping the MCP content envelope.
+//
+// Retry policy is the load-bearing safety property: callTool does NOT retry by
+// default. Only reads that pass { retryable: true } are retried on transport
+// timeouts/5xx. Writes (create-task, add-comment) must never auto-retry — a
+// transport failure after a server-side success would duplicate the write; the
+// caller is expected to be resumable instead.
+
+const DEFAULT_PROTOCOL_VERSION = '2025-03-26';
+const DEFAULT_CLIENT_INFO = { name: 'ghl-ai-aw-cli', version: '1.0.0' };
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class McpRpcError extends Error {
+  constructor(message, { status, timeout = false, transport = false } = {}) {
+    super(message);
+    this.name = 'McpRpcError';
+    this.status = status;
+    this.timeout = timeout;
+    this.transport = transport;
+  }
+}
+
+function errMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// Parse an MCP HTTP body as either a JSON-RPC object or the last data: frame of
+// an SSE stream (Streamable HTTP fallback). Mirrors remote-mcp.client parseRpcPayload.
+function parseRpcPayload(raw) {
+  const trimmed = (raw ?? '').trim();
+  if (!trimmed) return {};
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Fall through to SSE frame parsing.
+  }
+
+  const lines = trimmed.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (!line?.startsWith('data:')) continue;
+    const payload = line.slice(5).trim();
+    if (!payload || payload === '[DONE]') continue;
+    try {
+      return JSON.parse(payload);
+    } catch {
+      // Try an earlier frame.
+    }
+  }
+
+  throw new McpRpcError(`Unable to parse upstream MCP response: ${trimmed.slice(0, 300)}`);
+}
+
+// Unwrap an MCP tools/call `result` content envelope into a usable value.
+// A single text block is JSON-parsed (falling back to the raw text); an error
+// envelope throws. Mirrors remote-mcp.client unwrapMcpTextContent.
+export function unwrapMcpContent(payload) {
+  if (!payload || typeof payload !== 'object') return payload;
+
+  const result = payload;
+  if (result.isError === true) {
+    const errorText = Array.isArray(result.content)
+      ? result.content.find((item) => item?.type === 'text')?.text
+      : undefined;
+    throw new McpRpcError(typeof errorText === 'string' ? errorText : 'Upstream MCP tool returned an error');
+  }
+
+  if (!Array.isArray(result.content) || result.content.length === 0) {
+    return payload;
+  }
+
+  if (result.content.length === 1 && result.content[0]?.type === 'text') {
+    const text = result.content[0]?.text;
+    if (typeof text !== 'string') return payload;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  return result.content;
+}
+
+function isStaleSessionError(err) {
+  if (!(err instanceof McpRpcError)) return false;
+  if (err.status === 404 || err.status === 410) return true;
+  const body = errMessage(err).toLowerCase();
+  return body.includes('session') && (body.includes('not found') || body.includes('expired') || body.includes('invalid'));
+}
+
+function isRetryableError(err) {
+  if (err instanceof McpRpcError) {
+    if (err.timeout || err.transport) return true;
+    return err.status === 502 || err.status === 503 || err.status === 504;
+  }
+  return err instanceof Error;
+}
+
+/**
+ * @param {{ url: string, token: string, fetchImpl?: typeof fetch, timeoutMs?: number,
+ *   clientInfo?: { name: string, version: string }, protocolVersion?: string }} config
+ */
+export function createMcpRpcClient(config = {}) {
+  const { url, token } = config;
+  if (!url || typeof url !== 'string') throw new Error('createMcpRpcClient: url is required');
+  if (!token || typeof token !== 'string') throw new Error('createMcpRpcClient: token is required');
+
+  const doFetch = config.fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== 'function') throw new Error('createMcpRpcClient: fetch is unavailable');
+  const timeoutMs = Number.isFinite(config.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const clientInfo = config.clientInfo ?? DEFAULT_CLIENT_INFO;
+  const protocolVersion = config.protocolVersion ?? DEFAULT_PROTOCOL_VERSION;
+
+  let sessionId;
+  let initialized = false;
+  let rpcId = 1;
+
+  async function sendRpc(payload, { parseBody = true } = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await doFetch(url, {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json, text/event-stream',
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${token}`,
+          ...(sessionId ? { 'Mcp-Session-Id': sessionId } : {}),
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        throw new McpRpcError(`MCP request timed out after ${timeoutMs}ms`, { timeout: true });
+      }
+      throw new McpRpcError(`MCP endpoint unreachable: ${errMessage(err)}`, { transport: true });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const raw = parseBody ? await response.text() : '';
+    const sid = response.headers.get('mcp-session-id');
+    if (sid) sessionId = sid;
+
+    if (!response.ok) {
+      throw new McpRpcError(`MCP ${response.status}: ${raw.slice(0, 500)}`, { status: response.status });
+    }
+    return parseBody ? parseRpcPayload(raw) : undefined;
+  }
+
+  function invalidateSession() {
+    sessionId = undefined;
+    initialized = false;
+  }
+
+  async function ensureSession() {
+    if (initialized && sessionId) return;
+    await sendRpc({
+      jsonrpc: '2.0',
+      id: rpcId++,
+      method: 'initialize',
+      params: { protocolVersion, capabilities: {}, clientInfo },
+    });
+    await sendRpc({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }, { parseBody: false });
+    initialized = true;
+  }
+
+  function unwrapEnvelope(payload) {
+    if (!payload || typeof payload !== 'object') return payload;
+    if (payload.error) {
+      throw new McpRpcError(payload.error.message ?? 'MCP returned an error');
+    }
+    return 'result' in payload ? payload.result : payload;
+  }
+
+  /**
+   * Call an MCP tool and return its unwrapped content.
+   * @param {string} name
+   * @param {Record<string, unknown>} args
+   * @param {{ retryable?: boolean }} [options] retryable=true only for idempotent reads.
+   */
+  async function callTool(name, args = {}, { retryable = false } = {}) {
+    const invoke = async () => {
+      await ensureSession();
+      const parsed = await sendRpc({
+        jsonrpc: '2.0',
+        id: rpcId++,
+        method: 'tools/call',
+        params: { name, arguments: args },
+      });
+      return unwrapMcpContent(unwrapEnvelope(parsed));
+    };
+
+    try {
+      return await invoke();
+    } catch (err) {
+      if (isStaleSessionError(err)) {
+        invalidateSession();
+        return invoke();
+      }
+      if (retryable && isRetryableError(err)) {
+        return invoke();
+      }
+      throw err;
+    }
+  }
+
+  return { callTool };
+}

package/mcp.mjs

@@ -11,7 +11,7 @@ import * as p from '@clack/prompts';
 import * as fmt from './fmt.mjs';
 
 const HOME = homedir();
-const DEFAULT_MCP_URL = 'https://services.leadconnectorhq.com/agentic-workspace/mcp';
+export const DEFAULT_MCP_URL = 'https://services.leadconnectorhq.com/agentic-workspace/mcp';
 const MCP_PREFS_FILENAME = 'mcp-preferences.json';
 const ENABLED_MODE = 'enabled';
 const DISABLED_MODE = 'disabled';
@@ -121,7 +121,7 @@ function warnIfCodexBearerEnvMissing(envVar, silent = false) {
  *   2. `gh auth token` (GitHub CLI — most devs have this)
  *   3. null (fall back to ${GITHUB_TOKEN} interpolation in config)
  */
-function resolveGitHubToken(silent = false) {
+export function resolveGitHubToken(silent = false) {
   // 1. Environment variable
   if (process.env.GITHUB_TOKEN) {
     if (!silent) fmt.logStep('Using GITHUB_TOKEN from environment');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.85",
+  "version": "0.1.88",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {