@hassangameryt/freeflow 0.7.0 → 0.7.2

package/hooks/adapters/copilot-session-start.mjs

@@ -0,0 +1,13 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      additionalContext,
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/cursor-session-start.mjs

@@ -0,0 +1,13 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["sessionStart", "SessionStart"],
+    getWorkspaceCwd: (input) => input.workspace_roots?.[0] || input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      additional_context: additionalContext,
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/gemini-session-start.mjs

@@ -0,0 +1,15 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      hookSpecificOutput: {
+        additionalContext,
+      },
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/claude/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Load Freeflow core runtime context in Claude Code.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart",
+            "timeout": 5,
+            "statusMessage": "Loading Freeflow context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/codex/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Load Freeflow core runtime context in Codex.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/adapters/codex-session-start.mjs\" SessionStart",
+            "timeout": 5,
+            "statusMessage": "Loading Freeflow context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/cursor/hooks.json

@@ -0,0 +1,9 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node hooks/adapters/cursor-session-start.mjs SessionStart"
+      }
+    ]
+  }
+}

package/hooks/freeflow-runtime-context.mjs

@@ -1,218 +1,6 @@
 #!/usr/bin/env node
 
-import fs from "node:fs";
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
+import { main } from "./adapters/codex-session-start.mjs";
+import { runSafely } from "./shared/runtime-context.mjs";
 
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "..");
-
-function readStdinJson() {
-  const raw = fs.readFileSync(0, "utf8").trim();
-  if (!raw) return { input: {}, raw: "" };
-
-  try {
-    return { input: JSON.parse(raw), raw };
-  } catch {
-    return { input: {}, raw };
-  }
-}
-
-function readText(filePath) {
-  try {
-    const text = fs.readFileSync(filePath, "utf8").trim();
-    return text || null;
-  } catch {
-    return null;
-  }
-}
-
-function findWorkspaceRoot(cwd) {
-  let current = path.resolve(cwd || process.cwd());
-
-  while (true) {
-    if (fs.existsSync(path.join(current, ".git"))) return current;
-
-    const parent = path.dirname(current);
-    if (parent === current) return path.resolve(cwd || process.cwd());
-    current = parent;
-  }
-}
-
-function loadRuntimeContext() {
-  const corePrompt = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "core.md"));
-  const interactionContract = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "interaction-contract.md"));
-
-  if (!corePrompt || !interactionContract) {
-    throw new Error("Freeflow core runtime prompt files are missing.");
-  }
-
-  return { corePrompt, interactionContract };
-}
-
-function readConfig(root) {
-  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
-  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
-  const localValid = !local.exists || local.valid;
-  const configured = repository.valid && localValid;
-  const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
-  const enabled = configured && core.config.enabled;
-
-  return {
-    exists: repository.exists,
-    valid: configured,
-    configured,
-    repositoryValid: repository.valid,
-    localExists: local.exists,
-    localValid,
-    error: repository.valid ? local.error : repository.error,
-    enabled,
-    contextVirtualizationEnabled: enabled && core.config.contextVirtualization,
-    conversationHistoryEnabled: enabled && core.config.conversationHistory,
-  };
-}
-
-function readConfigLayer(filePath, validate) {
-  if (!fs.existsSync(filePath)) {
-    return { path: filePath, exists: false, valid: false, parsed: {}, error: null };
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    const error = validate(parsed);
-    return {
-      path: filePath,
-      exists: true,
-      valid: error === null,
-      parsed: error === null ? parsed : {},
-      error,
-    };
-  } catch (error) {
-    return {
-      path: filePath,
-      exists: true,
-      valid: false,
-      parsed: {},
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function validateCoreConfigFields(value) {
-  if (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
-    return "enabled must be a boolean";
-  }
-  if (Object.hasOwn(value, "contextVirtualization") && typeof value.contextVirtualization !== "boolean") {
-    return "contextVirtualization must be a boolean";
-  }
-  if (Object.hasOwn(value, "conversationHistory") && typeof value.conversationHistory !== "boolean") {
-    return "conversationHistory must be a boolean";
-  }
-  return null;
-}
-
-function isValidSetupConfig(value) {
-  if (!isRecord(value)) return "repository config must be a JSON object";
-
-  const allowedKeys = new Set([
-    "enabled",
-    "contextVirtualization",
-    "conversationHistory",
-    "outputRouter",
-    "observedRouting",
-    "scriptTransform",
-    "cognitiveRouting",
-  ]);
-  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return "repository config contains unsupported top-level keys";
-  }
-
-  const coreError = validateCoreConfigFields(value);
-  if (coreError) return coreError;
-
-  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
-    if (Object.hasOwn(value, key) && !isRecord(value[key])) return `${key} must be an object`;
-  }
-  return null;
-}
-
-function isValidLocalConfig(value) {
-  if (!isRecord(value)) return "local config must be a JSON object";
-
-  const allowedKeys = new Set([
-    "enabled",
-    "processing",
-    "cognitiveRouting",
-    "contextVirtualization",
-    "conversationHistory",
-  ]);
-  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return "local config contains unsupported top-level keys";
-  }
-  return validateCoreConfigFields(value);
-}
-
-function resolveLayeredValue(repository, local, key, fallback) {
-  if (Object.hasOwn(local, key)) return local[key];
-  if (Object.hasOwn(repository, key)) return repository[key];
-  return fallback;
-}
-
-function resolveCoreConfig(repository, local) {
-  return {
-    config: {
-      enabled: resolveLayeredValue(repository, local, "enabled", true),
-      contextVirtualization: resolveLayeredValue(repository, local, "contextVirtualization", false),
-      conversationHistory: resolveLayeredValue(repository, local, "conversationHistory", false),
-    },
-  };
-}
-
-function runtimeStateContext() {
-  return ["# Freeflow Runtime State", "", "Freeflow: active"].join("\n");
-}
-
-function renderSessionStart(config) {
-  if (!config.valid || !config.enabled) return "";
-
-  const { corePrompt, interactionContract } = loadRuntimeContext();
-  return [corePrompt.trim(), interactionContract.trim(), runtimeStateContext()].filter(Boolean).join("\n\n");
-}
-
-function shouldHandle(eventName) {
-  if (process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") return false;
-  return eventName === "SessionStart";
-}
-
-function emitAdditionalContext(eventName, additionalContext) {
-  process.stdout.write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: eventName,
-        additionalContext,
-      },
-    })}\n`,
-  );
-}
-
-function main() {
-  const { input, raw } = readStdinJson();
-  const eventName = process.argv[2] || input.hook_event_name || "";
-
-  if ((!raw && !eventName) || !shouldHandle(eventName)) return;
-
-  const root = findWorkspaceRoot(input.cwd || process.cwd());
-  const additionalContext = renderSessionStart(readConfig(root));
-  if (additionalContext.trim()) emitAdditionalContext(eventName, additionalContext);
-}
-
-try {
-  main();
-} catch (error) {
-  process.stderr.write(`Freeflow runtime context hook skipped: ${error.message}\n`);
-}
+runSafely(main);

package/hooks/hooks.json

@@ -1,15 +1,14 @@
 {
-  "description": "Load Freeflow core runtime context.",
+  "description": "Load Freeflow core runtime context in Gemini CLI.",
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT}}/hooks/freeflow-runtime-context.mjs\" SessionStart",
-            "timeout": 5,
-            "statusMessage": "Loading Freeflow context"
+            "name": "freeflow-runtime-context",
+            "command": "node \"${extensionPath}/hooks/adapters/gemini-session-start.mjs\" SessionStart",
+            "timeout": 5000
           }
         ]
       }

package/hooks/shared/runtime-context.mjs

@@ -0,0 +1,210 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "../..");
+
+export function readHookInput() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) return { input: {}, raw: "" };
+
+  try {
+    return { input: JSON.parse(raw), raw };
+  } catch {
+    return { input: {}, raw };
+  }
+}
+
+function readText(filePath) {
+  try {
+    const text = fs.readFileSync(filePath, "utf8").trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+export function findWorkspaceRoot(cwd) {
+  let current = path.resolve(cwd || process.cwd());
+
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(cwd || process.cwd());
+    current = parent;
+  }
+}
+
+function readConfigLayer(filePath, validate) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, valid: false, parsed: {}, error: null };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const error = validate(parsed);
+    return {
+      exists: true,
+      valid: error === null,
+      parsed: error === null ? parsed : {},
+      error,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      valid: false,
+      parsed: {},
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateCoreConfigFields(value) {
+  if (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
+    return "enabled must be a boolean";
+  }
+  if (Object.hasOwn(value, "contextVirtualization") && typeof value.contextVirtualization !== "boolean") {
+    return "contextVirtualization must be a boolean";
+  }
+  if (Object.hasOwn(value, "conversationHistory") && typeof value.conversationHistory !== "boolean") {
+    return "conversationHistory must be a boolean";
+  }
+  return null;
+}
+
+function isValidSetupConfig(value) {
+  if (!isRecord(value)) return "repository config must be a JSON object";
+
+  const allowedKeys = new Set([
+    "enabled",
+    "contextVirtualization",
+    "conversationHistory",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+    "cognitiveRouting",
+  ]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "repository config contains unsupported top-level keys";
+  }
+
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (Object.hasOwn(value, key) && !isRecord(value[key])) return `${key} must be an object`;
+  }
+  return null;
+}
+
+function isValidLocalConfig(value) {
+  if (!isRecord(value)) return "local config must be a JSON object";
+
+  const allowedKeys = new Set([
+    "enabled",
+    "processing",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
+  ]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "local config contains unsupported top-level keys";
+  }
+  return validateCoreConfigFields(value);
+}
+
+function resolveLayeredValue(repository, local, key, fallback) {
+  if (Object.hasOwn(local, key)) return local[key];
+  if (Object.hasOwn(repository, key)) return repository[key];
+  return fallback;
+}
+
+function resolveCoreConfig(repository, local) {
+  return {
+    enabled: resolveLayeredValue(repository, local, "enabled", true),
+    contextVirtualization: resolveLayeredValue(repository, local, "contextVirtualization", false),
+    conversationHistory: resolveLayeredValue(repository, local, "conversationHistory", false),
+  };
+}
+
+export function readConfig(root) {
+  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
+  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
+  const localValid = !local.exists || local.valid;
+  const configured = repository.valid && localValid;
+  const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
+  const enabled = configured && core.enabled;
+
+  return {
+    exists: repository.exists,
+    valid: configured,
+    configured,
+    repositoryValid: repository.valid,
+    localExists: local.exists,
+    localValid,
+    error: repository.valid ? local.error : repository.error,
+    enabled,
+    contextVirtualizationEnabled: enabled && core.contextVirtualization,
+    conversationHistoryEnabled: enabled && core.conversationHistory,
+  };
+}
+
+function loadRuntimeContext() {
+  const corePrompt = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "core.md"));
+  const interactionContract = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "interaction-contract.md"));
+
+  if (!corePrompt || !interactionContract) {
+    throw new Error("Freeflow core runtime prompt files are missing.");
+  }
+
+  return { corePrompt, interactionContract };
+}
+
+function runtimeStateContext() {
+  return ["# Freeflow Runtime State", "", "Freeflow: active"].join("\n");
+}
+
+export function renderRuntimeContext(root) {
+  const config = readConfig(root);
+  if (!config.valid || !config.enabled) return "";
+
+  const { corePrompt, interactionContract } = loadRuntimeContext();
+  return [corePrompt, interactionContract, runtimeStateContext()].filter(Boolean).join("\n\n");
+}
+
+export function emitHookOutput(output) {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+export function runSessionStartAdapter({ eventNames, getWorkspaceCwd, formatOutput }) {
+  const { input, raw } = readHookInput();
+  const eventName = process.argv[2] || input.hook_event_name || "";
+  if ((!raw && !eventName) || process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") return;
+  if (!eventNames.includes(eventName)) return;
+
+  const root = findWorkspaceRoot(getWorkspaceCwd(input));
+  const additionalContext = renderRuntimeContext(root);
+  if (additionalContext.trim()) {
+    emitHookOutput(formatOutput({ eventName, input, additionalContext }));
+  }
+}
+
+export function runSafely(run) {
+  try {
+    run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Freeflow runtime context hook skipped: ${message}\n`);
+  }
+}
+
+export function isMainModule(metaUrl) {
+  return process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === metaUrl;
+}

