infernoflow 0.4.2 → 0.5.0

package/README.md

@@ -25,16 +25,19 @@ npx infernoflow init
 ## Quick Start
 
 ```bash
-# In your project root:
+# 1. Scaffold in your project root:
 npx infernoflow init
 
-# See your contract health:
+# 2. See your contract health:
 infernoflow status
 
-# Validate everything:
+# 3. When you add a feature, let AI update the docs:
+infernoflow suggest "added email notifications and user profiles"
+
+# 4. Validate everything:
 infernoflow check
 
-# In CI / pre-push hook:
+# 5. In CI / pre-push hook:
 infernoflow doc-gate
 ```
 
@@ -44,48 +47,61 @@ infernoflow doc-gate
 |---|---|
 | `infernoflow init` | Interactive scaffold — creates `inferno/` in your project |
 | `infernoflow status` | At-a-glance health of your contract |
+| `infernoflow suggest` | Generate an AI prompt, apply capability updates |
 | `infernoflow check` | Full validation: contract, capabilities, scenarios, changelog |
 | `infernoflow doc-gate` | Fails if code changed but docs weren't updated |
 
 ### Options
 
 ```bash
-infernoflow init --force    # overwrite existing files
-infernoflow init --yes      # skip prompts, use defaults
-infernoflow check --json    # machine-readable output for CI
+infernoflow init --force       # overwrite existing files
+infernoflow init --yes         # skip prompts, use defaults
+infernoflow suggest "..."      # describe what changed
+infernoflow check --json       # machine-readable output for CI
 infernoflow check --skip-doc-gate
 ```
 
-## Example: Todo App
+## `infernoflow suggest` — AI-powered updates
 
-After `infernoflow init` in a React Todo project:
+When you add a feature, just describe it in plain language. infernoflow generates a prompt you can paste into **any AI** (Claude, ChatGPT, Copilot, Cursor, etc.), then applies the suggested changes automatically.
 
+```bash
+infernoflow suggest "added payment processing and invoice generation"
 ```
-inferno/
-├── contract.json
-│   {
-│     "policyId": "todo-app",
-│     "policyVersion": 1,
-│     "capabilities": ["CreateTask", "ReadTasks", "UpdateTask", "ToggleComplete", "DeleteTask"]
-│   }
-├── capabilities.json
-│   { capabilities: [{ id: "CreateTask", title: "Create a task", since: "0.1.0" }, ...] }
-├── scenarios/
-│   └── happy_path.json   ← covers all 5 capabilities
-└── CHANGELOG.md
+
+**What happens:**
+1. infernoflow reads your current contract state
+2. Generates a structured prompt with full context
+3. You paste it into your AI of choice
+4. Paste the JSON response back
+5. infernoflow previews the changes and asks for confirmation
+6. On approval — updates `contract.json`, `capabilities.json`, `scenarios/`, and `CHANGELOG.md`
+
+**Example output:**
 ```
+Proposed Changes
 
-Then in CI:
+  Summary: Added payment processing and invoice generation functionality.
 
-```yaml
-- run: npm run inferno:check
+  + New capabilities:
+      ProcessPayment — Process Payment
+      GenerateInvoice — Generate Invoice
+
+  ~ Scenario updates:
+      [update] happy_path.json
+
+  📝 Changelog: - Add payment processing and invoice generation capabilities.
+
+  Apply these changes? (y/n)
 ```
 
+Works with any AI — Claude, ChatGPT, GitHub Copilot, Cursor, or your own setup.
+
 ## Why infernoflow?
 
 **The problem:** AI-assisted development moves fast. Code changes daily. But what does the system *actually do*? What changed? What's covered?
 
-**The metaphor:** A forge (כיבשן). Metal becomes liquid — flexible, shapeable. The forge is the controlled environment where that change happens safely, with molds (contracts) and tempering (tests).
+**The metaphor:** A forge (כיבשן). Metal becomes liquid — flexible, shapeable. The forge is the controlled environment where that change happens safely, with molds (contracts) and tempering (validation).
 
 **The principle:** Liquid where you want flexibility. Solid where you need safety.
 

package/bin/infernoflow.mjs

@@ -1,60 +1,50 @@
 #!/usr/bin/env node
+import { bold, gray, cyan, red } from "../lib/ui/output.mjs";
 
-import { parseArgs } from "node:util";
-import { bold, gray, cyan, red, orange } from "../lib/ui/output.mjs";
-
-const VERSION = "0.1.0";
+const VERSION = "0.5.0";
 
 const HELP = `
   ${bold("🔥 infernoflow")} ${gray("v" + VERSION)}
