@supersuit/transcript-md 0.1.0

package/lib/freedom-run-lock.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// A run lock that is stale only when the run that holds it is DEAD.
+//
+// WHY THIS EXISTS (freedom-dev#146). catch-up-freeda guarded itself with a lockfile holding a
+// timestamp, and called any lock older than 15 minutes stale. Age was standing in for liveness,
+// and a real run broke the stand-in: thirteen recordings, about ten hours of audio, several hours
+// of transcription. A second run found the lock "stale", deleted it, and ran to completion on the
+// same staging directory, sync state and people files. Neither run reported the overlap.
+//
+// So the lock names its holder, and nothing about its age decides anything:
+//
+//   { pid, pidStarted, by, since }
+//
+//   - `pid` is the holding SESSION's pid ($PPID from a skill's shell, never a helper's own pid).
+//   - `pidStarted` is that process's start time as `ps` reports it. A pid is recycled once its
+//     process exits, and a crashed run whose pid now belongs to an unrelated process would
+//     otherwise hold the lock forever, which silences the unattended timer for good. Matching the
+//     start time makes "this pid is alive" mean "THIS run is alive".
+//
+// A lock with no pid is LEGACY, written by a skill from before this library. It cannot say whether
+// its run is alive, so it keeps the rule it was written under (15 minutes) rather than being held
+// forever, and it is reported as legacy so nobody mistakes the guess for a verdict.
+//
+// This is the same liveness rule freedom-claims.mjs uses for a project claim, applied to a lock.
+//
+// CLI (exit codes are the contract):
+//   node freedom-run-lock.mjs acquire <skill> --pid $PPID [--by <who>]   0 taken, 3 held by a live run
+//   node freedom-run-lock.mjs status  <skill>                            prints free|held|stale|legacy-held|legacy-stale
+//   node freedom-run-lock.mjs release <skill> [--pid $PPID]              0 released or already free, 3 held by another live run
+//   Any command takes --path <lockfile> instead of <skill>.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isMain } from "./freedom-is-main.mjs";
+
+/** The age rule a legacy lock was written under. Never applied to a lock that names its holder. */
+export const LEGACY_STALE_MS = 15 * 60 * 1000;
+
+/** When `pid`'s process started, as `ps` prints it, or null when there is no such process. */
+export function processStart(pid, { run = execFileSync } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    const out = String(run("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })).trim();
+    return out || null;
+  } catch { return null; }
+}
+
+/** True when the pid answers signal 0. EPERM means it exists and belongs to someone else. */
+export function pidAlive(pid, { kill = process.kill.bind(process) } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; }
+}
+
+function readLock(path) {
+  let text;
+  try { text = readFileSync(path, "utf8"); } catch { return { exists: false }; }
+  try {
+    const rec = JSON.parse(text);
+    if (rec && Number.isInteger(rec.pid) && rec.pid > 0) return { exists: true, rec };
+  } catch { /* legacy: a bare timestamp or an empty file */ }
+  return { exists: true, rec: null };
+}
+
+/**
+ * The lock's state. `held` and `legacy-held` mean a run owns it; `stale`, `legacy-stale` and
+ * `free` mean a new run may take it. Age decides only a legacy lock.
+ */
+export function lockStatus(path, { alive = pidAlive, startOf = processStart, now = Date.now() } = {}) {
+  const { exists, rec } = readLock(path);
+  if (!exists) return { state: "free" };
+  if (!rec) {
+    let age = 0;
+    try { age = now - statSync(path).mtimeMs; } catch { /* vanished between reads */ }
+    return age < LEGACY_STALE_MS
+      ? { state: "legacy-held", ageMs: age, why: "a lock with no pid, younger than 15 minutes" }
+      : { state: "legacy-stale", ageMs: age, why: "a lock with no pid, older than 15 minutes" };
+  }
+  if (!alive(rec.pid)) return { state: "stale", record: rec, why: `pid ${rec.pid} is not running` };
+  if (rec.pidStarted) {
+    const started = startOf(rec.pid);
+    if (started && started !== rec.pidStarted) {
+      return { state: "stale", record: rec, why: `pid ${rec.pid} was reused by a process started ${started}` };
+    }
+  }
+  return { state: "held", record: rec, why: `pid ${rec.pid} is running` };
+}
+
+export const isHeld = (s) => s.state === "held" || s.state === "legacy-held";
+
+/**
+ * Take the lock for `pid`. Never takes it from a live run. Clears a stale one and says so.
+ * The write is exclusive (`wx`), so two runs racing past the status check cannot both win.
+ */
+export function acquire(path, { pid, by = "unknown", now = new Date(), alive = pidAlive, startOf = processStart } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) throw new Error(`acquire needs the holding session's pid ($PPID from a skill's shell), got ${pid}`);
+  const status = lockStatus(path, { alive, startOf, now: now.getTime() });
+  if (isHeld(status)) {
+    if (status.record?.pid === pid) return { acquired: true, reentrant: true, status };
+    return { acquired: false, status };
+  }
+  if (status.state !== "free") { try { unlinkSync(path); } catch { /* already gone */ } }
+  mkdirSync(dirname(path), { recursive: true });
+  const rec = { pid, pidStarted: startOf(pid), by, since: now.toISOString() };
+  try {
+    writeFileSync(path, JSON.stringify(rec, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e?.code === "EEXIST") return { acquired: false, status: lockStatus(path, { alive, startOf }) };
+    throw e;
+  }
+  return { acquired: true, record: rec, cleared: status.state === "free" ? null : status };
+}
+
+/**
+ * Release the lock. With a pid, refuses to delete a lock a DIFFERENT live run holds, which is the
+ * mirror of the bug this file exists for: a finishing run must not delete a newer run's lock.
+ */
+export function release(path, { pid = null, alive = pidAlive, startOf = processStart } = {}) {
+  const status = lockStatus(path, { alive, startOf });
+  if (status.state === "free") return { released: false, status };
+  if (pid != null && status.state === "held" && status.record.pid !== pid) return { released: false, status };
+  try { unlinkSync(path); } catch { /* already gone */ }
+  return { released: true, status };
+}
+
+async function lockPathFor(args) {
+  const i = args.indexOf("--path");
+  if (i !== -1 && args[i + 1]) return args[i + 1];
+  const skill = args.find((a, j) => !a.startsWith("--") && !(j > 0 && args[j - 1].startsWith("--")));
+  if (!skill) throw new Error("name a skill, or pass --path <lockfile>");
+  const here = dirname(fileURLToPath(import.meta.url));
+  const { stateDir } = await import(pathToFileURL(join(here, "freedom-workspace.mjs")).href);
+  return join(stateDir(skill), ".lock");
+}
+
+if (isMain(import.meta.url)) {
+  const [cmd, ...args] = process.argv.slice(2);
+  const opt = (k) => { const i = args.indexOf(k); return i === -1 ? undefined : args[i + 1]; };
+  try {
+    const path = await lockPathFor(args);
+    if (cmd === "status") {
+      const s = lockStatus(path);
+      console.log(s.state);
+      if (s.why) console.error(s.why);
+    } else if (cmd === "acquire") {
+      const r = acquire(path, { pid: parseInt(opt("--pid") ?? "", 10), by: opt("--by") ?? "cli" });
+      if (r.acquired) {
+        if (r.cleared) console.error(`cleared a ${r.cleared.state} lock: ${r.cleared.why}`);
+        console.log("acquired");
+      } else {
+        console.log("Pipeline already running.");
+        console.error(r.status.why || r.status.state);
+        process.exit(3);
+      }
+    } else if (cmd === "release") {
+      const pid = opt("--pid") ? parseInt(opt("--pid"), 10) : null;
+      const r = release(path, { pid });
+      if (!r.released && r.status.state === "held") {
+        console.error(`not released: ${r.status.why}, and it is not this run`);
+        process.exit(3);
+      }
+      console.log(r.released ? "released" : "already free");
+    } else {
+      console.error("usage: freedom-run-lock.mjs {acquire <skill> --pid $PPID [--by <who>] | status <skill> | release <skill> [--pid $PPID]} (or --path <lockfile>)");
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+  }
+}

package/lib/freedom-self.mjs

@@ -0,0 +1,5 @@
+// Existing self reference only; no profile/global workspace discovery.
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {paths} from './freedom-workspace.mjs';
+export function workspaceFile(root,key){if(key!=='self.md')throw Error('Unsupported self reference');const p=paths(root),fresh=join(p.self,'self.md'),legacy=join(p.user,'USER.md');return existsSync(fresh)?fresh:existsSync(legacy)?legacy:fresh;}

package/lib/freedom-workspace.mjs

@@ -0,0 +1,19 @@
+// Portable boundary: explicit caller roots and local markers only. No environment/home discovery.
+import {existsSync,readFileSync,realpathSync,lstatSync} from 'node:fs';
+import {resolve,join,dirname,isAbsolute} from 'node:path';
+const required=root=>{if(typeof root!=='string'||!root)throw Object.assign(Error('explicit workspace root required'),{code:'WORKSPACE_REQUIRED'});return realpathSync(resolve(root));};
+export function resolveTrackedRoot(root){return required(root);}
+export function enclosingWorkspace(start){let dir=resolve(start);for(;;){if(existsSync(join(dir,'.freedom.json')))return required(dir);const parent=dirname(dir);if(parent===dir)return null;dir=parent;}}
+export function paths(root){
+ root=required(root);const config=join(root,'.freedom.json');let cfg={};
+ if(existsSync(config)){cfg=JSON.parse(readFileSync(config,'utf8'));if(!cfg||typeof cfg!=='object'||Array.isArray(cfg)||cfg.paths!==undefined&&(!cfg.paths||typeof cfg.paths!=='object'||Array.isArray(cfg.paths)))throw Error('Invalid caller root configuration');}
+ const defaults={transcripts:'meeting-transcripts',state:'.agents/state',people:'people',self:'self',user:'user'};
+ const out={root};for(const [key,fallback]of Object.entries(defaults)){const value=cfg.paths?.[key]??fallback;if(typeof value!=='string'||!value||value.startsWith('~'))throw Error('Caller paths must be explicit paths');out[key]=resolve(root,value);}
+ // Relative state is shared by linked Git worktrees, matching the common-repository capture lock.
+ const dotgit=join(root,'.git');if(existsSync(dotgit)&&lstatSync(dotgit).isFile()){
+  const match=/^gitdir:\s*(.+)$/m.exec(readFileSync(dotgit,'utf8'));
+  if(match){const gitdir=resolve(root,match[1]),common=join(gitdir,'commondir');if(existsSync(common)){const main=dirname(realpathSync(resolve(gitdir,readFileSync(common,'utf8').trim())));const value=cfg.paths?.state??defaults.state;if(!isAbsolute(value))out.state=resolve(main,value);}}
+ }
+ return out;
+}
+export function stateDir(skill,root){if(typeof skill!=='string'||!skill||/[/\\]/.test(skill)||skill==='.'||skill==='..')throw Error('stateDir needs a bare skill name');return join(paths(root).state,skill);}

package/lib/freedom_conversations.py

@@ -0,0 +1,219 @@
+"""Thin Python door to the shared conversation CLI; never parse or write Markdown.
+
+Installed callers resolve the adjacent packaged CLI; no global resolver or
+source-checkout override is consulted.
+Every bridge failure raises ConversationError rather than an empty archive.
+"""
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+class ConversationError(RuntimeError):
+    """Redacted bridge failure retaining the actual exit and shared diagnostics."""
+
+    def __init__(self, message, returncode=None, diagnostics=None):
+        self.returncode = returncode
+        self.diagnostics = diagnostics or []
+        codes = ", ".join(d.get("code", "UNKNOWN") for d in self.diagnostics)
+        super().__init__(message + (": " + codes if codes else ""))
+
+
+def _diagnostics(value):
+    if not isinstance(value, list) or any(not isinstance(d, dict)
+            or not isinstance(d.get("code"), str)
+            or d.get("severity") not in ("error", "warning") for d in value):
+        raise ConversationError("Malformed conversation diagnostics")
+    return value
+
+
+def _run(args, workspace=None):
+    # The shared workspace resolver prioritizes its environment binding over
+    # --workspace. Pin an explicit caller selector in the child too, without
+    # mutating the Python caller's environment or changing default resolution.
+    env = None if workspace is None else dict(os.environ, FREEDOM_WORKSPACE=os.fspath(workspace))
+    try:
+        result = subprocess.run(args, capture_output=True, text=True,
+                                encoding="utf-8", check=True, env=env)
+    except OSError as exc:
+        raise ConversationError("Conversation runtime unavailable") from exc
+    except UnicodeError as exc:
+        raise ConversationError("Unreadable conversation output") from exc
+    except subprocess.CalledProcessError as exc:
+        diagnostics = []
+        try:
+            value = json.loads(exc.stdout)
+            if isinstance(value, dict):
+                diagnostics = _diagnostics(value.get("diagnostics", []))
+        except (ValueError, TypeError, ConversationError):
+            pass
+        raise ConversationError("Conversation CLI failed", exc.returncode, diagnostics) from exc
+    try:
+        value = json.loads(result.stdout)
+    except (ValueError, TypeError) as exc:
+        raise ConversationError("Malformed conversation JSON") from exc
+    if not isinstance(value, dict) or type(value.get("api_version")) is not int or value["api_version"] != 1:
+        raise ConversationError("Unsupported conversation API")
+    if "diagnostics" in value:
+        diagnostics = _diagnostics(value["diagnostics"])
+        if any(d["severity"] == "error" for d in diagnostics):
+            raise ConversationError("Conversation read refused", result.returncode, diagnostics)
+    return value
+
+
+def _cli(command):
+    cli = Path(__file__).resolve().with_name("freedom-conversations-cli.mjs")
+    if not cli.is_file():
+        raise ConversationError("Installed conversation CLI unavailable")
+    invocation = ["node", str(cli)]
+    caps = _run(invocation + ["--capabilities", "--json"])
+    if not isinstance(caps.get("schema_versions"), list) or not any(type(v) is int and v == 1 for v in caps["schema_versions"]):
+        raise ConversationError("Unsupported conversation schema capability")
+    if not isinstance(caps.get("commands"), list) or command not in caps["commands"]:
+        raise ConversationError("Missing conversation command capability")
+    return invocation
+
+
+def _root_args(workspace=None, transcripts_dir=None):
+    if workspace is not None and transcripts_dir is not None:
+        raise ValueError("Use exactly one root selector")
+    if workspace is not None:
+        if not os.fspath(workspace):
+            raise ValueError("Empty workspace selector")
+        return ["--workspace", os.fspath(workspace)]
+    if transcripts_dir is not None:
+        if not os.fspath(transcripts_dir):
+            raise ValueError("Empty transcript selector")
+        return ["--transcripts-dir", os.fspath(transcripts_dir)]
+    return []
+
+
+def _records(value):
+    _diagnostics(value.get("diagnostics"))
+    records = value.get("records")
+    if not isinstance(records, list) or any(not isinstance(r, dict) or not isinstance(r.get("path"), str) for r in records):
+        raise ConversationError("Malformed conversation records")
+    for record in records:
+        diagnostics = _diagnostics(record.get("diagnostics"))
+        if any(d["severity"] == "error" for d in diagnostics):
+            raise ConversationError("Conversation record refused", diagnostics=diagnostics)
+    return records
+
+
+def list_records(workspace=None, transcripts_dir=None, include_sections=False):
+    """Return metadata for admitted records, using exactly the supplied root."""
+    args = ["list"] + _root_args(workspace, transcripts_dir) + ["--json"]
+    if include_sections:
+        args.append("--include-sections")
+    return _records(_run(_cli("list") + args, workspace))
+
+
+def _read(command, path, workspace=None, include_body=False):
+    args = [command, os.fspath(path)] + _root_args(workspace) + ["--json"]
+    if include_body:
+        args.append("--include-body")
+    records = _records(_run(_cli(command) + args, workspace))
+    if len(records) != 1:
+        raise ConversationError("Conversation read requires one record")
+    return records[0]
+
+
+def read_record(path, workspace=None, include_body=False):
+    """Return one record; words/sections are included only on explicit request."""
+    return _read("read", path, workspace, include_body)
+
+
+def read_source_refs(path, workspace=None):
+    """Shared SourceRefs plus explicit resolvedPath, without changing identity.
+
+    Metadata Capture locators establish kind, never a guess from path spelling.
+    Pair exact capture/locator/role properties and pin the two read snapshots.
+    A relative external locator has no declared origin and therefore refuses.
+    Service-only and unknown locators retain null resolvedPath.
+    """
+    record = read_record(path, workspace)
+    sourced = _read("sources", path, workspace)
+    if record.get("fileSha256") != sourced.get("fileSha256") or record["path"] != sourced["path"]:
+        raise ConversationError("Conversation changed during source read")
+    captures = record.get("sources")
+    refs = sourced.get("sources")
+    if not isinstance(captures, list) or not isinstance(refs, list):
+        raise ConversationError("Source metadata unavailable")
+    result = []
+    for ref in refs:
+        if not isinstance(ref, dict):
+            raise ConversationError("Malformed shared source reference")
+        matches = [c for c in captures if c.get("id") == ref.get("capture")]
+        if len(matches) != 1 or ref.get("role") not in matches[0].get("roles", []):
+            raise ConversationError("Source metadata mismatch")
+        capture = matches[0]
+        if any(capture.get(a) != ref.get(b) for a, b in (("type", "type"), ("service", "service"), ("recording_id", "recordingId"), ("vendor_id", "vendorId"), ("availability", "availability"))):
+            raise ConversationError("Source identity mismatch")
+        locators = capture.get("locators", [])
+        matching = [l for l in locators if all(l.get(a) == ref.get(b) for a, b in (("path", "path"), ("url", "url"), ("service_id", "serviceId")))]
+        kinds = {l.get("kind") for l in matching}
+        if not locators and all(ref.get(k) is None for k in ("path", "url", "serviceId")):
+            kind = None
+        elif len(kinds) == 1:
+            kind = next(iter(kinds))
+        else:
+            raise ConversationError("Source locator kind unresolved")
+        resolved = None
+        original = ref.get("path")
+        if kind == "bundled":
+            folder = Path(record["path"]).parent.resolve()
+            target = (folder / original).resolve()
+            if not target.is_relative_to(folder):
+                raise ConversationError("Bundled source escapes entry folder")
+            resolved = str(target)
+        elif kind == "external-local":
+            expanded = os.path.expanduser(original)
+            if not os.path.isabs(expanded):
+                raise ConversationError("External source origin unresolved")
+            resolved = os.path.abspath(expanded)
+        elif kind not in (None, "service"):
+            raise ConversationError("Source locator kind unsupported")
+        result.append(dict(ref, resolvedPath=resolved))
+    return result
+
+
+def _revision_result(value):
+    required = ("path", "revision_id", "changed", "before_sha256", "after_sha256", "turn_ids", "journal_path", "recovered")
+    if any(key not in value for key in required):
+        raise ConversationError("Malformed conversation revision result")
+    return {key: value[key] for key in required}
+
+
+def revise_record(path, spec, expected_sha, workspace=None):
+    """Transport the complete caller spec and exact pin to the shared writer."""
+    invocation = _cli("revise")
+    with tempfile.TemporaryDirectory(prefix="conversation-spec-") as temporary:
+        spec_file = Path(temporary) / "spec.json"
+        spec_file.write_text(json.dumps(spec, ensure_ascii=False, allow_nan=False), encoding="utf-8")
+        value = _run(invocation + ["revise", os.fspath(path), "--spec", str(spec_file),
+            "--expected-sha", expected_sha] + _root_args(workspace) + ["--json"], workspace)
+    return _revision_result(value)
+
+
+def recover_revision(path, revision_id, action, workspace=None):
+    """Resume/reverse only through the journal-aware shared recovery command."""
+    value = _run(_cli("recover") + ["recover", os.fspath(path), "--revision-id", revision_id,
+        "--action", action] + _root_args(workspace) + ["--json"], workspace)
+    return _revision_result(value)
+
+
+def annotate_record(path, spec, expected_sha, workspace=None):
+    """Transport append-only interpretation and caller pins to shared authority."""
+    invocation = _cli("annotate")
+    with tempfile.TemporaryDirectory(prefix="conversation-spec-") as temporary:
+        spec_file = Path(temporary) / "spec.json"
+        spec_file.write_text(json.dumps(spec, ensure_ascii=False, allow_nan=False), encoding="utf-8")
+        value = _run(invocation + ["annotate", os.fspath(path), "--spec", str(spec_file),
+            "--expected-sha", expected_sha] + _root_args(workspace) + ["--json"], workspace)
+    if (not isinstance(value.get("path"), str) or not value["path"]
+            or not isinstance(value.get("fileSha256"), str) or len(value["fileSha256"]) != 64
+            or any(c not in "0123456789abcdef" for c in value["fileSha256"])):
+        raise ConversationError("Malformed conversation annotation result")
+    return {key: value[key] for key in ("path", "fileSha256")}