trucontext 0.3.0 → 0.4.0

package/README.md

@@ -168,6 +168,8 @@ Observe → Capture → Sleep → Wake → Query → Observe → ...
 | `relationship-types` | List all relationship types |
 | `schema show` | Show current app schema |
 | `schema generate` | AI-generate a schema from description |
+| `docs` | List all API documentation sections |
+| `docs show <slug>` | View a specific doc section (no auth required) |
 
 ## API
 

package/bin/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 
+import { readFileSync } from 'fs';
 import { program } from 'commander';
 import { loginCommand } from '../src/commands/login.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 import { logoutCommand } from '../src/commands/logout.js';
 import { whoamiCommand } from '../src/commands/whoami.js';
 import { appsCommand, useCommand } from '../src/commands/apps.js';
@@ -11,14 +14,15 @@ import { queryCommand } from '../src/commands/query.js';
 import { recallCommand } from '../src/commands/recall.js';
 import { contextsListCommand, contextsCreateCommand, contextsDeleteCommand } from '../src/commands/contexts.js';
 import { schemaShowCommand, schemaGenerateCommand, schemaSetAuthorshipCommand } from '../src/commands/schema.js';
-import { entitiesListCommand, entitiesGetCommand, entitiesCreateCommand, entitiesUpdateCommand, entitiesDeleteCommand } from '../src/commands/entities.js';
+import { entitiesListCommand, entitiesGetCommand, entitiesCreateCommand, entitiesUpdateCommand, entitiesDeleteCommand, entitiesEdgesCommand } from '../src/commands/entities.js';
 import { recipesListCommand, recipesGetCommand, recipesCreateCommand, recipesDeleteCommand } from '../src/commands/recipes.js';
 import { relationshipTypesListCommand } from '../src/commands/relationship-types.js';
+import { docsListCommand, docsShowCommand } from '../src/commands/docs.js';
 
 program
   .name('trucontext')
   .description('TruContext CLI — contextual memory for AI applications')
-  .version('0.2.1');
+  .version(pkg.version);
 
 // Auth
 program.command('login')
@@ -88,7 +92,9 @@ const entities = program.command('entities').description('Manage entities').acti
 entities.command('list')
   .description('List entities')
   .option('--type <type>', 'Filter by entity type')
-  .option('-l, --limit <n>', 'Max results')
+  .option('--context <id>', 'Filter by context')
+  .option('--scope <scope>', 'Filter by scope')
+  .option('-l, --limit <n>', 'Max results (default: 50)')
   .action(entitiesListCommand);
 entities.command('get <entityId>')
   .description('Get an entity')
@@ -99,6 +105,7 @@ entities.command('create')
   .requiredOption('--type <Type>', 'Entity type (PascalCase)')
   .option('--properties <json>', 'JSON properties object')
   .option('--recipe <recipeId>', 'Recipe ID')
+  .option('--heartbeat', 'Enable heartbeat')
   .option('--no-heartbeat', 'Disable heartbeat')
   .option('--confidence <n>', 'Confidence level (0.0-1.0)')
   .option('--temporal', 'Content can decay over time (default)')
@@ -114,10 +121,14 @@ entities.command('update <entityId>')
   .option('--confidence <n>', 'Confidence level (0.0-1.0)')
   .option('--temporal', 'Content can decay over time')
   .option('--no-temporal', 'Content is a permanent fact')
+  .option('-c, --context <entry>', 'Link to context (entity-id:RELATIONSHIP, repeatable)', (val, prev) => [...prev, val], [])
   .action(entitiesUpdateCommand);
 entities.command('delete <entityId>')
   .description('Delete an entity')
   .action(entitiesDeleteCommand);
+entities.command('edges <entityId>')
+  .description('List edges for an entity')
+  .action(entitiesEdgesCommand);
 
 // Recipes
 const recipes = program.command('recipes').description('Manage recipes').action(function() { this.help(); });
@@ -158,4 +169,9 @@ schema.command('set-authorship <model>')
   .description('Set authorship model (single_author, multi_author, anonymous)')
   .action(schemaSetAuthorshipCommand);
 