-  ${gray("The forge for liquid code")}
+  ${gray("The forge for liquid code — keep every AI session in sync")}
 
   ${bold("Usage:")}
     infernoflow <command> [options]
 
   ${bold("Commands:")}
-    init          Scaffold inferno/ in your project (interactive)
+    init          Scaffold inferno/ in your project
     check         Validate contract, capabilities, scenarios, changelog
     status        Show contract health at a glance
     doc-gate      Fail if code changed but docs were not updated
-
-  ${bold("Options:")}
-    init:
-      --force, -f     Overwrite existing files
-      --yes, -y       Skip prompts, use defaults
-
-    check:
-      --skip-doc-gate   Skip the git doc-gate check
-      --json            Machine-readable JSON output (for CI)
-
-  ${bold("Examples:")}
-    ${cyan("npx infernoflow init")}
-    ${cyan("infernoflow status")}
-    ${cyan("infernoflow check")}
-    ${cyan("infernoflow check --json")}
-    ${cyan("infernoflow doc-gate")}
-
-  ${bold("CI example:")}
-    ${gray("# In GitHub Actions:")}
-    ${gray("- run: npx infernoflow check --json")}
-    ${gray("  env:")}
-    ${gray("    BASE_SHA: ${{ github.event.pull_request.base.sha }}")}
-    ${gray("    HEAD_SHA: ${{ github.event.pull_request.head.sha }}")}
+    suggest       Generate AI prompt + apply capability updates
+    context       Generate AI-ready context for new sessions
+
+  ${bold("context options:")}
+    --intent  "..."     What you plan to build next
+    --working "..."     What you are building right now
+    --decision "..."    Record a decision or note
+    --show              Print context without writing file
+    --reset             Clear all stored state
+
+  ${bold("Typical workflow:")}
+    ${gray('1. infernoflow context --intent "what I want to build"')}
+    ${gray("2. [paste inferno/CONTEXT.md into Claude / Cursor / Copilot]")}
+    ${gray("3. [build the feature]")}
+    ${gray('4. infernoflow suggest "what I built"')}
+    ${gray("5. infernoflow check")}
 `;
 
-const [,, cmd, ...rest] = process.argv;
+const [, , cmd, ...rest] = process.argv;
 
 if (!cmd || cmd === "--help" || cmd === "-h") {
   console.log(HELP);
   process.exit(0);
 }
-
 if (cmd === "--version" || cmd === "-v") {
   console.log(VERSION);
   process.exit(0);
 }
 
-const commands = ["init", "check", "status", "doc-gate"];
+const commands = ["init", "check", "status", "doc-gate", "suggest", "context"];
 
 if (!commands.includes(cmd)) {
   console.error(red(`\nUnknown command: ${cmd}`));
@@ -67,22 +57,50 @@ const args = [cmd, ...rest];
 switch (cmd) {
   case "init":
     import("../lib/commands/init.mjs")
-      .then(m => m.initCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+      .then((m) => m.initCommand(args))
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
     break;
   case "check":
     import("../lib/commands/check.mjs")
-      .then(m => m.checkCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+      .then((m) => m.checkCommand(args))
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
     break;
   case "status":
     import("../lib/commands/status.mjs")
-      .then(m => m.statusCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+      .then((m) => m.statusCommand(args))
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
+    break;
+  case "suggest":
+    import("../lib/commands/suggest.mjs")
+      .then((m) => m.suggestCommand(args))
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
+    break;
+  case "context":
+    import("../lib/commands/context.mjs")
+      .then((m) => m.contextCommand(args))
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
     break;
   case "doc-gate":
     import("../lib/commands/docGate.mjs")
-      .then(m => m.docGateCommand())
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
+      .then((m) => m.docGateCommand())
+      .catch((err) => {
+        console.error(red("\nError: ") + err.message);
+        process.exit(1);
+      });
     break;
 }

package/lib/commands/context.mjs

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import path from "node:path";
+import { bold, gray, cyan, red, green, yellow } from "../ui/output.mjs";
+
+const INFERNO_DIR = "inferno";
+const CONTEXT_FILE = path.join(INFERNO_DIR, "CONTEXT.md");
+const STATE_FILE = path.join(INFERNO_DIR, "context-state.json");
+
+function readJSON(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch { return null; }
+}
+
+function readFile(filePath) {
+  try { return fs.readFileSync(filePath, "utf8"); }
+  catch { return null; }
+}
+
+function parseRecentChangelog(changelogContent, maxEntries = 3) {
+  if (!changelogContent) return [];
+  const lines = changelogContent.split("\n");
+  const entries = [];
+  let current = null;
+
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      if (current && entries.length < maxEntries) entries.push(current);
+      if (entries.length >= maxEntries) break;
+      current = { title: line.replace("## ", "").trim(), items: [] };
+    } else if (current && line.startsWith("- ")) {
+      current.items.push(line.replace("- ", "").trim());
+    }
+  }
+  if (current && entries.length < maxEntries) entries.push(current);
+  return entries.filter(e => e.items.length > 0);
+}
+
+function loadState() {
+  const raw = readFile(STATE_FILE);
+  if (!raw) return {};
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+function saveState(state) {
+  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), "utf8");
+}
+
+function formatDate(iso) {
+  if (!iso) return "unknown";
+  return new Date(iso).toLocaleDateString("en-GB", {
+    day: "2-digit", month: "short", year: "numeric"
+  });
+}
+
+export async function contextCommand(args) {
+  const getFlagValue = (f) => {
+    const i = args.indexOf(f);
+    return i !== -1 && args[i + 1] ? args[i + 1] : null;
+  };
+  const hasFlag = (f) => args.includes(f);
+
+  const intent   = getFlagValue("--intent")   || getFlagValue("-i");
+  const working  = getFlagValue("--working")  || getFlagValue("-w");
+  const decision = getFlagValue("--decision") || getFlagValue("-d");
+  const showOnly = hasFlag("--show") || hasFlag("-s");
+  const resetState = hasFlag("--reset");
+
+  console.log(`\n  ${bold("🔥 infernoflow — context")}`);
+  console.log(`  ${"─".repeat(50)}\n`);
+
+  if (!fs.existsSync(INFERNO_DIR)) {
+    console.error(red("  ✘ inferno/ not found"));
+    console.error(gray("  → Run: infernoflow init\n"));
+    process.exit(1);
+  }
+
+  const contract     = readJSON(path.join(INFERNO_DIR, "contract.json"));
+  const capabilities = readJSON(path.join(INFERNO_DIR, "capabilities.json"));
+  const changelog    = readFile(path.join(INFERNO_DIR, "CHANGELOG.md"));
+
+  if (!contract || !capabilities) {
+    console.error(red("  ✘ Missing contract.json or capabilities.json"));
+    process.exit(1);
+  }
+
+  let state = loadState();
+  if (resetState) { state = {}; console.log(yellow("  ⚠ State reset\n")); }
+
+  if (intent)   { state.intent = intent; state.intentUpdated = new Date().toISOString(); console.log(green(`  ✔ Intent saved: "${intent}"`)); }
+  if (working)  { state.working = working; state.workingUpdated = new Date().toISOString(); console.log(green(`  ✔ Working on: "${working}"`)); }
+  if (decision) {
+    if (!state.decisions) state.decisions = [];
+    state.decisions.push({ text: decision, date: new Date().toISOString() });
+    console.log(green(`  ✔ Decision recorded: "${decision}"`));
+  }
+  if (intent || working || decision) saveState(state);
+
+  const capList      = capabilities.capabilities || [];
+  const contractCaps = contract.capabilities || [];
+  const allInSync    = capList.length === contractCaps.length;
+  const recentChanges = parseRecentChangelog(changelog, 3);
+
+  const now = new Date().toLocaleDateString("en-GB", {
+    day: "2-digit", month: "short", year: "numeric"
+  });
+
+  const capLines = capList.map(c => `- **${c.id}** — ${c.title}`).join("\n");
+
+  const changelogLines = recentChanges.length > 0
+    ? recentChanges.map(e => `### ${e.title}\n${e.items.map(i => `  - ${i}`).join("\n")}`).join("\n\n")
+    : "_No recent changes recorded_";
+
+  const intentLine  = state.intent
+    ? `${state.intent}  _(updated: ${formatDate(state.intentUpdated)})_`
+    : "_Not set — run: `infernoflow context --intent \"what I want to do next\"`_";
+
+  const workingLine = state.working
+    ? `${state.working}  _(updated: ${formatDate(state.workingUpdated)})_`
+    : "_Not set — run: `infernoflow context --working \"what I am building now\"`_";
+
+  const decisionsLines = state.decisions?.length > 0
+    ? state.decisions.slice(-5).map(d => `- ${d.text}  _(${formatDate(d.date)})_`).join("\n")
+    : "_No decisions recorded — run: `infernoflow context --decision \"why I chose X\"`_";
+
+  const syncBadge = allInSync ? "✓ validated" : "⚠ out of sync — run infernoflow check";
+  const version   = String(contract.policyVersion).replace(/^v/i, "");
+
+  const contextMd = `# Project Context — ${contract.policyId} v${version}
+> Generated by infernoflow | ${now} | ${syncBadge}
+
+---
+
+## What this system does
+
+${capLines}
+
+---
+
+## Recent changes
+
+${changelogLines}
+
+---
+
+## Current state
+
+- **Capabilities declared:** ${capList.length}
+- **Contract version:** v${version}
+- **Sync status:** ${syncBadge}
+
+---
+
+## What I am working on right now
+
+${workingLine}
+
+---
+
+## Intent — what I want to build next
+
+${intentLine}
+
+---
+
+## Decisions & notes
+
+${decisionsLines}
+
+---
+_Paste this block at the start of any new AI session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infernoflow",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "The forge for liquid code — keep capabilities, contracts, and docs in sync.",
   "type": "module",
   "bin": {

package/lib/infernoflow.mjs

@@ -1,94 +0,0 @@
-#!/usr/bin/env node
-
-import { parseArgs } from "node:util";
-import { bold, gray, cyan, red, orange } from "../lib/ui/output.mjs";
-
-const VERSION = "0.1.0";
-
-const HELP = `
-  ${bold("🔥 infernoflow")} ${gray("v" + VERSION)}
-  ${gray("The forge for liquid code")}
-
-  ${bold("Usage:")}
-    infernoflow <command> [options]
-
-  ${bold("Commands:")}
-    init          Scaffold inferno/ in your project (interactive)
-    check         Validate contract, capabilities, scenarios, changelog
-    status        Show contract health at a glance
-    doc-gate      Fail if code changed but docs were not updated
-    suggest       Generate AI prompt + apply capability updates
-
-  ${bold("Options:")}
-    init:
-      --force, -f     Overwrite existing files
-      --yes, -y       Skip prompts, use defaults
-
-    check:
-      --skip-doc-gate   Skip the git doc-gate check
-      --json            Machine-readable JSON output (for CI)
-
-  ${bold("Examples:")}
-    ${cyan("npx infernoflow init")}
-    ${cyan("infernoflow status")}
-    ${cyan("infernoflow check")}
-    ${cyan("infernoflow check --json")}
-    ${cyan("infernoflow doc-gate")}
-
-  ${bold("CI example:")}
-    ${gray("# In GitHub Actions:")}
-    ${gray("- run: npx infernoflow check --json")}
-    ${gray("  env:")}
-    ${gray("    BASE_SHA: ${{ github.event.pull_request.base.sha }}")}
-    ${gray("    HEAD_SHA: ${{ github.event.pull_request.head.sha }}")}
-`;
-
-const [,, cmd, ...rest] = process.argv;
-
-if (!cmd || cmd === "--help" || cmd === "-h") {
-  console.log(HELP);
-  process.exit(0);
-}
-
-if (cmd === "--version" || cmd === "-v") {
-  console.log(VERSION);
-  process.exit(0);
-}
-
-const commands = ["init", "check", "status", "doc-gate", "suggest"];
-
-if (!commands.includes(cmd)) {
-  console.error(red(`\nUnknown command: ${cmd}`));
-  console.error(gray("Run: infernoflow --help\n"));
-  process.exit(1);
-}
-
-const args = [cmd, ...rest];
-
-switch (cmd) {
-  case "init":
-    import("../lib/commands/init.mjs")
-      .then(m => m.initCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
-    break;
-  case "check":
-    import("../lib/commands/check.mjs")
-      .then(m => m.checkCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
-    break;
-  case "status":
-    import("../lib/commands/status.mjs")
-      .then(m => m.statusCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
-    break;
-  case "suggest":
-    import("../lib/commands/suggest.mjs")
-      .then(m => m.suggestCommand(args))
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
-    break;
-  case "doc-gate":
-    import("../lib/commands/docGate.mjs")
-      .then(m => m.docGateCommand())
-      .catch(err => { console.error(red("\nError: ") + err.message); process.exit(1); });
-    break;
-}