@useshifu/coding-harness 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# Shifu coding-harness connector
+
+`@useshifu/coding-harness` connects Codex, Claude Code, or OpenCode to Shifu through reviewed, incremental summaries. It never uploads raw transcripts or syncs in the background.
+
+```sh
+npx @useshifu/coding-harness install --harness codex
+npx @useshifu/coding-harness connect --harness codex
+npx @useshifu/coding-harness schedule --harness codex --after-turns 12 --after-hours 4
+npx @useshifu/coding-harness activate --harness codex
+```
+
+Replace `codex` with `claude_code` or `opencode` as needed. `connect`, `schedule`, `activate`, and `sync` each ask for confirmation. Activation writes only local harness configuration; it can mark a segment as due but cannot upload it. A due reminder appears when the harness next becomes active.
+
+To submit a reviewed segment, pipe the exact payload to `sync`. The CLI prints it, asks again, and only then sends it to Shifu. Successful responses advance a local checkpoint; the server rejects out-of-order or changed retries.
+
+```sh
+printf '%s' '{"harness":"codex","sessionRef":"opaque-session-id","fromTurn":1,"toTurn":8,"summary":"Implemented a focused change and checked the result.","evidence":["Focused tests passed."],"decisions":[],"redactionVersion":1}' | npx @useshifu/coding-harness sync --harness codex
+```
+
+The default API URL is `https://api.useshifu.com`. Override it during local or self-hosted use with `--api-url` on `connect`, or `SHIFU_API_URL`.

