trucontext 0.5.0 → 0.6.0

package/bin/cli.js

@@ -18,6 +18,7 @@ import { entitiesListCommand, entitiesGetCommand, entitiesCreateCommand, entitie
 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';
+import { registerRootsCommand } from '../src/commands/roots.js';
 
 program
   .name('trucontext')
@@ -65,7 +66,8 @@ program.command('ingest <source>')
 // Query
 program.command('query <question>')
   .description('Query the knowledge graph')
-  .option('-c, --context <id>', 'Scope to a context')
+  .option('-r, --root <id>', 'Root node ID (or use: trucontext roots use <id>)')
+  .option('-c, --context <id>', 'Further scope within the root ego network')
   .option('-m, --mode <mode>', 'Query mode: answer (default) or context', 'answer')
   .option('-l, --limit <n>', 'Max results', '20')
   .action(queryCommand);
@@ -73,7 +75,8 @@ program.command('query <question>')
 // Recall
 program.command('recall <query>')
   .description('Semantic memory recall')
-  .option('-c, --context <id>', 'Scope to a context')
+  .option('-r, --root <id>', 'Root node ID (or use: trucontext roots use <id>)')
+  .option('-c, --context <id>', 'Further scope within the root ego network')
   .option('-l, --limit <n>', 'Max seed results', '10')
   .option('-d, --depth <n>', 'Graph expansion depth', '2')
   .action(recallCommand);
@@ -130,6 +133,9 @@ entities.command('edges <entityId>')
   .description('List edges for an entity')
   .action(entitiesEdgesCommand);
 
+// Root Nodes
+registerRootsCommand(program);
+
 // Recipes
 const recipes = program.command('recipes').description('Manage recipes').action(function() { this.help(); });
 recipes.command('list')
@@ -139,10 +145,11 @@ recipes.command('get <recipeId>')
   .description('Get recipe details')
   .action(recipesGetCommand);
 recipes.command('create')
-  .description('Create a recipe')
-  .requiredOption('--id <recipeId>', 'Recipe ID')
-  .requiredOption('--name <name>', 'Recipe name')
-  .requiredOption('--purpose <text>', 'Recipe purpose')
+  .description('Create a custom recipe. --id and --name are always required. Provide the interpretation via --file (JSON) or inline flags.')
+  .requiredOption('--id <recipeId>', 'Recipe ID (e.g., my-health-score)')
+  .requiredOption('--name <name>', 'Recipe display name')
+  .option('--file <path>', 'JSON file containing the interpretation block (the WHY)')
+  .option('--purpose <text>', 'Recipe purpose (inline alternative to --file)')
   .option('--decay-profile <text>', 'Decay profile description')
   .option('--confidence-bias <text>', 'Confidence bias description')
   .action(recipesCreateCommand);

package/package.json

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

package/src/commands/ingest.js

@@ -32,20 +32,24 @@ export async function ingestCommand(source, options) {
     if (options.confidence !== undefined) body.confidence = parseFloat(options.confidence);
     if (options.temporal !== undefined) body.temporal = options.temporal;
 
-    // Build contexts array from --context flags: "entity-id:RELATIONSHIP"
-    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),
-        };
-      });
+    // Build contexts array from --context flags: "entity-id:RELATIONSHIP" (required)
+    if (!options.context || options.context.length === 0) {
+      console.error(chalk.red('At least one context is required.'));
+      console.error(chalk.dim('Use: --context entity-id:RELATIONSHIP (e.g., --context dustin:ABOUT)'));
+      process.exit(1);
     }
 
+    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),
+      };
+    });
+
     const res = await dataPlane('POST', '/v1/ingest', body);
     console.log(chalk.green('Accepted'));
     console.log(chalk.dim(`Content ID: ${res.contentId}`));

package/src/commands/init.js

@@ -71,8 +71,62 @@ export async function initCommand(name, options) {
       console.log(chalk.cyan('  trucontext schema generate -d "your description"'));
     }
 
