rippletide-package 0.1.0

package/tide/src/hook.js

@@ -0,0 +1,71 @@
+// Codex PreToolUse hook — where Tide sits between the agent and the user.
+// Rule-driven: loads the compiled bundle and evaluates each shell command through the
+// deterministic engine. Codex passes JSON on stdin:
+//   {"cwd":"...","tool_name":"Bash","tool_input":{"command":"..."}}
+// Output contract (Codex 0.142): print {"decision":"block","reason":...} to block, else {}.
+// Every firing is appended to <project>/.runtime/events.jsonl so it's easy to see.
+
+import fs from "node:fs";
+import path from "node:path";
+import { Engine } from "./engine.js";
+import { loadBundle } from "./schema.js";
+
+function projectDir() {
+  return process.env.TIDE_PROJECT || path.join(process.cwd(), ".tide");
+}
+
+function logEvent(dir, event) {
+  try {
+    const runtime = path.join(dir, ".runtime");
+    fs.mkdirSync(runtime, { recursive: true });
+    fs.appendFileSync(path.join(runtime, "events.jsonl"), JSON.stringify(event) + "\n");
+  } catch { /* never block on logging */ }
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export function decideCommand(dir, toolName, command) {
+  const bundle = loadBundle(dir);
+  const engine = new Engine(bundle);
+  const action = "shell" in bundle.actions ? "shell" : (toolName || "shell");
+  return engine.decide(action, { command }, {}, []);
+}
+
+export async function main() {
+  let payload;
+  try { payload = JSON.parse(await readStdin()); } catch { process.stdout.write("{}"); return; }
+
+  const toolName = String(payload.tool_name ?? "");
+  const command = String(payload.tool_input?.command ?? "");
+  const dir = projectDir();
+
+  let verdict, reason, ruleIds;
+  try {
+    const d = decideCommand(dir, toolName, command);
+    verdict = d.verdict;
+    reason = d.reasons.join("; ") || "blocked by Tide policy";
+    ruleIds = d.fired.map((f) => f.id);
+  } catch (e) {
+    logEvent(dir, { ts: Date.now(), decision: "error", tool: toolName, command: command.slice(0, 200), error: String(e.message || e) });
+    process.stdout.write("{}"); // fail open, but recorded
+    return;
+  }
+
+  logEvent(dir, { ts: Date.now(), decision: verdict, tool: toolName, command: command.slice(0, 200),
+    rules: ruleIds, reason: verdict === "allow" ? "" : reason });
+
+  if (verdict === "deny") {
+    process.stdout.write(JSON.stringify({ decision: "block", reason: `Tide blocked this: ${reason}` }));
+  } else if (verdict === "escalate") {
+    process.stdout.write(JSON.stringify({ decision: "block",
+      reason: `Tide: this needs human approval (${reason}). Ask the user before proceeding.` }));
+  } else {
+    process.stdout.write("{}");
+  }
+}
+
+main();

package/tide/src/ontology.js

@@ -0,0 +1,28 @@
+// Tool manifests per agent — the action vocabulary rules are written against.
+//
+// Codex's PreToolUse hook fires for the shell/command tool; its payload is
+// {tool_name:"Bash", tool_input:{command}, cwd}. So the single governed action is the
+// shell command — the primary risky surface (file writes, deletes, network, secret reads
+// all happen as shell commands). Codex ALSO edits files through this action via
+// apply_patch, whose body carries markers like "*** Add File:". We tell the LLM both.
+
+export const CODEX_ACTIONS = {
+  shell: {
+    description:
+      "Runs a shell command in the user's workspace (Codex's command/Bash tool). This is " +
+      "the action Codex's PreToolUse hook gates before execution. Everything the agent does " +
+      "on the machine — reading/writing/deleting files, network calls, running programs — " +
+      "happens through this command string. IMPORTANT: Codex also EDITS FILES through this " +
+      "same action via apply_patch; those calls arrive as a patch body containing markers " +
+      "like '*** Begin Patch', '*** Add File:', '*** Update File:', '*** Delete File:', " +
+      "'*** Move to:'. Any policy about creating/editing/deleting files MUST match BOTH " +
+      "ordinary shell write commands (rm, mv, cp, touch, mkdir, tee, sed -i, output " +
+      "redirection with > or >>, chmod, editors) AND these apply_patch markers.",
+    params: { command: "string — the full shell command line or apply_patch body about to run" },
+  },
+};
+
+export function actionsFor(agent) {
+  if (agent === "codex") return structuredClone(CODEX_ACTIONS);
+  throw new Error(`no tool manifest for agent '${agent}' yet (Codex only in v1)`);
+}

package/tide/src/schema.js

@@ -0,0 +1,87 @@
+// Read/write a Tide policy project — the tide-test schema, on disk (YAML via js-yaml).
+//
+//   <project>/
+//     tide.yaml                     name, version
+//     ontology/actions.yaml         {actions: {name: {description, params}}}
+//     policies/rules.policy.yaml    [ {id, action, when|requires, verdict, mode, reason, to} ]
+//     tests/golden.scenarios.yaml   [ {name, session, action, params, context, expect, expect_rules} ]
+//     findings.md                   human-review summary
+
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+export const DEFAULT_DIR = ".tide";
+
+function readYaml(file, fallback) {
+  try { return yaml.load(fs.readFileSync(file, "utf8")) ?? fallback; } catch { return fallback; }
+}
+
+function dump(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, yaml.dump(data, { lineWidth: 100, noRefs: true }));
+}
+
+export function loadBundle(projectDir) {
+  const meta = readYaml(path.join(projectDir, "tide.yaml"), {}) || {};
+  const ont = readYaml(path.join(projectDir, "ontology", "actions.yaml"), {}) || {};
+  const actions = (ont && typeof ont === "object" && ont.actions) ? ont.actions : {};
+  const rules = readYaml(path.join(projectDir, "policies", "rules.policy.yaml"), []) || [];
+  return {
+    name: meta.name || path.basename(path.resolve(projectDir)),
+    version: String(meta.version || "1"),
+    actions,
+    rules: rules.map(normalizeRule),
+  };
+}
+
+function normalizeRule(r) {
+  return {
+    id: String(r.id ?? ""),
+    action: String(r.action ?? ""),
+    verdict: r.verdict ?? "deny",
+    mode: r.mode ?? "enforce",
+    when: r.when ?? null,
+    requires: r.requires ?? null,
+    reason: r.reason ?? null,
+    to: r.to ?? null,
+  };
+}
+
+export function loadScenarios(projectDir) {
+  const raw = readYaml(path.join(projectDir, "tests", "golden.scenarios.yaml"), []) || [];
+  return raw.map((s) => ({
+    name: String(s.name ?? "scenario"),
+    action: String(s.action ?? ""),
+    params: s.params ?? {},
+    context: s.context ?? {},
+    expect: String(s.expect ?? "allow"),
+    expect_rules: s.expect_rules ?? [],
+    session: s.session ?? [],
+  }));
+}
+
+function ruleToYaml(r) {
+  const out = { id: r.id, action: r.action };
+  if (r.when) out.when = r.when;
+  if (r.requires && r.requires.length) out.requires = r.requires;
+  out.verdict = r.verdict;
+  out.mode = r.mode;
+  if (r.reason) out.reason = r.reason;
+  if (r.to) out.to = r.to;
+  return out;
+}
+
+export function writeBundle(projectDir, bundle, scenarios, findings = "") {
+  dump(path.join(projectDir, "tide.yaml"), { name: bundle.name, version: bundle.version });
+  dump(path.join(projectDir, "ontology", "actions.yaml"), { actions: bundle.actions });
+  dump(path.join(projectDir, "policies", "rules.policy.yaml"), bundle.rules.map(ruleToYaml));
+  dump(path.join(projectDir, "tests", "golden.scenarios.yaml"), scenarios.map((s) => ({
+    name: s.name, session: s.session, action: s.action, params: s.params,
+    context: s.context, expect: s.expect, expect_rules: s.expect_rules,
+  })));
+  if (findings) {
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(path.join(projectDir, "findings.md"), findings);
+  }
+}