package/bin/shifu-harness.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+
+const DEFAULT_API_URL = "https://api.useshifu.com";
+const HARNESS_NAMES = {
+  codex: "Codex",
+  claude_code: "Claude Code",
+  opencode: "OpenCode",
+};
+const TOKEN_PATTERN = /^cs_sk_[a-f0-9]{16}_[a-f0-9]{64}$/;
+const SENSITIVE_PATTERNS = ["-----begin", "api_key", "authorization", "password=", "sk-", "ghp_", "@", "://", "`", "/"];
+
+function configRoot() {
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "shifu", "coding-harness");
+}
+
+function configPath(harness) {
+  return path.join(configRoot(), `${harness}.json`);
+}
+
+function statePath(harness) {
+  return path.join(configRoot(), `${harness}-checkpoints.json`);
+}
+
+function installedRunnerPath() {
+  return path.join(configRoot(), "runner.js");
+}
+
+function requireHarness(value) {
+  if (!Object.hasOwn(HARNESS_NAMES, value)) throw new Error("Choose --harness codex, claude_code, or opencode.");
+  return value;
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+function hasFlag(name) {
+  return process.argv.includes(name);
+}
+
+function readJSON(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error && error.code === "ENOENT") return fallback;
+    throw new Error(`Could not read ${file}.`);
+  }
+}
+
+function writeJSON(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, file);
+  fs.chmodSync(file, 0o600);
+}
+
+function readConfig(harness) {
+  const config = readJSON(configPath(harness), undefined);
+  if (!config || typeof config.token !== "string" || typeof config.apiUrl !== "string") {
+    throw new Error(`No ${HARNESS_NAMES[harness]} connection is configured. Run connect first.`);
+  }
+  return config;
+}
+
+function readState(harness) {
+  return readJSON(statePath(harness), { sessions: {} });
+}
+
+function saveState(harness, state) {
+  writeJSON(statePath(harness), state);
+}
+
+function prompt() {
+  return readline.createInterface({ input: process.stdin, output: process.stderr });
+}
+
+async function confirm(question) {
+  const terminal = prompt();
+  const answer = (await terminal.question(`${question} [y/N] `)).trim().toLowerCase();
+  terminal.close();
+  return answer === "y" || answer === "yes";
+}
+
+function copyRunner() {
+  fs.mkdirSync(configRoot(), { recursive: true, mode: 0o700 });
+  fs.copyFileSync(__filename, installedRunnerPath());
+  fs.chmodSync(installedRunnerPath(), 0o700);
+}
+
+function copyDirectory(source, destination) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+  fs.cpSync(source, destination, { recursive: true, force: true });
+}
+
+function shellCommand(harness, event) {
+  return `\"${process.execPath}\" \"${installedRunnerPath()}\" hook --harness ${harness} --event ${event}`;
+}
+
+function addHook(config, event, command, timeout) {
+  config.hooks ||= {};
+  config.hooks[event] ||= [];
+  const present = config.hooks[event].some((group) => group && Array.isArray(group.hooks) && group.hooks.some((hook) => hook.command === command));
+  if (!present) config.hooks[event].push({ hooks: [{ type: "command", command, timeout }] });
+}
+
+function enableCodex(harness) {
+  const file = path.join(os.homedir(), ".codex", "hooks.json");
+  const config = readJSON(file, { description: "Shifu reviewed sync reminders" });
+  addHook(config, "Stop", shellCommand(harness, "stop"), 3);
+  addHook(config, "SessionEnd", shellCommand(harness, "session_end"), 3);
+  writeJSON(file, config);
+  return file;
+}
+
+function enableClaude(harness) {
+  const file = path.join(os.homedir(), ".claude", "settings.json");
+  const config = readJSON(file, {});
+  addHook(config, "Stop", shellCommand(harness, "stop"), 3);
+  addHook(config, "SessionEnd", shellCommand(harness, "session_end"), 3);
+  writeJSON(file, config);
+  return file;
+}
+
+function enableOpenCode(harness) {
+  const file = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "plugins", "shifu-sync.js");
+  const runner = JSON.stringify(installedRunnerPath());
+  const source = `import { spawn } from "node:child_process";\n\nconst runner = ${runner};\n\nfunction notify(event) {\n  const child = spawn(process.execPath, [runner, "hook", "--harness", "${harness}", "--event", "idle"], { stdio: ["pipe", "ignore", "ignore"], detached: true });\n  child.stdin.end(JSON.stringify({ event }));\n  child.unref();\n}\n\nexport const ShifuSync = async () => ({\n  event: async ({ event }) => {\n    if (event.type === "session.idle" || event.type === "session.deleted") notify(event);\n  },\n});\n`;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, source, { mode: 0o600 });
+  return file;
+}
+
+function installDestination(harness) {
+  if (harness === "codex") return path.join(os.homedir(), ".codex", "skills", "shifu-sync");
+  if (harness === "claude_code") return path.join(os.homedir(), ".claude", "skills", "shifu-sync");
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "opencode", "commands", "shifu-sync.md");
+}
+
+function install(harness) {
+  copyRunner();
+  const destination = installDestination(harness);
+  if (harness === "opencode") {
+    fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o700 });
+    fs.copyFileSync(path.join(__dirname, "..", "commands", "shifu-sync.md"), destination);
+  } else {
+    copyDirectory(path.join(__dirname, "..", "skills", "shifu-sync"), destination);
+    const skill = path.join(destination, "SKILL.md");
+    const content = fs.readFileSync(skill, "utf8")
+      .replaceAll('"codex"', `"${harness}"`)
+      .replaceAll("--harness codex", `--harness ${harness}`);
+    fs.writeFileSync(skill, content, { mode: 0o600 });
+  }
+  console.error(`Installed the Shifu sync instruction for ${HARNESS_NAMES[harness]}.`);
+  console.error(`Next: shifu-harness connect --harness ${harness}`);
+}
+
+async function connect(harness) {
+  const terminal = prompt();
+  const token = (await terminal.question("Connection key: ")).trim();
+  terminal.close();
+  if (!TOKEN_PATTERN.test(token)) throw new Error("The connection key is invalid.");
+  const apiUrl = (option("--api-url") || process.env.SHIFU_API_URL || DEFAULT_API_URL).replace(/\/$/, "");
+  if (!(await confirm(`Save this ${HARNESS_NAMES[harness]} key locally for ${apiUrl}? No work content will be sent.`))) {
+    console.error("Connection was not saved.");
+    return;
+  }
+  const existing = readJSON(configPath(harness), {});
+  writeJSON(configPath(harness), { ...existing, apiUrl, token, harness, schedule: existing.schedule || { afterTurns: 12, afterHours: 4 } });
+  console.error(`${HARNESS_NAMES[harness]} is connected. Run activate only when you want reminders.`);
+}
+
+async function activate(harness) {
+  readConfig(harness);
+  if (!(await confirm(`Activate Shifu reminders for ${HARNESS_NAMES[harness]}? This adds local lifecycle hooks. They only mark syncs as due; they never upload automatically.`))) {
+    console.error("Activation was cancelled.");
+    return;
+  }
+  copyRunner();
+  const file = harness === "codex" ? enableCodex(harness) : harness === "claude_code" ? enableClaude(harness) : enableOpenCode(harness);
+  console.error(`Shifu reminders are active. Updated ${file}.`);
+}
+
+async function schedule(harness) {
+  const config = readConfig(harness);
+  const afterTurns = Number(option("--after-turns") || config.schedule?.afterTurns || 12);
+  const afterHours = Number(option("--after-hours") || config.schedule?.afterHours || 4);
+  if (!Number.isInteger(afterTurns) || afterTurns < 1 || afterTurns > 1000 || !Number.isFinite(afterHours) || afterHours <= 0 || afterHours > 168) {
+    throw new Error("Choose --after-turns from 1 to 1000 and --after-hours greater than 0 and at most 168.");
+  }
+  if (!(await confirm(`Save a reminder after ${afterTurns} turns or ${afterHours} hours without a sync? It will request review, never upload automatically.`))) {
+    console.error("Schedule was not changed.");
+    return;
+  }
+  writeJSON(configPath(harness), { ...config, schedule: { afterTurns, afterHours } });
+  console.error("Reminder schedule saved. Activate the connector to receive harness lifecycle reminders.");
+}
+
+function sessionID(input) {
+  return input.session_id || input.sessionId || input?.event?.properties?.sessionID || input?.event?.properties?.id;
+}
+
+function hook(harness, event) {
+  const config = readConfig(harness);
+  const input = readJSON(0, {});
+  const reference = sessionID(input);
+  if (typeof reference !== "string" || reference.length < 8) return;
+  const state = readState(harness);
+  state.lastSessionRef = reference;
+  const session = state.sessions[reference] || { turnsSinceSync: 0, lastSyncedAt: 0, syncDue: false };
+  if (event === "stop" || event === "idle") session.turnsSinceSync += 1;
+  if (event === "session_end") session.syncDue = true;
+  const hoursSinceSync = session.lastSyncedAt ? (Date.now() - session.lastSyncedAt) / 3_600_000 : 0;
+  const schedule = config.schedule || { afterTurns: 12, afterHours: 4 };
+  const due = session.turnsSinceSync >= schedule.afterTurns || hoursSinceSync >= schedule.afterHours || session.syncDue;
+  session.syncDue = due;
+  state.sessions[reference] = session;
+  saveState(harness, state);
+  if (event === "stop" && harness === "codex") {
+    process.stdout.write(JSON.stringify(due
+      ? { systemMessage: "A Shifu sync is due. Prepare an incremental, redacted summary, show exactly what would be sent, and ask the user to confirm before running sync." }
+      : { continue: true }));
+  }
+}
+
+function textIsSafe(value, maximum) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= maximum && !SENSITIVE_PATTERNS.some((pattern) => value.toLowerCase().includes(pattern));
+}
+
+function validateSync(input, harness) {
+  if (!input || input.harness !== harness || typeof input.sessionRef !== "string" || !textIsSafe(input.sessionRef, 200) || input.sessionRef.length < 8) throw new Error("Add the current opaque sessionRef before syncing.");
+  if (!Number.isInteger(input.fromTurn) || !Number.isInteger(input.toTurn) || input.fromTurn < 1 || input.toTurn < input.fromTurn) throw new Error("Use a valid incremental turn range.");
+  if (!textIsSafe(input.summary, 1200)) throw new Error("The summary is empty, too long, or contains sensitive content. Redact it before syncing.");
+  for (const field of ["evidence", "decisions"]) {
+    if (!Array.isArray(input[field]) || input[field].length > 4 || !input[field].every((item) => textIsSafe(item, 240))) throw new Error(`${field} must contain at most four redacted statements.`);
+  }
+  if (input.redactionVersion !== 1) throw new Error("Use redactionVersion 1.");
+}
+
+async function sync(harness) {
+  const config = readConfig(harness);
+  const input = readJSON(0, undefined);
+  validateSync(input, harness);
+  const state = readState(harness);
+  const checkpoint = state.sessions[input.sessionRef];
+  const expected = (checkpoint?.lastSyncedTurn || 0) + 1;
+  if (input.fromTurn !== expected) throw new Error(`This local checkpoint expects turn ${expected}. Review the pending segment before retrying.`);
+  const preview = JSON.stringify(input, null, 2);
+  console.error(`\nThis exact reviewed, redacted segment will be sent to Shifu:\n${preview}`);
+  if (!(await confirm("Sync this segment"))) {
+    console.error("Nothing was sent.");
+    return;
+  }
+  const response = await fetch(`${config.apiUrl}/v1/connectors/coding-sessions/syncs`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.token}` },
+    body: JSON.stringify(input),
+  });
+  const payload = await response.json().catch(() => undefined);
+  if (!response.ok) throw new Error(payload?.error?.message || `Shifu rejected the sync (${response.status}).`);
+  const receipt = payload?.data;
+  if (!receipt || !Number.isInteger(receipt.lastSyncedTurn)) throw new Error("Shifu did not return a sync checkpoint.");
+  state.sessions[input.sessionRef] = { turnsSinceSync: 0, lastSyncedAt: Date.now(), lastSyncedTurn: receipt.lastSyncedTurn, syncDue: false };
+  saveState(harness, state);
+  console.error(receipt.duplicate ? "Shifu already had this exact segment. Local checkpoint recovered." : `Synced through turn ${receipt.lastSyncedTurn}.`);
+}
+
+function status(harness) {
+  const config = readConfig(harness);
+  const state = readState(harness);
+  console.log(JSON.stringify({ harness, apiUrl: config.apiUrl, schedule: config.schedule, sessions: state.sessions }, null, 2));
+}
+
+async function main() {
+  const command = process.argv[2];
+  const harness = requireHarness(option("--harness"));
+  if (command === "install") return install(harness);
+  if (command === "connect") return connect(harness);
+  if (command === "activate") return activate(harness);
+  if (command === "schedule") return schedule(harness);
+  if (command === "sync") return sync(harness);
+  if (command === "status") return status(harness);
+  if (command === "hook") return hook(harness, option("--event"));
+  throw new Error("Use install, connect, activate, schedule, sync, status, or hook.");
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { addHook, configPath, statePath, textIsSafe, validateSync };

package/commands/shifu-sync.md

@@ -0,0 +1,11 @@
+---
+description: Prepare a reviewed, redacted incremental Shifu sync and ask for confirmation.
+---
+
+Use the Shifu reviewed-sync process for the current OpenCode session. Never upload automatically or include raw transcript content. First explain what the unsynced incremental segment contains and show the exact JSON payload. Ask the user to confirm. Only after confirmation, pipe the reviewed payload to:
+
+```sh
+npx @useshifu/coding-harness sync --harness opencode
+```
+
+The payload must contain `harness`, an opaque `sessionRef`, `fromTurn`, `toTurn`, a concise redacted `summary`, up to four redacted `evidence` items, up to four redacted `decisions`, and `redactionVersion: 1`. Replace names, paths, URLs, credentials, commands, prompts, source code, customer details, and proprietary identifiers with neutral descriptions.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@useshifu/coding-harness",
+  "version": "0.1.0",
+  "description": "Reviewed, incremental coding-harness sync for Shifu",
+  "bin": {
+    "shifu-harness": "bin/shifu-harness.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "commands",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/skills/shifu-sync/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: shifu-sync
+description: Prepare and sync a reviewed, redacted incremental summary of the current coding session to Shifu. Use only when the user explicitly asks to connect, activate, schedule, sync, or push their Shifu coding-harness data.
+---
+
+Shifu captures reviewed, incremental work context. It does not collect raw transcripts or upload in the background.
+
+Before taking any action, state the exact action and ask the user for confirmation:
+
+- `connect`: explain that the command saves the supplied connection key locally and does not send session content.
+- `activate`: explain that it adds local lifecycle hooks. Hooks can mark a sync as due, but never upload automatically.
+- `schedule`: explain the turn and time thresholds. A threshold asks for review on the next active harness turn; it cannot interrupt an ended session with a dialog.
+- `sync`: show the exact JSON payload, including its incremental `fromTurn` and `toTurn`, then ask whether to send it.
+
+Before preparing a sync, run `npx @useshifu/coding-harness status --harness codex` to see the local checkpoint. Use its most recent opaque `lastSessionRef` and begin at `lastSyncedTurn + 1`. Do not guess a checkpoint or claim to be syncing the whole conversation when an earlier segment is still pending.
+
+For a manual request such as “push this conversation,” prepare only the unsynced segment. Make the content concise and useful, preserving technical decisions, outcome, evidence, and verification. Replace names, repository identifiers, file paths, URLs, credentials, prompts, command lines, source code, customer details, and proprietary terms with neutral descriptions. Never invent missing details.
+
+When a turn or time reminder appears, first decide whether the unsynced work forms a coherent, useful segment. If it does not, keep the segment pending and continue the session without prompting or sending anything. A reminder is never permission to upload.
+
+Use this structure:
+
+```json
+{
+  "harness": "codex",
+  "sessionRef": "opaque-session-id",
+  "fromTurn": 1,
+  "toTurn": 12,
+  "summary": "Implemented a narrow change and checked the relevant behaviour.",
+  "evidence": ["Focused tests passed."],
+  "decisions": ["Kept the change within the existing connector boundary."],
+  "redactionVersion": 1
+}
+```
+
+Only after the user confirms the displayed payload, run:
+
+```sh
+printf '%s' '<reviewed JSON>' | npx @useshifu/coding-harness sync --harness codex
+```
+
+The CLI prints the payload again and asks for a final terminal confirmation. Never bypass that confirmation.