-    console.log(chalk.dim(`\nReady to go:`));
-    console.log(chalk.cyan('  trucontext ingest <file>'));
+    // Step 7: Create first root node
+    console.log(chalk.bold('\nCreate Your First Root Node'));
+    console.log(chalk.dim('Root nodes are the intelligence boundaries of your graph.\n'));
+
+    const rootId = await input({ message: 'Root node ID (e.g., my-agent, dustin):' });
+    const rootType = await select({
+      message: 'Root node type:',
+      choices: [
+        { name: 'Person', value: 'Person' },
+        { name: 'Agent', value: 'Agent' },
+        { name: 'Organization', value: 'Organization' },
+        { name: 'Business', value: 'Business' },
+        { name: 'Product', value: 'Product' },
+        { name: 'Project', value: 'Project' },
+      ],
+    });
+
+    const rootRecipe = await select({
+      message: 'Recipe (how should the system think about this node\'s data?):',
+      choices: [
+        { name: 'Personal Assistant Memory', value: 'recipe:personal-assistant-memory' },
+        { name: 'Meeting Memory', value: 'recipe:meeting-memory' },
+        { name: 'Customer Voice', value: 'recipe:customer-voice' },
+        { name: 'Competitive Intelligence', value: 'recipe:competitive-intelligence' },
+        { name: 'AI Agent Self-Reflection', value: 'recipe:ai-agent-self-reflection' },
+        { name: 'Organizational Context', value: 'recipe:organizational-context' },
+        { name: 'Decision Archive', value: 'recipe:decision-archive' },
+        { name: 'Curiosity Loop', value: 'recipe:curiosity-loop' },
+      ],
+    });
+
+    const rootName = await input({ message: 'Display name (e.g., Dustin Henderson):' });
+
+    try {
+      await controlPlane('POST', '/roots', {
+        entityId: rootId,
+        type: rootType,
+        recipe_id: rootRecipe,
+        dreamers: 'all',
+        properties: rootName ? { name: rootName } : {},
+      });
+
+      const { saveConfig, getConfig } = await import('../config.js');
+      const config = getConfig();
+      config.activeRoot = rootId;
+      saveConfig(config);
+
+      console.log(chalk.green(`Root node created: ${rootId}`));
+      console.log(chalk.green(`Active root set: ${rootId}\n`));
+    } catch (rootErr) {
+      console.error(chalk.yellow(`Root creation failed: ${rootErr.response?.data?.error || rootErr.message}`));
+      console.log(chalk.dim('You can create one later: trucontext roots create --id <id> --type <type> --recipe <recipe>\n'));
+    }
+
+    console.log(chalk.dim('Ready to go:'));
+    console.log(chalk.cyan('  trucontext ingest "content" --context ' + rootId + ':ABOUT'));
     console.log(chalk.cyan('  trucontext query "your question"'));
   } catch (err) {
     console.error(chalk.red(`Failed: ${err.message}`));

package/src/commands/query.js

@@ -1,10 +1,19 @@
 import chalk from 'chalk';
 import { dataPlane } from '../client.js';
+import { getConfig } from '../config.js';
 
 export async function queryCommand(question, options) {
   try {
+    // root_id is required — from --root flag or active root
+    const rootId = options.root || getConfig().activeRoot;
+    if (!rootId) {
+      console.error(chalk.red('Root node required. Use --root <id> or set active root: trucontext roots use <id>'));
+      process.exit(1);
+    }
+
     const body = {
       mode: options.mode === 'context' ? 'CONTEXT' : 'ANSWER',
+      root_id: rootId,
       max_results: options.limit ? parseInt(options.limit, 10) : 20,
     };
 

package/src/commands/recall.js

@@ -1,10 +1,19 @@
 import chalk from 'chalk';
 import { dataPlane } from '../client.js';
+import { getConfig } from '../config.js';
 
 export async function recallCommand(query, options) {
   try {
+    // root_id is required — from --root flag or active root
+    const rootId = options.root || getConfig().activeRoot;
+    if (!rootId) {
+      console.error(chalk.red('Root node required. Use --root <id> or set active root: trucontext roots use <id>'));
+      process.exit(1);
+    }
+
     const body = {
       query,
+      root_id: rootId,
       maxResults: options.limit ? parseInt(options.limit, 10) : 10,
       expansionDepth: options.depth ? parseInt(options.depth, 10) : 2,
     };

package/src/commands/recipes.js

@@ -1,3 +1,4 @@
+import { readFileSync } from 'fs';
 import chalk from 'chalk';
 import { controlPlane } from '../client.js';
 import { getActiveApp } from '../config.js';
@@ -107,19 +108,35 @@ export async function recipesCreateCommand(options) {
       console.error(chalk.red('--name is required'));
       process.exit(1);
     }
-    if (!options.purpose) {
-      console.error(chalk.red('--purpose is required'));
-      process.exit(1);
-    }
 
     const body = {
       recipeId: options.id,
       name: options.name,
-      purpose: options.purpose,
     };
 
-    if (options.decayProfile) body.decay_profile = options.decayProfile;
-    if (options.confidenceBias) body.confidence_bias = options.confidenceBias;
+    // --file provides the full interpretation block as JSON
+    if (options.file) {
+      try {
+        const raw = readFileSync(options.file, 'utf8');
+        body.interpretation = JSON.parse(raw);
+        if (!body.interpretation.purpose) {
+          console.error(chalk.red('File must contain a "purpose" field'));
+          process.exit(1);
+        }
+      } catch (e) {
+        console.error(chalk.red(`Failed to read --file: ${e.message}`));
+        process.exit(1);
+      }
+    } else {
+      // Inline flags → build interpretation object
+      if (!options.purpose) {
+        console.error(chalk.red('--purpose is required (or use --file to provide the full interpretation)'));
+        process.exit(1);
+      }
+      body.interpretation = { purpose: options.purpose };
+      if (options.decayProfile) body.interpretation.decay_profile = options.decayProfile;
+      if (options.confidenceBias) body.interpretation.confidence_bias = options.confidenceBias;
+    }
 
     const res = await controlPlane('POST', `/apps/${appId}/recipes`, body);
     const r = res.data || res;

package/src/commands/roots.js

@@ -0,0 +1,195 @@
+// roots.js — Root Node commands
+//
+// Root nodes are the intelligence boundaries of the graph. They define ego networks,
+// carry recipes, and control which dreams run. Queries require a root_id.
+
+import chalk from 'chalk';
+import { controlPlane } from '../client.js';
+import { getConfig, saveConfig } from '../config.js';
+
+export function registerRootsCommand(program) {
+  const roots = program
+    .command('roots')
+    .description('Manage root nodes — intelligence boundaries of the graph')
+    .action(function() { this.help(); });
+
+  // CREATE
+  roots
+    .command('create')
+    .description('Create a root node')
+    .requiredOption('--id <entityId>', 'Unique identifier for the root node')
+    .requiredOption('--type <type>', 'Node type (e.g., Person, Agent, Organization)')
+    .requiredOption('--recipe <recipeId>', 'Recipe ID (e.g., recipe:personal-assistant-memory)')
+    .option('--dreamers <list>', 'Dreamers: "all" or comma-separated (e.g., decay,curiosity)', 'all')
+    .option('--hop-depth <n>', 'Max traversal depth for ego network (default: unlimited)', parseInt)
+    .option('--do-not-follow', 'Mark as structural root — do not traverse into from other roots')
+    .option('--properties <json>', 'JSON properties object')
+    .option('-c, --context <entry>', 'Link to other roots: entity-id:RELATIONSHIP (repeatable)', (val, prev) => [...prev, val], [])
+    .action(async (opts) => {
+      try {
+        const body = {
+          entityId: opts.id,
+          type: opts.type,
+          recipe_id: opts.recipe,
+          dreamers: opts.dreamers === 'all' ? 'all' : opts.dreamers.split(',').map(s => s.trim()),
+          hop_depth: opts.hopDepth || null,
+          do_not_follow: opts.doNotFollow || false,
+        };
+
+        if (opts.properties) {
+          try { body.properties = JSON.parse(opts.properties); } catch {
+            console.error(chalk.red('Error: --properties must be valid JSON'));
+            process.exit(1);
+          }
+        }
+
+        if (opts.context && opts.context.length > 0) {
+          body.contexts = opts.context.map(c => {
+            const [id, rel] = c.split(':');
+            if (!id || !rel) {
+              console.error(chalk.red(`Error: Invalid context format "${c}". Use entity-id:RELATIONSHIP`));
+              process.exit(1);
+            }
+            return { context_id: id, relationship: rel };
+          });
+        }
+
+        const res = await controlPlane('POST', '/roots', body);
+        const r = res.data;
+        console.log(chalk.green(`Root node created: ${r.entityId}`));
+        console.log(`  Type: ${r.type}`);
+        console.log(`  Recipe: ${r.recipe_id}`);
+        console.log(`  Dreamers: ${Array.isArray(r.dreamers) ? r.dreamers.join(', ') : r.dreamers}`);
+        console.log(`  Hop depth: ${r.hop_depth || 'unlimited'}`);
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.response?.data?.details || err.message);
+        process.exit(1);
+      }
+    });
+
+  // LIST
+  roots
+    .command('list')
+    .description('List all root nodes for the active app')
+    .action(async () => {
+      try {
+        const res = await controlPlane('GET', '/roots');
+        const rootNodes = res.data?.roots || [];
+        if (rootNodes.length === 0) {
+          console.log('No root nodes. Create one with: trucontext roots create');
+          return;
+        }
+
+        const config = getConfig();
+        for (const r of rootNodes) {
+          const active = config.activeRoot === r.entityId ? chalk.cyan(' (active)') : '';
+          const dreamers = Array.isArray(r.dreamers) ? r.dreamers.join(', ') : r.dreamers;
+          console.log(`${chalk.bold(r.properties?.name || r.entityId)}${active}`);
+          console.log(`  ${r.entityId} — ${r.type} — recipe: ${r.recipe_id || 'none'} — dreamers: ${dreamers}`);
+        }
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // SHOW
+  roots
+    .command('show <rootId>')
+    .description('Show details of a root node')
+    .action(async (rootId) => {
+      try {
+        const res = await controlPlane('GET', `/roots/${rootId}`);
+        const r = res.data;
+        console.log(chalk.bold(`Root: ${r.entityId}`));
+        console.log(`  Type: ${r.type}`);
+        console.log(`  Recipe: ${r.recipe_id || 'none'}`);
+        console.log(`  Dreamers: ${Array.isArray(r.dreamers) ? r.dreamers.join(', ') : r.dreamers}`);
+        console.log(`  Hop depth: ${r.hop_depth || 'unlimited'}`);
+        console.log(`  Do not follow: ${r.do_not_follow}`);
+
+        if (r.linkedRoots && r.linkedRoots.length > 0) {
+          console.log(`  Linked roots:`);
+          for (const lr of r.linkedRoots) {
+            console.log(`    → ${lr.entityId} (${lr.type}) via ${lr.relationship}`);
+          }
+        }
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // UPDATE
+  roots
+    .command('update <rootId>')
+    .description('Update a root node')
+    .option('--recipe <recipeId>', 'New recipe ID')
+    .option('--dreamers <list>', 'New dreamers: "all" or comma-separated')
+    .option('--hop-depth <n>', 'New hop depth', parseInt)
+    .option('--do-not-follow', 'Set do-not-follow flag')
+    .option('--no-do-not-follow', 'Clear do-not-follow flag')
+    .option('--properties <json>', 'JSON properties to update')
+    .action(async (rootId, opts) => {
+      try {
+        const body = {};
+        if (opts.recipe) body.recipe_id = opts.recipe;
+        if (opts.dreamers) body.dreamers = opts.dreamers === 'all' ? 'all' : opts.dreamers.split(',').map(s => s.trim());
+        if (opts.hopDepth !== undefined) body.hop_depth = opts.hopDepth;
+        if (opts.doNotFollow !== undefined) body.do_not_follow = opts.doNotFollow;
+        if (opts.properties) {
+          try { body.properties = JSON.parse(opts.properties); } catch {
+            console.error(chalk.red('Error: --properties must be valid JSON'));
+            process.exit(1);
+          }
+        }
+
+        await controlPlane('PUT', `/roots/${rootId}`, body);
+        console.log(chalk.green(`Updated: ${rootId}`));
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // DELETE (demote)
+  roots
+    .command('delete <rootId>')
+    .description('Demote a root node to a regular entity (does not delete the node)')
+    .action(async (rootId) => {
+      try {
+        await controlPlane('DELETE', `/roots/${rootId}`);
+        console.log(chalk.green(`Demoted: ${rootId} (no longer a root node)`));
+
+        const config = getConfig();
+        if (config.activeRoot === rootId) {
+          config.activeRoot = undefined;
+          saveConfig(config);
+        }
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // USE — set active root for queries
+  roots
+    .command('use <rootId>')
+    .description('Set the active root node for queries and recall')
+    .action(async (rootId) => {
+      try {
+        await controlPlane('GET', `/roots/${rootId}`);
+        const config = getConfig();
+        config.activeRoot = rootId;
+        saveConfig(config);
+        console.log(chalk.green(`Active root: ${rootId}`));
+      } catch (err) {
+        if (err.response?.status === 404) {
+          console.error(chalk.red(`Root node '${rootId}' not found. Run: trucontext roots list`));
+        } else {
+          console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        }
+        process.exit(1);
+      }
+    });
+}