superdev-cli 0.1.0

package/src/cloud/crypto.mjs

@@ -0,0 +1,118 @@
+// Encryption for anything that leaves the machine. DEC-TBD-008.
+//
+// The key is generated here, stored here, and never transmitted. What a remote
+// holds is unreadable without it, which is the whole point: a directory on a
+// shared drive, and later a hosted service, both get bytes that say nothing.
+//
+// Losing the key costs the remote copy and nothing else. That is only an
+// acceptable trade because DEC-0014 makes the local database authoritative, so
+// recovery is the local backup rather than the remote. A product whose only
+// copy was remote could not afford an owner-held key, and this one can.
+
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { paths } from "../db/store.mjs";
+
+export const E = {
+  NO_KEY: "E_NO_SYNC_KEY",
+  WRONG_KEY: "E_WRONG_SYNC_KEY",
+  CORRUPT: "E_BUNDLE_CORRUPT",
+};
+
+export class CryptoError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "CryptoError";
+    this.code = code;
+  }
+}
+
+const keyFile = (root) => join(paths(root).dir, "cloud", "key");
+
+/**
+ * The key for this project, created on first use.
+ *
+ * Written with owner-only permissions, in the project's own directory rather
+ * than a shared one, because a key that lives next to the thing it protects is
+ * a key somebody can find when they need it and can delete when they mean to.
+ */
+export function ensureKey(root) {
+  const file = keyFile(root);
+  if (existsSync(file)) return readFileSync(file);
+  const key = randomBytes(32);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, key);
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // A filesystem without permissions is not a reason to refuse the key.
+  }
+  return key;
+}
+
+export function keyExists(root) {
+  return existsSync(keyFile(root));
+}
+
+export function loadKey(root) {
+  const file = keyFile(root);
+  if (!existsSync(file)) {
+    throw new CryptoError(E.NO_KEY,
+      "No encryption key exists for this project, so nothing can be read from or written to a remote. Run superdev cloud connect to create one.");
+  }
+  return readFileSync(file);
+}
+
+/**
+ * A short, stable name for a key.
+ *
+ * Two machines can compare fingerprints to find out whether they hold the same
+ * key without either sending it. A mismatch is the difference between "the
+ * bundle is corrupt" and "you have the wrong key", and those need different
+ * answers from whoever is reading the error.
+ */
+export const fingerprint = (key) =>
+  createHash("sha256").update(key).digest("hex").slice(0, 16);
+
+/** Encrypt a JSON-serializable value. Returns bytes, not text. */
+export function seal(key, value) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const body = Buffer.concat([
+    cipher.update(Buffer.from(JSON.stringify(value), "utf8")),
+    cipher.final(),
+  ]);
+  // Version byte first, so a future format change is detectable rather than
+  // arriving as a decryption failure nobody can explain.
+  return Buffer.concat([Buffer.from([1]), iv, cipher.getAuthTag(), body]);
+}
+
+/** Decrypt what seal produced, or say plainly which of the two things went wrong. */
+export function open(key, bytes) {
+  const buffer = Buffer.from(bytes);
+  if (buffer.length < 30 || buffer[0] !== 1) {
+    throw new CryptoError(E.CORRUPT,
+      "This does not look like a Superdev bundle. It is either truncated or written by a different version.");
+  }
+  const iv = buffer.subarray(1, 13);
+  const tag = buffer.subarray(13, 29);
+  const body = buffer.subarray(29);
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(body), decipher.final()]);
+    return JSON.parse(plain.toString("utf8"));
+  } catch {
+    throw new CryptoError(E.WRONG_KEY,
+      "The bundle could not be opened with this project's key. Either it was written under a different key, or it has been altered since it was written. Nothing has been read from it.");
+  }
+}
+
+/** A stable hash of a record, for deciding whether it changed. */
+export const rowHash = (row) =>
+  createHash("sha256")
+    .update(JSON.stringify(Object.keys(row).sort().map((k) => [k, row[k]])))
+    .digest("hex")
+    .slice(0, 32);

package/src/cloud/merge.mjs

