atris 3.2.0 → 3.11.0

package/lib/scorecard.js

@@ -4,16 +4,31 @@ const { parseTodo } = require('./todo');
 
 const PRIVATE_MEMORY_ROOT = '.atris/presidio';
 
+/**
+ * Ensure the private memory directory exists.
+ * @param {string} atrisDir - Path to the atris directory
+ * @returns {string} Path to the private memory directory
+ */
 function ensurePrivateMemoryDir(atrisDir) {
   const privateDir = path.join(path.dirname(atrisDir), PRIVATE_MEMORY_ROOT);
   fs.mkdirSync(privateDir, { recursive: true });
   return privateDir;
 }
 
+/**
+ * Get the path to the scorecards file.
+ * @param {string} atrisDir - Path to the atris directory
+ * @returns {string} Path to scorecards.md
+ */
 function getScorecardsPath(atrisDir) {
   return path.join(ensurePrivateMemoryDir(atrisDir), 'scorecards.md');
 }
 
+/**
+ * Parse a "picked at" timestamp from scorecard data.
+ * @param {string} value - Timestamp string in YYYY-MM-DD [HH:MM] format
+ * @returns {Date|null} Parsed date or null if invalid
+ */
 function parsePickedAt(value) {
   if (!value) return null;
   const match = String(value).trim().match(/^(\d{4}-\d{2}-\d{2})(?:\s+(\d{2}:\d{2}))?/);
@@ -24,6 +39,12 @@ function parsePickedAt(value) {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
 
+/**
+ * Parse a tick timestamp combining date and time label.
+ * @param {string} dateStr - Date in YYYY-MM-DD format
+ * @param {string} timeLabel - Time label like "2:30 PM"
+ * @returns {Date|null} Parsed date or null if invalid
+ */
 function parseTickDate(dateStr, timeLabel) {
   const match = String(timeLabel || '').trim().toLowerCase().match(/^(\d{1,2}):(\d{2})(?:\s*(am|pm))?$/);
   if (!match) return null;
@@ -40,6 +61,13 @@ function parseTickDate(dateStr, timeLabel) {
   return Number.isNaN(parsed.getTime()) ? null : parsed;
 }
 
+/**
+ * List journal log files within a date range.
+ * @param {string} atrisDir - Path to the atris directory
+ * @param {Date} startDate - Start of date range
+ * @param {Date} [endDate] - End of date range (defaults to today)
+ * @returns {Array} Array of log file paths
+ */
 function listLogFiles(atrisDir, startDate, endDate = new Date()) {
   const logsDir = path.join(atrisDir, 'logs');
   if (!fs.existsSync(logsDir)) return [];
@@ -153,16 +181,20 @@ function buildScorecardData(atrisDir, { slug, pickedAt } = {}) {
   const todo = parseTodo(todoPath);
   const startAt = parsePickedAt(pickedAt) || new Date();
   const rewardStats = collectRewardStats(atrisDir, pickedAt);
-  const completedEndgame = todo.completed.filter(t => t.tag === 'endgame').length;
+  // Count shipped tasks from journal completions (tasks get deleted from TODO.md after completion)
+  const completedFromTodo = todo.completed.filter(t => t.tag === 'endgame').length;
   const activeEndgame = todo.backlog.filter(t => t.tag === 'endgame').length
     + todo.inProgress.filter(t => t.tag === 'endgame').length;
+  // Fall back to reward tick count if TODO completions were already pruned
+  const shipped = completedFromTodo > 0 ? completedFromTodo : rewardStats.totalTicks - rewardStats.haltedTicks;
+  const attempted = shipped + activeEndgame + rewardStats.haltedTicks;
 
   return {
     slug,
     startDate: startAt.toISOString().slice(0, 10),
     endDate: new Date().toISOString().slice(0, 10),
-    tasksShipped: completedEndgame,
-    tasksAttempted: completedEndgame + activeEndgame,
+    tasksShipped: Math.max(shipped, 0),
+    tasksAttempted: Math.max(attempted, shipped),
     wallClockHours: Math.max(0, (Date.now() - startAt.getTime()) / (1000 * 60 * 60)),
     haltRatio: rewardStats.totalTicks > 0 ? rewardStats.haltedTicks / rewardStats.totalTicks : 0,
     totalReward: rewardStats.totalReward,
@@ -205,6 +237,12 @@ function writeScorecard(atrisDir, data) {
 
   const scorecardsPath = getScorecardsPath(atrisDir);
 
+  // Dedupe guard: don't write the same slug twice
+  const existing = readScorecards(atrisDir);
+  if (existing.some(sc => sc.slug === slug)) {
+    return; // already written
+  }
+
   // Ensure scorecards.md exists
   if (!fs.existsSync(scorecardsPath)) {
     const template = `# scorecards.md — Endgame Results\n\n> Append-only. One line per closed endgame. Records outcome metrics from the horizon.\n\n---\n\n`;
@@ -263,7 +301,7 @@ function readScorecards(atrisDir) {
   const scorecards = [];
 
   for (const line of content.split('\n')) {
-    const match = line.match(/^- \*\*\[(.+?)\]\s+(.+?)\*\*\s*—\s*shipped:\s*(\d+)\/(\d+)\s*—\s*wall-clock:\s*(.+?)\s*—\s*halt:\s*(\d+)%\s*—\s*reward:\s*(\d+)\s*—\s*lessons:\s*(\d+)$/);
+    const match = line.match(/^- \*\*\[(.+?)\]\s+(.+?)\*\*\s*—\s*shipped:\s*(\d+)\/(\d+)\s*—\s*wall-clock:\s*(.+?)\s*—\s*halt:\s*(\d+)%\s*—\s*reward:\s*(-?\d+)\s*—\s*lessons:\s*(\d+)$/);
     if (!match) continue;
 
     const [, endDate, slug, shipped, attempted, wallClockStr, haltPercent, reward, lessons] = match;

package/lib/sync-telemetry.js

@@ -0,0 +1,59 @@
+// Atris sync telemetry — emit one event per `atris push` / `atris pull`.
+//
+// Why awaited (not fire-and-forget): push.js / pull.js call process.exit(1)
+// on most failure paths. A fire-and-forget POST gets killed mid-flight and
+// the RL loop loses signals on the exact failures it most needs to learn.
+//
+// Best-effort: any error swallowed silently — telemetry never blocks UX.
+// Hard 2s timeout so a flaky control plane can't slow real operations.
+
+const { apiRequestJson } = require('../utils/api');
+
+let _cachedVersion = null;
+function cliVersion() {
+  if (_cachedVersion) return _cachedVersion;
+  try {
+    _cachedVersion = require('../package.json').version || 'unknown';
+  } catch {
+    _cachedVersion = 'unknown';
+  }
+  return _cachedVersion;
+}
+
+async function emitSyncEvent(token, businessId, workspaceId, op, outcome, latencyMs, extras = {}) {
+  if (!token || !businessId || !workspaceId || !op || !outcome) return false;
+  const event = {
+    business_id: businessId,
+    workspace_id: workspaceId,
+    op,
+    outcome,
+    latency_ms: Math.max(0, Math.round(latencyMs || 0)),
+    bytes_transferred: extras.bytes_transferred || 0,
+    bytes_changed: extras.bytes_changed || 0,
+    files_pushed: extras.files_pushed || 0,
+    files_deleted: extras.files_deleted || 0,
+    files_unchanged: extras.files_unchanged || 0,
+    cli_version: cliVersion(),
+  };
+  if (extras.error_detail) event.error_detail = String(extras.error_detail).slice(0, 500);
+
+  try {
+    await apiRequestJson('/atris-sync/telemetry', {
+      method: 'POST',
+      token,
+      body: event,
+      timeoutMs: 2000,
+      retries: 0,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function startTimer() {
+  const t0 = Date.now();
+  return () => Date.now() - t0;
+}
+
+module.exports = { emitSyncEvent, startTimer };

package/lib/todo.js

@@ -17,6 +17,12 @@ function parseTodo(todoPath) {
   };
 }
 
+/**
+ * Parse a specific section from TODO.md content into task objects.
+ * @param {string} content - Full TODO.md content
+ * @param {string} sectionName - Section name to extract (e.g., 'Backlog')
+ * @returns {Array} Array of parsed task objects
+ */
 function parseSection(content, sectionName) {
   const escaped = sectionName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const match = content.match(new RegExp(`##\\s+${escaped}\\n([\\s\\S]*?)(?=\\n##|$)`, 'i'));

package/lib/wiki.js

@@ -2,7 +2,9 @@ const fs = require('fs');
 const path = require('path');
 
 const WIKI_ROOT = 'atris/wiki';
+const CONTEXT_ROOT = 'atris/context';
 const PRIVATE_WIKI_ROOT = '.atris/presidio';
+const PRIVATE_CONTEXT_ROOT = `${PRIVATE_WIKI_ROOT}/context`;
 const LEGACY_WIKI_ROOT = 'wiki';
 const WIKI_BRIEFS_SUBDIR = 'briefs';
 const LEGACY_WIKI_BRIEFS_SUBDIR = 'syntheses';
@@ -14,6 +16,10 @@ function getWikiRoot(mode = 'public') {
   return mode === 'private' ? PRIVATE_WIKI_ROOT : WIKI_ROOT;
 }
 
+function getContextRoot(mode = 'public') {
+  return mode === 'private' ? PRIVATE_CONTEXT_ROOT : CONTEXT_ROOT;
+}
+
 function getWikiLinkRoot(mode = 'public') {
   return mode === 'private' ? PRIVATE_WIKI_ROOT : 'atris/wiki';
 }
@@ -89,6 +95,23 @@ function statusMarkdown() {
 `;
 }
 
+function contextMarkdown(mode = 'public') {
+  const contextRoot = getContextRoot(mode);
+  const wikiRoot = getWikiRoot(mode);
+  return `# Context
+
+Raw source material lives in \`${contextRoot}/\`.
+Compiled memory belongs in \`${wikiRoot}/\`.
+
+## Rules
+
+- Drop source files or source packs here before compiling them into the wiki.
+- Treat source files as immutable evidence. If the source changes, add a new dated copy.
+- Keep compiled summaries, briefs, and durable facts in the wiki instead of this folder.
+- Use \`${contextRoot}/_ingest/\` for staged ingest packs and receipts.
+`;
+}
+
 function ensureFile(filePath, content) {
   if (!fs.existsSync(filePath)) {
     fs.writeFileSync(filePath, content, 'utf8');
@@ -185,6 +208,122 @@ function ensureWikiScaffold(projectRoot = process.cwd(), mode = 'public') {
   return wikiDir;
 }
 
+function ensureContextScaffold(projectRoot = process.cwd(), mode = 'public') {
+  const contextRoot = getContextRoot(mode);
+  const contextDir = path.join(projectRoot, contextRoot);
+  fs.mkdirSync(path.join(contextDir, '_ingest'), { recursive: true });
+  ensureFile(path.join(contextDir, 'README.md'), contextMarkdown(mode));
+  return contextDir;
+}
+
+function slugifyLabel(value) {
+  return String(value || 'source')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'source';
+}
+
+function isInsideDirectory(candidate, rootDir) {
+  const relative = path.relative(rootDir, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function walkFiles(dir, output = []) {
+  if (!fs.existsSync(dir)) return output;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(fullPath, output);
+    } else if (entry.isFile()) {
+      output.push(fullPath);
+    }
+  }
+  return output;
+}
+
+function stageWikiIngest(projectRoot = process.cwd(), sourceValue, mode = 'public') {
+  const contextDir = ensureContextScaffold(projectRoot, mode);
+  const ingestDir = path.join(contextDir, '_ingest');
+  const raw = String(sourceValue || '').trim();
+  const timestamp = `${today()}-${nowTime().replace(':', '')}`;
+  const labelSeed = raw ? path.basename(raw) : 'source-pack';
+  const packDir = path.join(ingestDir, `${timestamp}-${slugifyLabel(labelSeed)}`);
+  fs.mkdirSync(packDir, { recursive: true });
+
+  const manifest = {
+    ingested_at: `${today()} ${nowTime()}`,
+    mode,
+    source_input: raw,
+    pack_path: path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    entries: [],
+  };
+
+  const maybeUrl = /^https?:\/\//i.test(raw);
+  const sourcePath = raw ? path.resolve(projectRoot, raw) : null;
+
+  if (raw && sourcePath && fs.existsSync(sourcePath)) {
+    const stat = fs.statSync(sourcePath);
+    if (isInsideDirectory(sourcePath, contextDir)) {
+      const files = stat.isDirectory() ? walkFiles(sourcePath) : [sourcePath];
+      manifest.entries.push({
+        kind: stat.isDirectory() ? 'directory' : 'file',
+        original: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        staged: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        file_count: files.length,
+        files: files.map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, '/')),
+      });
+    } else {
+      const stagedPath = path.join(packDir, path.basename(sourcePath));
+      if (stat.isDirectory()) {
+        fs.cpSync(sourcePath, stagedPath, { recursive: true });
+      } else {
+        fs.copyFileSync(sourcePath, stagedPath);
+      }
+      const files = stat.isDirectory() ? walkFiles(stagedPath) : [stagedPath];
+      manifest.entries.push({
+        kind: stat.isDirectory() ? 'directory' : 'file',
+        original: path.relative(projectRoot, sourcePath).replace(/\\/g, '/'),
+        staged: path.relative(projectRoot, stagedPath).replace(/\\/g, '/'),
+        file_count: files.length,
+        files: files.map((filePath) => path.relative(projectRoot, filePath).replace(/\\/g, '/')),
+      });
+    }
+  } else if (maybeUrl) {
+    const linksPath = path.join(packDir, 'links.txt');
+    fs.writeFileSync(linksPath, `${raw}\n`, 'utf8');
+    manifest.entries.push({
+      kind: 'url',
+      original: raw,
+      staged: path.relative(projectRoot, linksPath).replace(/\\/g, '/'),
+      file_count: 1,
+      files: [path.relative(projectRoot, linksPath).replace(/\\/g, '/')],
+    });
+  } else {
+    const requestPath = path.join(packDir, 'request.txt');
+    fs.writeFileSync(requestPath, `${raw || '(empty)'}\n`, 'utf8');
+    manifest.entries.push({
+      kind: 'unresolved',
+      original: raw || '(empty)',
+      staged: path.relative(projectRoot, requestPath).replace(/\\/g, '/'),
+      file_count: 1,
+      files: [path.relative(projectRoot, requestPath).replace(/\\/g, '/')],
+    });
+  }
+
+  const manifestPath = path.join(packDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+  return {
+    contextDir: path.relative(projectRoot, contextDir).replace(/\\/g, '/'),
+    packPath: path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    manifestPath: path.relative(projectRoot, manifestPath).replace(/\\/g, '/'),
+    promptSource: manifest.entries[0]?.staged || path.relative(projectRoot, packDir).replace(/\\/g, '/'),
+    manifest,
+  };
+}
+
 function findLocalWikiDir(projectRoot = process.cwd(), slug = null, mode = 'public') {
   if (mode === 'private') {
     const privateDir = path.join(projectRoot, PRIVATE_WIKI_ROOT);
@@ -444,7 +583,7 @@ function parseStatusBullets(content) {
   return bullets;
 }
 
-function writeWikiStatus(projectRoot = process.cwd(), report, mode = 'public') {
+function writeWikiStatus(projectRoot = process.cwd(), report, mode = 'public', overrides = {}) {
   const wikiDir = ensureWikiScaffold(projectRoot, mode);
   const statusPath = path.join(wikiDir, WIKI_STATUS_FILE);
   const existing = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : '';
@@ -453,9 +592,9 @@ function writeWikiStatus(projectRoot = process.cwd(), report, mode = 'public') {
   const lines = [
     '# Atris Wiki Status',
     '',
-    `- Last ingest: ${bullets.get('Last ingest') || 'never'}`,
-    `- Last lint: ${bullets.get('Last lint') || 'never'}`,
-    `- Last loop: ${today()} ${nowTime()}`,
+    `- Last ingest: ${overrides.lastIngest || bullets.get('Last ingest') || 'never'}`,
+    `- Last lint: ${overrides.lastLint || bullets.get('Last lint') || 'never'}`,
+    `- Last loop: ${overrides.lastLoop || `${today()} ${nowTime()}`}`,
     `- Health: ${report.health}`,
     `- Next move: ${report.nextMove}`,
     '',
@@ -465,7 +604,7 @@ function writeWikiStatus(projectRoot = process.cwd(), report, mode = 'public') {
   return statusPath;
 }
 
-function appendWikiLog(projectRoot = process.cwd(), summary, details = [], mode = 'public') {
+function appendWikiLog(projectRoot = process.cwd(), summary, details = [], mode = 'public', kind = 'LOOP') {
   const wikiDir = ensureWikiScaffold(projectRoot, mode);
   const logPath = path.join(wikiDir, 'log.md');
   let content = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '# Atris Wiki Log\n';
@@ -476,7 +615,7 @@ function appendWikiLog(projectRoot = process.cwd(), summary, details = [], mode
   }
 
   if (!content.endsWith('\n')) content += '\n';
-  content += `- ${nowTime()} LOOP ${summary}\n`;
+  content += `- ${nowTime()} ${kind} ${summary}\n`;
   for (const detail of details) {
     content += `  - ${detail}\n`;
   }
@@ -586,14 +725,18 @@ Output:
 
 module.exports = {
   WIKI_ROOT,
+  CONTEXT_ROOT,
   PRIVATE_WIKI_ROOT,
+  PRIVATE_CONTEXT_ROOT,
   LEGACY_WIKI_ROOT,
   WIKI_SUBDIRS,
   WIKI_CONTENT_SUBDIRS,
   WIKI_SCHEMA: buildWikiSchema(),
   WIKI_STATUS_FILE,
   getWikiRoot,
+  getContextRoot,
   ensureWikiScaffold,
+  ensureContextScaffold,
   findLocalWikiDir,
   normalizeWikiOnlyPrefix,
   readWikiStatus,
@@ -601,6 +744,7 @@ module.exports = {
   findStaleWikiPages,
   findWikiOrphans,
   findSuggestedSources,
+  stageWikiIngest,
   writeWikiStatus,
   appendWikiLog,
   buildIngestPrompt,

package/lib/workspace-safety.js

@@ -0,0 +1,87 @@
+const path = require('path');
+const os = require('os');
+
+// Returns a human-readable reason string if `dir` is a path we must never
+// treat as an Atris workspace root (pull/push would walk and mutate it).
+// Returns null if the dir is safe.
+//
+// The real bug this guards against: if outputDir resolves to $HOME, pull's
+// force mirror sweep walks ~/Library, ~/Documents, ~/Downloads, ... and
+// deletes any local file not on cloud. That wipes the user's home dir.
+function dangerousWorkspaceReason(dir) {
+  if (!dir) return 'empty path';
+  const abs = path.resolve(dir);
+  const home = os.homedir();
+  const rootParsed = path.parse(abs).root;
+
+  if (abs === home) return 'your home directory';
+  if (abs === rootParsed) return 'the filesystem root';
+  if (abs === path.dirname(home)) return `the users root (${path.dirname(home)})`;
+
+  const systemPaths = [
+    '/tmp', '/var', '/etc', '/usr', '/bin', '/sbin', '/opt',
+    '/private', '/Library', '/Applications', '/System', '/Volumes',
+    '/Users', '/home', '/root',
+  ];
+  for (const p of systemPaths) {
+    if (abs === p) return `the system path ${p}`;
+  }
+
+  // Reserved top-level folders inside the user's home — never workspaces.
+  const homeReservedNames = new Set([
+    'Library', 'Applications', 'Documents', 'Downloads', 'Desktop',
+    'Pictures', 'Music', 'Movies', 'Public', 'Sites', 'Dropbox',
+    'OneDrive', 'iCloud Drive',
+  ]);
+  if (path.dirname(abs) === home && homeReservedNames.has(path.basename(abs))) {
+    return `a reserved home folder (~/${path.basename(abs)})`;
+  }
+
+  return null;
+}
+
+// Pick a safe fallback directory for a business workspace when the
+// originally-resolved path is dangerous. Prefers cwd/slug, falls back to
+// ~/atris-workspaces/slug if cwd itself is unsafe.
+function safeFallbackDir(slug, cwd) {
+  const cwdFallback = path.join(cwd, slug);
+  if (!dangerousWorkspaceReason(cwdFallback)) return cwdFallback;
+  return path.join(os.homedir(), 'atris-workspaces', slug);
+}
+
+// Resolve an outputDir, auto-relocating to a safe fallback if the originally
+// chosen path is dangerous. Non-technical users don't need to know about
+// mkdir/cd — atris picks a safe folder and tells them where it landed.
+function resolveSafeOutputDir(requested, { slug, cwd = process.cwd(), op = 'use' } = {}) {
+  const reason = dangerousWorkspaceReason(requested);
+  if (!reason) return { dir: path.resolve(requested), relocated: false };
+
+  const fallback = safeFallbackDir(slug, cwd);
+  console.log('');
+  console.log(`  ${requested} is ${reason} — not safe to ${op}.`);
+  console.log(`  Using ${fallback} instead.`);
+  console.log('');
+  return { dir: fallback, relocated: true, originalReason: reason };
+}
+
+// Hard-refuse variant — used by push where we can't auto-relocate (the
+// source has to be where the user actually has their files).
+function assertSafeWorkspaceRoot(dir, { slug, op } = {}) {
+  const reason = dangerousWorkspaceReason(dir);
+  if (!reason) return;
+  const label = op || 'operate on';
+  console.error('');
+  console.error(`  Refusing to ${label} ${dir} (${reason}).`);
+  console.error('');
+  console.error('  Atris would walk this folder and sync files inside it.');
+  console.error('  Cd into a dedicated workspace folder first.');
+  if (slug) console.error(`  For example:  mkdir -p ~/code/${slug} && cd ~/code/${slug}`);
+  process.exit(1);
+}
+
+module.exports = {
+  dangerousWorkspaceReason,
+  safeFallbackDir,
+  resolveSafeOutputDir,
+  assertSafeWorkspaceRoot,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.2.0",
+  "version": "3.11.0",
   "description": "Atris — an operating system for intelligence. Integrates with any agent.",
   "main": "bin/atris.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin/",
+    "cli/",
     "commands/",
     "utils/",
     "lib/",

package/utils/api.js

@@ -20,22 +20,41 @@ try {
 const DEFAULT_CLIENT_ID = `AtrisCLI/${CLI_VERSION}`;
 const DEFAULT_USER_AGENT = `${DEFAULT_CLIENT_ID} (node ${process.version}; ${os.platform()} ${os.release()} ${os.arch()})`;
 
+/**
+ * Get the base URL for the Atris API.
+ * @returns {string} API base URL
+ */
 function getApiBaseUrl() {
   const raw = process.env.ATRIS_API_URL || 'https://api.atris.ai/api';
   return raw.replace(/\/$/, '');
 }
 
+/**
+ * Get the base URL for the Atris web app.
+ * @returns {string} App base URL
+ */
 function getAppBaseUrl() {
   const raw = process.env.ATRIS_APP_URL || 'https://atris.ai';
   return raw.replace(/\/$/, '');
 }
 
+/**
+ * Build a full API URL from a path.
+ * @param {string} pathname - API endpoint path
+ * @returns {string} Full API URL
+ */
 function buildApiUrl(pathname) {
   const base = getApiBaseUrl();
   const normalizedPath = pathname.startsWith('/') ? pathname : `/${pathname}`;
   return `${base}${normalizedPath}`;
 }
 
+/**
+ * Make an HTTP/HTTPS request.
+ * @param {string} urlString - Full URL to request
+ * @param {Object} options - Request options (method, headers, body, timeoutMs)
+ * @returns {Promise<Object>} Response with statusCode, headers, and data
+ */
 function httpRequest(urlString, options) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(urlString);

package/utils/auth.js

@@ -4,6 +4,10 @@ const fs = require('fs');
 const { exec } = require('child_process');
 const readline = require('readline');
 
+/**
+ * Open a URL in the system's default browser.
+ * @param {string} url - URL to open
+ */
 function openBrowser(url) {
   const platform = os.platform();
   // Sanitize URL to prevent shell injection — only allow valid URL characters
@@ -30,6 +34,11 @@ let sharedRl = null;
 let inputLines = [];
 let inputIndex = 0;
 
+/**
+ * Prompt the user for input, handling both TTY and piped input.
+ * @param {string} question - Prompt text to display
+ * @returns {Promise<string>} User's input
+ */
 function promptUser(question) {
   // If stdin is not a TTY (piped input), read all lines upfront
   if (!process.stdin.isTTY && inputLines.length === 0 && !sharedRl) {
@@ -74,7 +83,11 @@ function promptUser(question) {
 
 const TOKEN_REFRESH_BUFFER_SECONDS = 300;
 
-// JWT helpers
+/**
+ * Decode and parse the claims from a JWT token.
+ * @param {string} token - JWT token string
+ * @returns {Object|null} Decoded claims or null if invalid
+ */
 function decodeJwtClaims(token) {
   if (!token || typeof token !== 'string') {
     return null;
@@ -93,6 +106,11 @@ function decodeJwtClaims(token) {
   }
 }
 
+/**
+ * Get the expiration time of a JWT token in epoch seconds.
+ * @param {string} token - JWT token string
+ * @returns {number|null} Expiry epoch seconds or null if invalid
+ */
 function getTokenExpiryEpochSeconds(token) {
   const claims = decodeJwtClaims(token);
   if (!claims || typeof claims.exp !== 'number') {
@@ -101,6 +119,12 @@ function getTokenExpiryEpochSeconds(token) {
   return claims.exp;
 }
 
+/**
+ * Check if a JWT token should be refreshed based on expiry.
+ * @param {string} token - JWT token string
+ * @param {number} [bufferSeconds=300] - Seconds before expiry to trigger refresh
+ * @returns {boolean} True if token needs refresh
+ */
 function shouldRefreshToken(token, bufferSeconds = TOKEN_REFRESH_BUFFER_SECONDS) {
   const exp = getTokenExpiryEpochSeconds(token);
   if (!exp) {

package/utils/config.js

@@ -1,11 +1,19 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * Get the path to atris/.config in the current project.
+ * @returns {string} Config file path
+ */
 function getConfigPath() {
   const targetDir = path.join(process.cwd(), 'atris');
   return path.join(targetDir, '.config');
 }
 
+/**
+ * Load config from atris/.config, returning empty object if missing/invalid.
+ * @returns {Object} Config object
+ */
 function loadConfig() {
   const configPath = getConfigPath();
 
@@ -21,6 +29,10 @@ function loadConfig() {
   }
 }
 
+/**
+ * Save config to atris/.config. Exits if atris/ folder doesn't exist.
+ * @param {Object} config - Config object to save
+ */
 function saveConfig(config) {
   const configPath = getConfigPath();
   const targetDir = path.dirname(configPath);
@@ -33,11 +45,19 @@ function saveConfig(config) {
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
 
+/**
+ * Get the path to atris/.log_sync_state.json for tracking sync timestamps.
+ * @returns {string} Log sync state file path
+ */
 function getLogSyncStatePath() {
   const targetDir = path.join(process.cwd(), 'atris');
   return path.join(targetDir, '.log_sync_state.json');
 }
 
+/**
+ * Load log sync state, returning empty object if missing/invalid.
+ * @returns {Object} Sync state object with last sync timestamps
+ */
 function loadLogSyncState() {
   const statePath = getLogSyncStatePath();
   if (!fs.existsSync(statePath)) {
@@ -51,6 +71,10 @@ function loadLogSyncState() {
   }
 }
 
+/**
+ * Save log sync state to atris/.log_sync_state.json.
+ * @param {Object} state - Sync state object to save
+ */
 function saveLogSyncState(state) {
   const statePath = getLogSyncStatePath();
   fs.writeFileSync(statePath, JSON.stringify(state, null, 2));