package/hooks/tests/check-host-adapters.test.mjs

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const repoRoot = resolve(import.meta.dirname, "../..");
+const adapters = {
+  legacy: ["hooks/freeflow-runtime-context.mjs", "hookSpecificOutput.additionalContext"],
+  claude: ["hooks/adapters/claude-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  codex: ["hooks/adapters/codex-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  gemini: ["hooks/adapters/gemini-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  copilot: ["hooks/adapters/copilot-session-start.mjs", "additionalContext"],
+  cursor: ["hooks/adapters/cursor-session-start.mjs", "additional_context"],
+};
+
+function createWorkspace(config = "{}\n") {
+  const root = mkdtempSync(join(tmpdir(), "freeflow-host-adapter-"));
+  mkdirSync(join(root, ".freeflow"), { recursive: true });
+  writeFileSync(join(root, ".freeflow", "config.json"), config, "utf8");
+  return root;
+}
+
+function runAdapter(relativePath, workspace, input, event = "SessionStart") {
+  const result = spawnSync(process.execPath, [join(repoRoot, relativePath), event], {
+    cwd: repoRoot,
+    input: `${JSON.stringify(input)}\n`,
+    encoding: "utf8",
+  });
+  assert.equal(result.status, 0, `${relativePath} stderr: ${result.stderr}`);
+  assert.equal(result.stderr, "", `${relativePath} should not log on the happy path`);
+  return result.stdout.trim() ? JSON.parse(result.stdout) : undefined;
+}
+
+test("host adapters share rendered mandatory context but emit host-native envelopes", () => {
+  const workspace = createWorkspace();
+  const outputs = {};
+  for (const [host, [relativePath]] of Object.entries(adapters)) {
+    const input =
+      host === "cursor"
+        ? { hook_event_name: "sessionStart", workspace_roots: [workspace] }
+        : { hook_event_name: "SessionStart", cwd: workspace };
+    outputs[host] = runAdapter(relativePath, workspace, input, host === "cursor" ? "sessionStart" : "SessionStart");
+    assert.ok(outputs[host], `${host} should emit context`);
+  }
+
+  const legacyContext = outputs.legacy.hookSpecificOutput.additionalContext;
+  for (const host of ["claude", "codex", "gemini"]) {
+    assert.equal(outputs[host].hookSpecificOutput.additionalContext, legacyContext);
+  }
+  assert.deepEqual(Object.keys(outputs.copilot).sort(), ["additionalContext"]);
+  assert.equal(outputs.copilot.additionalContext, legacyContext);
+  assert.equal(outputs.copilot.hookSpecificOutput, undefined);
+  assert.equal(outputs.cursor.additional_context, legacyContext);
+  assert.equal(outputs.cursor.hookSpecificOutput, undefined);
+  assert.match(legacyContext, /# Freeflow Stable Guidance/);
+  assert.match(legacyContext, /# Freeflow Interaction Contract/);
+  assert.match(legacyContext, /Freeflow: active/);
+  assert.doesNotMatch(legacyContext, /Cognitive Routing/);
+});
+
+test("host adapters stay inert for disabled, invalid, and unsupported lifecycle inputs", () => {
+  const disabledWorkspace = createWorkspace('{"enabled":false}\n');
+  const invalidWorkspace = createWorkspace('{"enabled":"no"}\n');
+  for (const [host, [relativePath]] of Object.entries(adapters)) {
+    const input =
+      host === "cursor"
+        ? { hook_event_name: "sessionStart", workspace_roots: [disabledWorkspace] }
+        : { hook_event_name: "SessionStart", cwd: disabledWorkspace };
+    assert.equal(
+      runAdapter(relativePath, disabledWorkspace, input, host === "cursor" ? "sessionStart" : "SessionStart"),
+      undefined,
+    );
+    const invalidInput = { ...input, cwd: invalidWorkspace, workspace_roots: [invalidWorkspace] };
+    assert.equal(
+      runAdapter(relativePath, invalidWorkspace, invalidInput, host === "cursor" ? "sessionStart" : "SessionStart"),
+      undefined,
+    );
+    assert.equal(runAdapter(relativePath, disabledWorkspace, input, "UserPromptSubmit"), undefined);
+  }
+});