atris 3.2.0 → 3.5.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atris",
-  "version": "3.2.0",
+  "version": "3.5.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));

package/utils/update-check.js

@@ -8,6 +8,10 @@ const CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 const ATRIS_DIR = path.join(os.homedir(), '.atris');
 const CACHE_FILE = path.join(ATRIS_DIR, '.update-check');
 
+/**
+ * Get the currently installed CLI version from package.json.
+ * @returns {string|null} Installed version string, or null on error
+ */
 function getInstalledVersion() {
   try {
     const packageJsonPath = path.join(__dirname, '..', 'package.json');
@@ -18,6 +22,10 @@ function getInstalledVersion() {
   }
 }
 
+/**
+ * Load cached update check data from ~/.atris/.update-check.
+ * @returns {{lastCheck: Date|null, latestVersion: string|null}} Cache data
+ */
 function getCacheData() {
   try {
     if (fs.existsSync(CACHE_FILE)) {
@@ -33,6 +41,10 @@ function getCacheData() {
   return { lastCheck: null, latestVersion: null };
 }
 
+/**
+ * Save update check result to ~/.atris/.update-check cache file.
+ * @param {string} latestVersion - The latest version from npm
+ */
 function saveCacheData(latestVersion) {
   try {
     // Ensure ~/.atris/ exists
@@ -49,6 +61,10 @@ function saveCacheData(latestVersion) {
   }
 }
 
+/**
+ * Fetch the latest version of atris from npm registry.
+ * @returns {Promise<string>} Latest version string
+ */
 function checkNpmVersion() {
   return new Promise((resolve, reject) => {
     const options = {