+// Docs (public — no auth required)
+const docs = program.command('docs').description('Browse API documentation').action(docsListCommand);
+docs.command('list').description('List all doc sections').action(docsListCommand);
+docs.command('show <slug>').description('Show a specific doc section').action(docsShowCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trucontext",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TruContext CLI — contextual memory for AI applications",
   "type": "module",
   "bin": {

package/src/client.js

@@ -75,3 +75,18 @@ export function dataPlane(method, path, body) {
 export function controlPlane(method, path, body) {
   return request(CONTROL_PLANE_URL, method, path, body);
 }
+
+export async function publicApi(method, path) {
+  const ac = new AbortController();
+  const timeout = setTimeout(() => ac.abort(), 15000);
+  try {
+    const res = await fetch(`${CONTROL_PLANE_URL}${path}`, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      signal: ac.signal,
+    });
+    return handleResponse(res);
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/commands/docs.js

@@ -0,0 +1,113 @@
+import chalk from 'chalk';
+import { publicApi } from '../client.js';
+
+export async function docsListCommand() {
+  try {
+    const res = await publicApi('GET', '/public/docs');
+    const sections = res.data?.sections || res.sections || [];
+
+    if (sections.length === 0) {
+      console.log(chalk.yellow('No documentation available.'));
+      return;
+    }
+
+    console.log(chalk.bold('TruContext Documentation\n'));
+    for (const section of sections) {
+      const slug = section.sectionId || section.layerId || section.slug || section.id;
+      console.log(`  ${chalk.cyan(slug.padEnd(28))} ${chalk.bold(section.title)}`);
+    }
+    console.log();
+    console.log(chalk.dim(`${sections.length} sections. Use: trucontext docs show <slug>`));
+  } catch (err) {
+    console.error(chalk.red(`Failed: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+export async function docsShowCommand(slug) {
+  try {
+    const res = await publicApi('GET', `/public/docs/${slug}`);
+    const doc = res.data || res;
+
+    if (!doc || !doc.title) {
+      console.error(chalk.red(`No doc found for slug: ${slug}`));
+      process.exit(1);
+    }
+
+    // Title
+    console.log(chalk.bold.underline(`\n${doc.title}\n`));
+
+    // Main content
+    if (doc.content) {
+      console.log(renderMarkdown(doc.content));
+      console.log();
+    }
+
+    // Callouts
+    for (const callout of (doc.callouts || [])) {
+      const icon = callout.variant === 'warning' ? '!' : 'i';
+      console.log(chalk.yellow(`  [${icon}] ${chalk.bold(callout.title)}`));
+      console.log(`  ${chalk.dim(callout.content.replace(/\n/g, '\n  '))}`);
+      console.log();
+    }
+
+    // Subsections
+    for (const sub of (doc.subsections || [])) {
+      if (sub.title) {
+        console.log(chalk.cyan.bold(`## ${sub.title}`));
+      }
+      if (sub.content) {
+        console.log(renderMarkdown(sub.content));
+        console.log();
+      }
+
+      // Steps
+      for (const step of (sub.steps || [])) {
+        console.log(`  ${chalk.green(step.number + '.')} ${renderMarkdown(step.content)}`);
+      }
+
+      // Endpoints
+      for (const ep of (sub.endpoints || [])) {
+        console.log(`  ${chalk.green(ep.method)} ${chalk.bold(ep.path)}`);
+        if (ep.description) console.log(`    ${chalk.dim(ep.description)}`);
+        if (ep.auth) console.log(`    ${chalk.dim(`Auth: ${ep.auth}`)}`);
+        if (ep.body) {
+          console.log(`    ${chalk.dim('Body:')} ${JSON.stringify(ep.body, null, 2).split('\n').join('\n    ')}`);
+        }
+        if (ep.response) {
+          console.log(`    ${chalk.dim('Response:')} ${JSON.stringify(ep.response, null, 2).split('\n').join('\n    ')}`);
+        }
+        console.log();
+      }
+
+      // Code blocks
+      for (const block of (sub.codeBlocks || [])) {
+        if (block.title) console.log(`  ${chalk.dim(block.title)}`);
+        console.log(chalk.green(`  ${block.code}`));
+        console.log();
+      }
+
+      // Items (relationship types, node types, etc.)
+      for (const item of (sub.items || [])) {
+        const label = item.type || item.name || item.recipeId || '';
+        const desc = item.description || '';
+        if (label) {
+          console.log(`  ${chalk.yellow(label.padEnd(24))} ${desc}`);
+        }
+      }
+
+      if (sub.steps?.length || sub.items?.length) console.log();
+    }
+  } catch (err) {
+    console.error(chalk.red(`Failed: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// Simple markdown-to-terminal renderer
+function renderMarkdown(text) {
+  return text
+    .replace(/\*\*(.+?)\*\*/g, (_, m) => chalk.bold(m))
+    .replace(/`(.+?)`/g, (_, m) => chalk.green(m))
+    .replace(/\[(.+?)\]\(.+?\)/g, (_, m) => chalk.underline(m));
+}

package/src/commands/entities.js

@@ -1,10 +1,47 @@
 import chalk from 'chalk';
 import { dataPlane } from '../client.js';
 
+// Fields stored on the node but not user-declared properties
+const SYSTEM_FIELDS = new Set([
+  'tenantId', 'entityId', 'provenance', 'scope', 'createdAt', 'updatedAt',
+  'lastReinforcedAt', 'confidence', 'temporal', 'heartbeat_enabled', 'recipe_id',
+]);
+
+function displayEntity(e) {
+  const props = e.properties || {};
+  const type = e.type || e.labels?.[0] || 'Unknown';
+  const entityId = e.entityId || props.entityId;
+  const confidence = e.confidence ?? props.confidence;
+  const temporal = e.temporal ?? props.temporal;
+  const recipeId = e.recipe_id ?? props.recipe_id;
+  const heartbeat = e.heartbeat_enabled ?? props.heartbeat_enabled;
+  const provenance = e.provenance ?? props.provenance;
+
+  console.log(`${chalk.bold(entityId)} ${chalk.dim(`[${type}]`)}`);
+  if (provenance) console.log(`  provenance: ${chalk.dim(provenance)}`);
+  if (recipeId) console.log(`  recipe: ${chalk.cyan(recipeId)}`);
+  if (confidence !== undefined) console.log(`  confidence: ${chalk.dim(confidence)}`);
+  if (temporal !== undefined) console.log(`  temporal: ${chalk.dim(temporal)}`);
+  if (heartbeat !== undefined) console.log(`  heartbeat: ${chalk.dim(heartbeat)}`);
+
+  // Show user-declared properties (exclude system fields)
+  const userProps = {};
+  for (const [k, v] of Object.entries(props)) {
+    if (!SYSTEM_FIELDS.has(k) && v !== null && v !== undefined) {
+      userProps[k] = v;
+    }
+  }
+  if (Object.keys(userProps).length > 0) {
+    console.log(`  properties: ${chalk.dim(JSON.stringify(userProps))}`);
+  }
+}
+
 export async function entitiesListCommand(options) {
   try {
     const params = new URLSearchParams();
     if (options.type) params.set('type', options.type);
+    if (options.context) params.set('context_id', options.context);
+    if (options.scope) params.set('scope', options.scope);
     if (options.limit) params.set('limit', options.limit);
     const qs = params.toString();
     const path = `/v1/entities${qs ? `?${qs}` : ''}`;
@@ -18,15 +55,9 @@ export async function entitiesListCommand(options) {
     }
 
     for (const e of entities) {
-      console.log(`${chalk.bold(e.entityId)} ${chalk.dim(`[${e.type}]`)}`);
-      if (e.recipe_id) console.log(`  recipe: ${chalk.dim(e.recipe_id)}`);
-      if (e.properties && Object.keys(e.properties).length > 0) {
-        console.log(`  properties: ${chalk.dim(JSON.stringify(e.properties))}`);
-      }
-      if (e.heartbeat_enabled !== undefined) console.log(`  heartbeat: ${chalk.dim(e.heartbeat_enabled)}`);
-      if (e.confidence !== undefined) console.log(`  confidence: ${chalk.dim(e.confidence)}`);
-      if (e.temporal !== undefined) console.log(`  temporal: ${chalk.dim(e.temporal)}`);
+      displayEntity(e);
     }
+    console.log(chalk.dim(`\n${entities.length} entities`));
   } catch (err) {
     console.error(chalk.red(`Failed: ${err.message}`));
     process.exit(1);
@@ -37,15 +68,22 @@ export async function entitiesGetCommand(entityId) {
   try {
     const res = await dataPlane('GET', `/v1/entities/${entityId}`);
     const e = res.data || res;
-
-    console.log(`${chalk.bold(e.entityId)} ${chalk.dim(`[${e.type}]`)}`);
-    if (e.recipe_id) console.log(`  recipe: ${chalk.dim(e.recipe_id)}`);
-    if (e.properties && Object.keys(e.properties).length > 0) {
-      console.log(`  properties: ${chalk.dim(JSON.stringify(e.properties))}`);
+    displayEntity(e);
+
+    // Show edges if available
+    try {
+      const edgeRes = await dataPlane('GET', `/v1/entities/${entityId}/edges`);
+      const edges = edgeRes.data?.edges || edgeRes.data || [];
+      if (edges.length > 0) {
+        console.log(chalk.dim(`\n  Edges (${edges.length}):`));
+        for (const edge of edges) {
+          const dir = edge.direction === 'outgoing' ? '→' : '←';
+          console.log(`    ${dir} ${chalk.cyan(edge.type)} ${chalk.dim(edge.targetEntityId || edge.targetLabel || edge.target || '')}`);
+        }
+      }
+    } catch {
+      // Edge listing may not be available — skip silently
     }
-    if (e.heartbeat_enabled !== undefined) console.log(`  heartbeat: ${chalk.dim(e.heartbeat_enabled)}`);
-    if (e.confidence !== undefined) console.log(`  confidence: ${chalk.dim(e.confidence)}`);
-    if (e.temporal !== undefined) console.log(`  temporal: ${chalk.dim(e.temporal)}`);
   } catch (err) {
     console.error(chalk.red(`Failed: ${err.message}`));
     process.exit(1);
@@ -122,6 +160,19 @@ export async function entitiesUpdateCommand(entityId, options) {
     if (options.confidence !== undefined) body.confidence = parseFloat(options.confidence);
     if (options.temporal !== undefined) body.temporal = options.temporal;
 
+    if (options.context?.length > 0) {
+      body.contexts = options.context.map(entry => {
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1) {
+          return { context_id: entry, relationship: 'ABOUT' };
+        }
+        return {
+          context_id: entry.slice(0, colonIdx),
+          relationship: entry.slice(colonIdx + 1),
+        };
+      });
+    }
+
     await dataPlane('PUT', `/v1/entities/${entityId}`, body);
     console.log(chalk.green(`Updated: ${entityId}`));
   } catch (err) {
@@ -139,3 +190,27 @@ export async function entitiesDeleteCommand(entityId) {
     process.exit(1);
   }
 }
+
+export async function entitiesEdgesCommand(entityId) {
+  try {
+    const res = await dataPlane('GET', `/v1/entities/${entityId}/edges`);
+    const edges = res.data?.edges || res.data || [];
+
+    if (edges.length === 0) {
+      console.log(chalk.yellow('No edges found.'));
+      return;
+    }
+
+    for (const edge of edges) {
+      const dir = edge.direction === 'outgoing' ? '→' : '←';
+      console.log(`  ${dir} ${chalk.cyan(edge.type)} ${chalk.dim(edge.targetEntityId || edge.targetLabel || '')}`);
+      if (edge.properties && Object.keys(edge.properties).length > 0) {
+        console.log(`    ${chalk.dim(JSON.stringify(edge.properties))}`);
+      }
+    }
+    console.log(chalk.dim(`\n${edges.length} edges`));
+  } catch (err) {
+    console.error(chalk.red(`Failed: ${err.message}`));
+    process.exit(1);
+  }
+}