@@ -0,0 +1,186 @@
+// The merge, the conflict, and the lease. DEC-TBD-006.
+//
+// Local first means the local database is always the authority: nothing here
+// ever overwrites a local record without either a clear reason or an explicit
+// resolution. A remote change to a record nobody touched locally is applied. A
+// remote change to a record that also changed locally is refused and recorded
+// as a conflict, because the alternative, last writer wins, loses somebody's
+// work silently. Silence is the failure this product exists to prevent.
+//
+// Three-way, not two-way. Comparing local against remote can only say they
+// differ; it cannot say who moved. The base, what both sides agreed at the end
+// of the last successful sync, is what turns a difference into a fact: changed
+// there, changed here, or changed in both places.
+//
+// Append only history is never merged. Activity does not cross the boundary at
+// all under DEC-TBD-007, and nothing here rewrites a sequence.
+
+import { rowHash } from "./crypto.mjs";
+import { isShared, project } from "./policy.mjs";
+
+/** What a comparison can conclude. */
+export const OUTCOME = {
+  UNCHANGED: "unchanged",
+  REMOTE_ONLY: "remote_only",
+  LOCAL_ONLY: "local_only",
+  BOTH: "both",
+  NEW_REMOTE: "new_remote",
+  NEW_LOCAL: "new_local",
+};
+
+/**
+ * Compare one record across the three points.
+ *
+ * `base` is what both sides last agreed, and its absence means this record has
+ * never synced: it is new to one side or the other rather than conflicted. A
+ * record present on both sides with no base and the same content is treated as
+ * unchanged, which happens whenever two copies come from the same export.
+ */
+export function compare({ local, remote, base }) {
+  const localHash = local ? rowHash(local) : null;
+  const remoteHash = remote ? rowHash(remote) : null;
+
+  if (!local && !remote) return { outcome: OUTCOME.UNCHANGED };
+  if (!local) return { outcome: OUTCOME.NEW_REMOTE, hash: remoteHash };
+  if (!remote) {
+    // No base means this side made it and the other has not seen it. A base
+    // means the other side deleted it, and deletion does not cross: a record
+    // removed elsewhere stays here until somebody removes it here too, because
+    // an accidental deletion that propagates is unrecoverable.
+    return { outcome: OUTCOME.LOCAL_ONLY, hash: localHash };
+  }
+  if (localHash === remoteHash) return { outcome: OUTCOME.UNCHANGED, hash: localHash };
+
+  if (!base) {
+    // Both sides have it, they differ, and nothing says what they agreed on.
+    // Treating that as a conflict is the honest answer: neither side can claim
+    // the other's version is stale.
+    return { outcome: OUTCOME.BOTH, localHash, remoteHash };
+  }
+  const localMoved = localHash !== base.base_hash;
+  const remoteMoved = remoteHash !== base.base_hash;
+  if (localMoved && remoteMoved) return { outcome: OUTCOME.BOTH, localHash, remoteHash };
+  if (remoteMoved) return { outcome: OUTCOME.REMOTE_ONLY, hash: remoteHash };
+  if (localMoved) return { outcome: OUTCOME.LOCAL_ONLY, hash: localHash };
+  return { outcome: OUTCOME.UNCHANGED, hash: localHash };
+}
+
+/**
+ * Which fields actually differ, so a conflict names the disagreement rather
+ * than two opaque blobs. A reader deciding between two versions of a feature
+ * wants to know that the purpose moved, not that something did.
+ */
+export function differingFields(local, remote) {
+  const keys = [...new Set([...Object.keys(local ?? {}), ...Object.keys(remote ?? {})])].sort();
+  const out = [];
+  for (const key of keys) {
+    // A version number differs by definition once anything else does, and
+    // saying so tells a reader nothing.
+    if (key === "version" || key === "updated_at") continue;
+    const a = local?.[key] ?? null;
+    const b = remote?.[key] ?? null;
+    if (JSON.stringify(a) !== JSON.stringify(b)) out.push({ field: key, local: a, remote: b });
+  }
+  return out;
+}
+
+/**
+ * Merge two versions field by field, taking the side that moved.
+ *
+ * Only usable when the two sides changed different fields, which is the common
+ * case for records with many independent columns. Where both moved the same
+ * field there is nothing to merge and the caller has to choose, so this reports
+ * what it could not settle rather than picking.
+ */
+export function mergeFields({ local, remote, base }) {
+  const merged = { ...local };
+  const unsettled = [];
+  for (const { field, local: mine, remote: theirs } of differingFields(local, remote)) {
+    const original = base?.row?.[field] ?? undefined;
+    const localMoved = original === undefined || JSON.stringify(mine) !== JSON.stringify(original);
+    const remoteMoved = original === undefined || JSON.stringify(theirs) !== JSON.stringify(original);
+    if (localMoved && remoteMoved) {
+      unsettled.push(field);
+      continue;
+    }
+    if (remoteMoved) merged[field] = theirs;
+  }
+  return { merged, unsettled };
+}
+
+// ------------------------------------------------------------------- leases
+
+/** How long a claim holds without being renewed. */
+export const LEASE_MINUTES = 60;
+
+export const leaseExpiry = (fromIso, minutes = LEASE_MINUTES) =>
+  new Date(Date.parse(fromIso) + minutes * 60 * 1000).toISOString();
+
+/**
+ * Whether a remote lease still holds a task here.
+ *
+ * An expired lease is not a claim. A machine that crashed holding a task must
+ * not hold it forever, and asking a person to release it by hand is asking them
+ * to clean up after a failure they did not cause.
+ */
+export function leaseHolds(lease, now = new Date().toISOString()) {
+  if (!lease?.lease_holder) return false;
+  if (!lease.lease_expires_at) return true;
+  return Date.parse(lease.lease_expires_at) > Date.parse(now);
+}
+
+/**
+ * Decide what a bundle's leases mean for this side.
+ *
+ * Returns the tasks this machine must not claim, each with the alias holding it
+ * and when that hold lapses, so a refusal can say who and until when instead of
+ * only no.
+ */
+export function foreignLeases(bundle, selfAlias, now = new Date().toISOString()) {
+  return (bundle?.leases ?? [])
+    .filter((lease) => lease.holder !== selfAlias && leaseHolds(
+      { lease_holder: lease.holder, lease_expires_at: lease.expiresAt }, now))
+    .map((lease) => ({ taskId: lease.taskId, holder: lease.holder, expiresAt: lease.expiresAt }));
+}
+
+// ------------------------------------------------------------------- bundles
+
+/**
+ * Everything this side is willing to send, already projected.
+ *
+ * The policy decides what is included; this only assembles it. Keeping those
+ * apart means a change to what may be shared is a change to one list, and the
+ * assembly cannot quietly disagree with it.
+ */
+export async function buildBundle(db, { projectId, alias, tables }) {
+  const records = {};
+  for (const table of tables) {
+    if (!isShared(table)) continue;
+    let rows;
+    try {
+      rows = await db.all(`SELECT * FROM ${table}`);
+    } catch {
+      // A table this schema version does not have is not an error: two copies
+      // of a project can be one migration apart and still exchange everything
+      // they both understand.
+      continue;
+    }
+    records[table] = rows.map((row) => project(table, row));
+  }
+
+  const leases = await db.all(
+    `SELECT a.task_id, a.lease_holder, a.lease_expires_at
+       FROM task_assignments a
+      WHERE a.active = 1 AND a.lease_holder IS NOT NULL`).catch(() => []);
+
+  return {
+    format: 1,
+    project: projectId,
+    alias,
+    writtenAt: new Date().toISOString(),
+    records,
+    leases: leases.map((l) => ({
+      taskId: l.task_id, holder: l.lease_holder, expiresAt: l.lease_expires_at,
+    })),
+  };
+}

