@rowan-hiro/inkan 0.1.0

package/src/git.js

@@ -0,0 +1,83 @@
+// The only child process Inkan ever spawns: git, with a fixed argument
+// array. Never `shell: true`, never a user-supplied command string.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+function run(args, { cwd, env }) {
+  return spawnSync('git', args, { cwd, env, encoding: 'utf8' });
+}
+
+/** The full sha `ref` resolves to, or null if it does not resolve here. */
+export function revParse(cwd, ref) {
+  const result = run(['rev-parse', ref], { cwd, env: process.env });
+  if (result.status !== 0) return null;
+  return result.stdout.trim();
+}
+
+/** The HEAD sha, or null outside a worktree or before the first commit. */
+export function head(cwd) {
+  return revParse(cwd, 'HEAD');
+}
+
+export function isWorktree(cwd) {
+  const result = run(['rev-parse', '--is-inside-work-tree'], { cwd, env: process.env });
+  return result.status === 0 && result.stdout.trim() === 'true';
+}
+
+/** The abbreviated form of `sha`, or `sha` itself if git cannot shorten it. */
+export function shortSha(cwd, sha) {
+  const result = run(['rev-parse', '--short', sha], { cwd, env: process.env });
+  return result.status === 0 ? result.stdout.trim() : sha;
+}
+
+/** Values of `commit`'s `Inkan-Outcome` trailers, in order; empty if none or if `commit` does not resolve. */
+export function trailerValues(cwd, commit) {
+  const result = run(['log', '-1', '--format=%(trailers:key=Inkan-Outcome,valueonly)', commit], { cwd, env: process.env });
+  if (result.status !== 0) return [];
+  return result.stdout.split('\n').filter((line) => line.length > 0);
+}
+
+/** The content of `filePath` as it exists in `commit`'s tree, or null if it is not there. */
+export function showFile(cwd, commit, filePath) {
+  const result = run(['show', `${commit}:${filePath}`], { cwd, env: process.env });
+  return result.status === 0 ? result.stdout : null;
+}
+
+/** Whether `recordedTree` matches `commit`'s tree, `.inkan/outcomes` excluded. */
+export function treeMatchesCommit(cwd, recordedTree, commit) {
+  const result = run(
+    ['diff-tree', '-r', '--quiet', recordedTree, `${commit}^{tree}`, '--', '.', ':(exclude).inkan/outcomes'],
+    { cwd, env: process.env }
+  );
+  return result.status === 0;
+}
+
+/**
+ * The tree hash of the working tree, `.inkan/outcomes` excluded, via the
+ * temporary-index recipe from decision 0006. Returns null outside a worktree.
+ * The temporary index file is always cleaned up.
+ */
+export function treeHash(cwd) {
+  if (!isWorktree(cwd)) return null;
+  const tmp = path.join(os.tmpdir(), `inkan-index-${process.pid}-${crypto.randomUUID()}`);
+  const env = { ...process.env, GIT_INDEX_FILE: tmp };
+  try {
+    let result = run(['read-tree', '--empty'], { cwd, env });
+    if (result.status !== 0) throw new Error(`git read-tree failed: ${result.stderr}`);
+    result = run(['add', '-A', '--', '.', ':(exclude).inkan/outcomes'], { cwd, env });
+    if (result.status !== 0) throw new Error(`git add failed: ${result.stderr}`);
+    result = run(['write-tree'], { cwd, env });
+    if (result.status !== 0) throw new Error(`git write-tree failed: ${result.stderr}`);
+    return result.stdout.trim();
+  } finally {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/store.js

@@ -0,0 +1,167 @@
+// Storage primitives: seal root discovery, outcome id generation, and durable
+// reads/writes of per-outcome event files. No knowledge of event semantics
+// lives here; that is fold.js.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const DIR_NAME = '.inkan';
+
+/**
+ * Walk up from `startDir` looking for a `.inkan` directory. Returns the
+ * directory that contains it, or null if none is found before the
+ * filesystem root.
+ */
+export function findRoot(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, DIR_NAME))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function outcomesDir(root) {
+  return path.join(root, DIR_NAME, 'outcomes');
+}
+
+export function decisionsDir(root) {
+  return path.join(root, DIR_NAME, 'decisions');
+}
+
+export function outcomeFile(root, id) {
+  return path.join(outcomesDir(root), `${id}.jsonl`);
+}
+
+// Crockford base32, lowercase, with the vowels (a, e) also removed on top of
+// Crockford's own exclusions (i, l, o, u) so an id never spells a word.
+const ID_ALPHABET = '0123456789bcdfghjkmnpqrstvwxyz';
+
+/**
+ * A fresh `YYYY-MM-DD-HHMM-xxxx` id (UTC date, UTC hour and minute, four
+ * random base32 characters), sorting chronologically to the minute with
+ * random tie-breaking. `existingIds` dodges same-minute collisions; a true
+ * cross-clone collision is left for `doctor` (M3) to report. Readers also
+ * accept the earlier `YYYY-MM-DD-xxxx` form (see OUTCOME_ID_RE in cli.js).
+ */
+export function newOutcomeId(existingIds = []) {
+  const existing = new Set(existingIds);
+  const now = new Date().toISOString();
+  const date = now.slice(0, 10);
+  const hhmm = now.slice(11, 13) + now.slice(14, 16);
+  for (;;) {
+    let suffix = '';
+    for (let i = 0; i < 4; i++) {
+      suffix += ID_ALPHABET[crypto.randomInt(ID_ALPHABET.length)];
+    }
+    const id = `${date}-${hhmm}-${suffix}`;
+    if (!existing.has(id)) return id;
+  }
+}
+
+/** Sort key for an outcome id: a legacy `YYYY-MM-DD-xxxx` id (missing the
+ * `HHMM` segment `newOutcomeId` adds) sorts as though that segment were
+ * `0000`, interleaving it chronologically instead of always sorting last. */
+export function idSortKey(id) {
+  const parts = id.split('-');
+  return parts.length === 4 ? `${parts[0]}-${parts[1]}-${parts[2]}-0000-${parts[3]}` : id;
+}
+
+/** Ascending comparator for outcome ids, built on idSortKey. */
+export function compareOutcomeIds(a, b) {
+  return idSortKey(a) < idSortKey(b) ? -1 : idSortKey(a) > idSortKey(b) ? 1 : 0;
+}
+
+export function listOutcomeIds(root) {
+  const dir = outcomesDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => name.slice(0, -'.jsonl'.length))
+    .sort(compareOutcomeIds);
+}
+
+/** Parse one outcome file's raw text into events, `label` naming it in error messages. */
+export function parseOutcomeEvents(raw, label) {
+  return raw
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .map((line, i) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        throw new Error(`${label}:${i + 1}: not valid JSON`);
+      }
+    });
+}
+
+export function readOutcomeEvents(root, id) {
+  const file = outcomeFile(root, id);
+  return parseOutcomeEvents(fs.readFileSync(file, 'utf8'), file);
+}
+
+function fsyncDir(dir) {
+  let fd;
+  try {
+    fd = fs.openSync(dir, 'r');
+    fs.fsyncSync(fd);
+  } catch (err) {
+    // Some platforms refuse to open or fsync a directory; that is not fatal.
+    if (!['EINVAL', 'ENOTSUP', 'EBADF', 'EPERM', 'EISDIR'].includes(err.code)) throw err;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/** Append one event line to an existing outcome file, fsynced before return. */
+export function appendEvent(root, id, event) {
+  const file = outcomeFile(root, id);
+  const line = Buffer.from(`${JSON.stringify(event)}\n`, 'utf8');
+  const fd = fs.openSync(file, 'a');
+  try {
+    fs.writeSync(fd, line);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Create a new outcome file containing exactly one event, failing if the
+ * file already exists. Writes to a temporary file first and fsyncs it, then
+ * links it into place, so the target name never appears with partial
+ * content.
+ */
+export function createOutcomeFile(root, id, event) {
+  const dir = outcomesDir(root);
+  fs.mkdirSync(dir, { recursive: true });
+  const target = outcomeFile(root, id);
+  const temp = path.join(dir, `.${id}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  const line = `${JSON.stringify(event)}\n`;
+  let fd;
+  try {
+    fd = fs.openSync(temp, 'wx', 0o644);
+    fs.writeFileSync(fd, line, 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.linkSync(temp, target);
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // already closed
+      }
+    }
+    try {
+      fs.unlinkSync(temp);
+    } catch {
+      // already gone
+    }
+  }
+  fsyncDir(dir);
+}