hyperstack-core 1.5.0 → 1.5.2

package/README.md

@@ -223,6 +223,12 @@ await hs.store({
 ## CLI
 
 ```bash
+# Ingest a README into cards + edges (no manual card creation)
+npx hyperstack-core ingest ./README.md
+npx hyperstack-core ingest ./docs/                    # whole directory
+cat DECISIONS.md | npx hyperstack-core ingest --source decisions  # stdin pipe
+npx hyperstack-core ingest ./README.md --dry          # preview without storing
+
 # Store a card
 npx hyperstack-core store --slug "use-clerk" --title "Use Clerk" --type decision
 
@@ -232,9 +238,12 @@ npx hyperstack-core decide --slug "use-clerk" --title "Use Clerk" --rationale "B
 # Check blockers
 npx hyperstack-core blockers deploy-prod
 
-# Traverse graph
+# Traverse graph — forward (what this card points to)
 npx hyperstack-core graph auth-api --depth 2
 
+# Traverse graph — reverse (what points at this card)
+npx hyperstack-core graph auth-api --depth 2 --reverse
+
 # Search
 npx hyperstack-core search "authentication setup"
 

package/cli.js

@@ -37,13 +37,14 @@ hyperstack-core — Typed graph memory for AI agents
 Commands:
   login               Authenticate via browser (OAuth device flow)
   logout              Remove saved credentials
+  quickstart          Scan current dir, ingest docs, show graph — 90 seconds to value
   init <template>     Initialize a project with a template
   ingest <path>       Auto-parse files into cards + edges (markdown/text/logs)
   search <query>      Search the knowledge graph
   store               Store a card (use --slug, --title, --body, --type, --links)
   decide              Record a decision (use --slug, --title, --rationale)
   blockers <slug>     Show what blocks a card
-  graph <slug>        Traverse graph from a card
+  graph <slug>        Traverse graph from a card (--reverse for inbound edges)
   list                List all cards
 
 Templates:
@@ -387,6 +388,116 @@ async function run() {
     return;
   }
 
+  // ─── Quickstart command ─────────────────────────────
+
+  if (command === "quickstart") {
+    console.log("\n🧠 HyperStack Quickstart\n");
+
+    // 1. Auth check
+    const qsApiKey = getApiKey();
+    if (!qsApiKey) {
+      console.log("  Not authenticated.\n");
+      console.log("  Option A: npx hyperstack-core login");
+      console.log("  Option B: export HYPERSTACK_API_KEY=hs_your_key");
+      console.log("  Get a free key: https://cascadeai.dev/hyperstack\n");
+      process.exit(1);
+    }
+    console.log("  ✅ Authenticated\n");
+
+    // 2. Scan current directory for ingestable files
+    const cwd = process.cwd();
+    const scanDirs = [cwd];
+    const docsDir = join(cwd, "docs");
+    if (existsSync(docsDir) && statSync(docsDir).isDirectory()) scanDirs.push(docsDir);
+
+    const found = [];
+    for (const dir of scanDirs) {
+      const entries = readdirSync(dir).filter((f) => /\.(md|txt)$/i.test(f));
+      for (const f of entries) {
+        const full = join(dir, f);
+        const stat = statSync(full);
+        const rel = dir === cwd ? f : `docs/${f}`;
+        found.push({ path: full, name: rel, size: stat.size });
+      }
+    }
+
+    if (!found.length) {
+      console.log("  No .md or .txt files found in current directory.\n");
+      console.log("  Try: npx hyperstack-core ingest <file>");
+      process.exit(0);
+    }
+
+    console.log("  Found files:\n");
+    for (const f of found) {
+      const kb = (f.size / 1024).toFixed(1);
+      console.log(`    📄 ${f.name} (${kb} KB)`);
+    }
+
+    const workspace = getFlag("workspace", "default");
+    console.log(`\n  Workspace: ${workspace}`);
+    console.log(`  Files: ${found.length}\n`);
+
+    // 3. Confirm (skip with --yes)
+    if (!args.includes("--yes") && !args.includes("-y")) {
+      const { createInterface } = await import("readline");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise((res) => {
+        rl.question("  Ingest these files? [Y/n] ", (a) => { rl.close(); res(a.trim().toLowerCase()); });
+      });
+      if (answer === "n" || answer === "no") {
+        console.log("\n  Cancelled.\n");
+        return;
+      }
+    }
+
+    // 4. Parse all files
+    console.log("\n  Parsing...\n");
+    let allCards = [];
+    let totalEdges = 0;
+
+    for (const f of found) {
+      const content = readFileSync(f.path, "utf-8");
+      const prefix = slugify(f.name.replace(/\.[^.]+$/, ""));
+      const result = parse(content, { prefix });
+      allCards.push(...result.cards);
+      totalEdges += result.edgeCount;
+      console.log(`    📄 ${f.name} → ${result.cards.length} cards, ${result.edgeCount} edges (${result.format})`);
+    }
+
+    if (!allCards.length) {
+      console.log("\n  No cards extracted. Files may be empty.\n");
+      return;
+    }
+
+    // 5. Store
+    console.log(`\n  Storing ${allCards.length} cards...`);
+    const qsClient = new HyperStackClient({ apiKey: qsApiKey, workspace });
+
+    const result = await qsClient.ingest(allCards, {
+      onProgress: () => process.stdout.write("."),
+    });
+
+    console.log("\n");
+    if (result.failed) {
+      console.log(`  ✅ ${result.stored} cards stored, ${result.failed} failed`);
+      for (const e of result.errors) console.log(`    ❌ [${e.slug}] ${e.error}`);
+    } else {
+      console.log(`  ✅ ${result.stored} cards stored, ${totalEdges} edges from ${found.length} file(s)`);
+    }
+
+    // 6. Next steps
+    const firstSlug = allCards[0]?.slug || "";
+    const searchTerm = allCards[0]?.title?.split(" ").slice(0, 3).join(" ") || "getting started";
+    console.log(`
+  Next steps:
+
+    npx hyperstack-core search "${searchTerm}"
+    npx hyperstack-core graph ${firstSlug} --depth 2 --reverse
+    npx hyperstack-core list
+`);
+    return;
+  }
+
   // ─── Ingest command ─────────────────────────────────
 
   if (command === "ingest") {
@@ -592,12 +703,15 @@ async function run() {
   if (command === "graph") {
     const from = args[1];
     if (!from) { console.error("Usage: hyperstack-core graph <slug>"); process.exit(1); }
+    const reverse = args.includes("--reverse");
     try {
       const result = await client.graph(from, {
         depth: parseInt(getFlag("depth", "2")),
         relation: getFlag("relation") || undefined,
+        mode: reverse ? "impact" : undefined,
       });
-      console.log(`Graph from [${from}]: ${result.nodes?.length || 0} nodes, ${result.edges?.length || 0} edges\n`);
+      const direction = reverse ? "pointing at" : "from";
+      console.log(`Graph ${direction} [${from}]: ${result.nodes?.length || 0} nodes, ${result.edges?.length || 0} edges\n`);
       for (const n of result.nodes || []) {
         console.log(`  [${n.slug}] ${n.title || "?"} (${n.cardType || "?"})`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperstack-core",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Typed graph memory for AI agents. Replace GOALS.md with queryable cards + relations. Works with OpenClaw, Claude Desktop, Cursor.",
   "type": "module",
   "main": "index.js",

package/src/client.js

@@ -165,6 +165,7 @@ class HyperStackClient {
    * @param {number} [opts.depth=1] — hops to traverse (1-3)
    * @param {string} [opts.relation] — filter by relation type
    * @param {string} [opts.type] — filter by card type
+   * @param {string} [opts.mode] — "impact" for reverse traversal, "replay" for decision replay
    * @param {string} [opts.at] — ISO timestamp for time-travel
    * @returns {Promise<{nodes: Array, edges: Array}>}
    */
@@ -173,6 +174,7 @@ class HyperStackClient {
     if (opts.depth) url += `&depth=${opts.depth}`;
     if (opts.relation) url += `&relation=${opts.relation}`;
     if (opts.type) url += `&type=${opts.type}`;
+    if (opts.mode) url += `&mode=${opts.mode}`;
     if (opts.at) url += `&at=${encodeURIComponent(opts.at)}`;
     return this._request("GET", url);
   }