package/src/cloud/policy.mjs

@@ -0,0 +1,115 @@
+// What may cross the boundary, and what never does. DEC-TBD-007.
+//
+// This is the one place that decides. Every other module asks it, so widening
+// what is shared is a change to this list rather than a change scattered across
+// a serializer, a merge and a report. Section 18 requires that a developer's
+// identity and a project's existence are not disclosed across an organization
+// boundary, and a rule spread over three files is a rule nobody can check.
+//
+// The list is what is allowed, never what is forbidden. A table added to the
+// schema tomorrow is not shared until somebody adds it here and says why, which
+// is the safe direction for a mistake to fall.
+
+/**
+ * Tables that travel, in dependency order so a bundle can be applied top down
+ * without a foreign key failing.
+ *
+ * Specifications, decisions and evidence, which is what a colleague needs to
+ * understand what was agreed and what proved it. Tasks travel with them because
+ * an execution contract nobody can see is not shareable work, but they travel
+ * stripped: see PERSONAL below.
+ */
+export const SHARED_TABLES = [
+  "projects",
+  "goals",
+  "milestones",
+  "modules",
+  "features",
+  "feature_flows",
+  "feature_acceptance_criteria",
+  "feature_edge_cases",
+  "workflows",
+  "workflow_steps",
+  "data_entities",
+  "data_fields",
+  "api_services",
+  "api_operations",
+  "surfaces",
+  "integrations",
+  "non_functional_requirements",
+  "schema_migrations",
+  "capability_areas",
+  "decisions",
+  "decision_links",
+  "test_plans",
+  "test_plan_cases",
+  "changes",
+  "change_targets",
+  "assumptions",
+  "tasks",
+  "task_contract_links",
+  "verification_evidence",
+];
+
+/**
+ * Tables that never travel, with the reason, so a reader can see this was
+ * decided rather than overlooked.
+ */
+export const WITHHELD = {
+  memory_entries: "A memory is one machine's recollection, not an agreed fact. DEC-TBD-007 keeps it local.",
+  memory_links: "Links into memory would describe the memory even without it.",
+  memory_search_terms: "An index of memory is memory.",
+  activity_events: "The activity trail records who did what and when, which is a working pattern.",
+  work_sessions: "A session says when a person was at their desk.",
+  developers: "A person's name and identity. Section 18 forbids disclosing it.",
+  agents: "Which harness and model somebody runs.",
+  task_assignments: "Who holds what. A lease crosses instead, carrying an alias rather than a person.",
+  branches: "Local branch names describe a working style and often a person.",
+  status_history: "A minute by minute record of how somebody worked.",
+  documents: "Generated files belong to the machine that generated them.",
+  source_material: "Intake material may contain anything the owner supplied.",
+  questions: "An open question is a conversation with the owner, not an agreed artifact.",
+  layout_positions: "Where somebody dragged a box on their own screen.",
+  sync_peers: "Who else this project syncs with. Section 18 forbids disclosing that another organization exists.",
+  sync_base: "A record of what a different peer holds.",
+  sync_conflicts: "A conflict is between two specific copies and means nothing to a third.",
+  applied_migrations: "The local schema history of one machine.",
+};
+
+/**
+ * Columns stripped from a row before it leaves, by table.
+ *
+ * A shared table can still carry a personal column. The row is worth sending
+ * and the column is not, so it is removed rather than the row withheld.
+ */
+const PERSONAL = {
+  tasks: ["assignee_developer_id", "assignee_agent_id", "branch_id", "session_id"],
+  verification_evidence: ["recorded_by", "session_id"],
+  decisions: ["accepted_by"],
+  changes: ["requested_by", "decided_by", "session_id", "task_id"],
+  assumptions: ["recorded_by", "session_id"],
+  capability_areas: ["owner"],
+};
+
+/** Whether a table is shared at all. */
+export const isShared = (table) => SHARED_TABLES.includes(table);
+
+/**
+ * A row as it may leave this machine.
+ *
+ * Unknown columns are kept: a column added to a shared table is data about the
+ * product, and treating it as personal by default would silently drop product
+ * information. Personal columns are enumerated because they are the exception
+ * and each one was a judgement somebody made.
+ */
+export function project(table, row) {
+  const strip = PERSONAL[table];
+  if (!strip) return { ...row };
+  const out = { ...row };
+  for (const column of strip) delete out[column];
+  return out;
+}
+
+/** Why a table is withheld, for a reader asking where their data went. */
+export const withheldReason = (table) =>
+  WITHHELD[table] ?? "It is not on the list of what may be shared, and the list is what is allowed rather than what is forbidden.";