@geraldmaron/construct 1.0.11 → 1.0.14

package/lib/tracking-surfaces.mjs

@@ -0,0 +1,375 @@
+/**
+ * lib/tracking-surfaces.mjs — automated maintenance for project-tracking files.
+ *
+ * Owns WHAT to refresh; the hooks that call these functions own WHEN. Three
+ * surfaces are covered:
+ *
+ *   - `.cx/context.md` + `.cx/context.json` — project state. Refreshed from
+ *     recent observations, commits, and bead state at the end of each
+ *     session via `refreshContextMd()`.
+ *   - `plan.md` — local working plan. Bead-status table synced via
+ *     `syncPlanFile()` (thin wrapper around `syncPlanWithBeads` in
+ *     lib/beads-automation.mjs). When every referenced bead is closed,
+ *     `archivePlanIfLanded()` stamps a landed footer, copies the plan into
+ *     `.cx/handoffs/`, and resets `plan.md` to the standard template.
+ *   - Beads — `closeBeadsFromPrRefs()` parses a merged PR's body for
+ *     `Refs:` / `Closes:` / `Fixes:` lines and closes the named beads with
+ *     a "Merged via PR #N (sha)" reason.
+ *
+ * Every export is best-effort: caught failures degrade to a structured
+ * result object, never throw. Caller hooks log to stderr via logHookFailure
+ * if they care about the failure mode.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { extractBeadsFromPlan, syncPlanWithBeads } from './beads-automation.mjs';
+import { buildPlanTemplate } from './project-init-shared.mjs';
+
+const CONTEXT_RECENT_DAYS = 30;
+const CONTEXT_MAX_ITEMS_PER_SECTION = 10;
+
+const SECTION_HEADERS = {
+  activeWork: '## Active Work',
+  recentDecisions: '## Recent Decisions',
+  architectureNotes: '## Architecture Notes',
+  openQuestions: '## Open Questions',
+};
+
+// ---------------------------------------------------------------------------
+// context.md / context.json refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull recent activity from observations, git, and beads into the managed
+ * sections of `.cx/context.md`. Preserves any non-managed sections the user
+ * has authored. Stamps `.cx/context.json` with the refresh timestamp and
+ * derived counts so a session-start digest can tell when content is fresh.
+ */
+export async function refreshContextMd({ rootDir, now = new Date() } = {}) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  const contextMdPath = join(rootDir, '.cx', 'context.md');
+  const contextJsonPath = join(rootDir, '.cx', 'context.json');
+  if (!existsSync(contextMdPath)) return { ok: false, reason: 'no-context-md' };
+
+  const cutoff = new Date(now.getTime() - CONTEXT_RECENT_DAYS * 24 * 60 * 60 * 1000);
+  const observations = collectRecentObservations(rootDir, cutoff);
+  const commits = collectRecentCommits(rootDir, cutoff);
+  const closedBeads = collectRecentlyClosedBeads(rootDir, cutoff);
+  const openBeads = collectInProgressBeads(rootDir);
+
+  const sections = {
+    activeWork: formatActiveWork(openBeads),
+    recentDecisions: formatRecentDecisions(observations, commits, closedBeads),
+    architectureNotes: formatArchitectureNotes(observations),
+  };
+
+  const before = readFileSync(contextMdPath, 'utf8');
+  const after = rewriteManagedSections(before, sections);
+  if (after !== before) {
+    writeFileSync(contextMdPath, after, 'utf8');
+  }
+
+  const json = readJsonSafe(contextJsonPath) ?? { format: 'json', source: 'construct' };
+  json.lastRefreshAt = now.toISOString();
+  json.activeWork = openBeads.map((b) => ({ id: b.id, title: b.title, status: b.status }));
+  json.recentDecisions = closedBeads.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION).map((b) => ({
+    id: b.id,
+    title: b.title,
+    closedAt: b.closed || b.updated || b.updatedAt,
+  }));
+  json.architectureNotes = observations
+    .filter((o) => o.category === 'architecture' || o.category === 'decision')
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)
+    .map((o) => ({ summary: o.summary, ts: o.ts }));
+  writeFileSync(contextJsonPath, JSON.stringify(json, null, 2) + '\n', 'utf8');
+
+  return {
+    ok: true,
+    changed: after !== before,
+    counts: {
+      activeWork: openBeads.length,
+      recentDecisions: closedBeads.length,
+      observations: observations.length,
+      commits: commits.length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// plan.md sync and archive
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the existing plan↔beads sync. Wrapper so the Stop hook calls one
+ * stable name even if the underlying implementation changes later.
+ */
+export async function syncPlanFile({ rootDir }) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  try {
+    const changed = await syncPlanWithBeads({ cwd: rootDir });
+    return { ok: true, changed };
+  } catch (err) {
+    return { ok: false, reason: 'sync-threw', error: err?.message };
+  }
+}
+
+/**
+ * When every bead referenced in `plan.md` is closed AND the plan has not
+ * been touched in the last hour, stamp a "Landed" footer, copy the plan to
+ * `.cx/handoffs/<date>-plan-landed.md`, and reset `plan.md` to the template.
+ * Otherwise no-op.
+ */
+export async function archivePlanIfLanded({ rootDir, now = new Date() } = {}) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  const planPath = join(rootDir, 'plan.md');
+  if (!existsSync(planPath)) return { ok: false, reason: 'no-plan' };
+
+  let stat;
+  try { stat = statSync(planPath); }
+  catch { return { ok: false, reason: 'stat-failed' }; }
+  const ONE_HOUR_MS = 60 * 60 * 1000;
+  if (now.getTime() - stat.mtimeMs < ONE_HOUR_MS) {
+    return { ok: false, reason: 'plan-recently-touched' };
+  }
+
+  const content = readFileSync(planPath, 'utf8');
+  const beadRefs = extractBeadsFromPlan(content);
+  if (beadRefs.length === 0) return { ok: false, reason: 'no-bead-refs' };
+
+  const uniqueIds = [...new Set(beadRefs.map((b) => b.beadId))];
+  const statuses = uniqueIds.map((id) => readBeadStatus(rootDir, id));
+  if (statuses.some((s) => s !== 'closed')) {
+    return { ok: false, reason: 'beads-still-open' };
+  }
+
+  const handoffsDir = join(rootDir, '.cx', 'handoffs');
+  mkdirSync(handoffsDir, { recursive: true });
+  const date = now.toISOString().slice(0, 10);
+  const archivePath = join(handoffsDir, `${date}-plan-landed.md`);
+  const archiveBody = `# Landed plan — ${date}\n\nBeads closed: ${uniqueIds.join(', ')}\n\nArchived from \`plan.md\` on ${now.toISOString()} by the session-tracking-refresh hook.\n\n---\n\n${content}`;
+  writeFileSync(archivePath, archiveBody, 'utf8');
+
+  writeFileSync(planPath, buildPlanTemplate(), 'utf8');
+
+  return { ok: true, changed: true, archivePath, beadsClosed: uniqueIds };
+}
+
+// ---------------------------------------------------------------------------
+// Bead closure from merged PR
+// ---------------------------------------------------------------------------
+
+const PR_REFS_PATTERN = /(?:Refs|Closes?|Fixes?|Resolves?)\s*:?\s*(?:#?\d+|(?:construct-[a-z0-9]+(?:\s*,\s*construct-[a-z0-9]+)*))/gi;
+const BEAD_ID_PATTERN = /construct-[a-z0-9]+/g;
+
+/**
+ * Parse a merged PR's body for bead references and close each open one.
+ * Idempotent: skips beads already closed. Best-effort: each `bd close`
+ * failure is captured in the result, no throws.
+ *
+ * @returns {Promise<{ ok: boolean, closed: string[], skipped: string[], errors: object[] }>}
+ */
+export async function closeBeadsFromPrRefs({ prNumber, mergeCommitSha = '', cwd = process.cwd() } = {}) {
+  if (!prNumber) return { ok: false, reason: 'pr-number-required', closed: [], skipped: [], errors: [] };
+
+  const body = readPrBody(prNumber, cwd);
+  if (!body) return { ok: false, reason: 'pr-body-unavailable', closed: [], skipped: [], errors: [] };
+
+  const beadIds = new Set();
+  for (const match of body.match(PR_REFS_PATTERN) ?? []) {
+    for (const id of match.match(BEAD_ID_PATTERN) ?? []) beadIds.add(id);
+  }
+  if (beadIds.size === 0) return { ok: true, closed: [], skipped: [], errors: [] };
+
+  const closed = [];
+  const skipped = [];
+  const errors = [];
+  const reason = mergeCommitSha
+    ? `Merged via PR #${prNumber} (${mergeCommitSha.slice(0, 12)})`
+    : `Merged via PR #${prNumber}`;
+
+  for (const id of beadIds) {
+    const status = readBeadStatus(cwd, id);
+    if (status === 'closed') { skipped.push(id); continue; }
+    if (status === null) { errors.push({ id, reason: 'bd-show-failed' }); continue; }
+    try {
+      const result = spawnSync('bd', ['close', id, '--reason', reason], { cwd, encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) closed.push(id);
+      else errors.push({ id, reason: 'bd-close-failed', detail: (result.stderr || '').slice(0, 200) });
+    } catch (err) {
+      errors.push({ id, reason: 'bd-close-threw', detail: err?.message });
+    }
+  }
+
+  return { ok: true, closed, skipped, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function collectRecentObservations(rootDir, cutoff) {
+  const dir = join(rootDir, '.cx', 'observations');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      const subdir = join(dir, entry.name);
+      for (const file of safeReaddir(subdir)) {
+        const obs = readJsonSafe(join(subdir, file));
+        if (!obs) continue;
+        const ts = obs.timestamp || obs.ts;
+        if (!ts || new Date(ts) < cutoff) continue;
+        out.push({ ...obs, ts });
+      }
+    } else if (entry.name.endsWith('.json') || entry.name.endsWith('.jsonl')) {
+      const obs = readJsonSafe(join(dir, entry.name));
+      if (!obs) continue;
+      const ts = obs.timestamp || obs.ts;
+      if (!ts || new Date(ts) < cutoff) continue;
+      out.push({ ...obs, ts });
+    }
+  }
+  out.sort((a, b) => new Date(b.ts) - new Date(a.ts));
+  return out;
+}
+
+function collectRecentCommits(rootDir, cutoff) {
+  try {
+    const result = spawnSync('git', ['log', '--since', cutoff.toISOString(), '--pretty=format:%H|%s|%cI'], {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: 3000,
+    });
+    if (result.status !== 0) return [];
+    return result.stdout.split('\n').filter(Boolean).map((line) => {
+      const [sha, subject, committerDate] = line.split('|');
+      return { sha, subject, committerDate };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function collectRecentlyClosedBeads(rootDir, cutoff) {
+  const beads = runBdListJson(rootDir, ['list', '--status', 'closed', '--json']);
+  return beads
+    .filter((b) => {
+      const ts = b.closed || b.updated || b.updatedAt;
+      return ts && new Date(ts) >= cutoff;
+    })
+    .sort((a, b) => new Date(b.closed || b.updated || b.updatedAt) - new Date(a.closed || a.updated || a.updatedAt));
+}
+
+function collectInProgressBeads(rootDir) {
+  return runBdListJson(rootDir, ['list', '--status', 'in_progress', '--json']);
+}
+
+function runBdListJson(rootDir, args) {
+  try {
+    const result = spawnSync('bd', args, { cwd: rootDir, encoding: 'utf8', timeout: 5000 });
+    if (result.status !== 0) return [];
+    const parsed = JSON.parse(result.stdout);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && Array.isArray(parsed.issues)) return parsed.issues;
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+function readBeadStatus(cwd, id) {
+  try {
+    const result = spawnSync('bd', ['show', id, '--json'], { cwd, encoding: 'utf8', timeout: 3000 });
+    if (result.status !== 0) return null;
+    const parsed = JSON.parse(result.stdout);
+    return parsed?.status || null;
+  } catch {
+    return null;
+  }
+}
+
+function readPrBody(prNumber, cwd) {
+  try {
+    const result = spawnSync('gh', ['pr', 'view', String(prNumber), '--json', 'body'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    if (result.status !== 0) return null;
+    const parsed = JSON.parse(result.stdout);
+    return parsed?.body || null;
+  } catch {
+    return null;
+  }
+}
+
+function safeReaddir(dir) {
+  try { return readdirSync(dir); }
+  catch { return []; }
+}
+
+function readJsonSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return null; }
+}
+
+function formatActiveWork(openBeads) {
+  if (openBeads.length === 0) return '_None in progress._';
+  return openBeads
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)
+    .map((b) => `- **${b.id}** · ${b.title}`)
+    .join('\n');
+}
+
+function formatRecentDecisions(observations, commits, closedBeads) {
+  const items = [];
+  for (const bead of closedBeads.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- closed **${bead.id}** · ${bead.title}`);
+  }
+  for (const commit of commits.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- commit \`${commit.sha.slice(0, 10)}\` — ${commit.subject}`);
+  }
+  for (const obs of observations.filter((o) => o.category === 'decision').slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- decision — ${obs.summary}`);
+  }
+  if (items.length === 0) return '_No recent decisions captured._';
+  return items.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION * 2).join('\n');
+}
+
+function formatArchitectureNotes(observations) {
+  const arch = observations
+    .filter((o) => o.category === 'architecture' || /architect|contract|boundary|invariant/i.test(o.summary || ''))
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION);
+  if (arch.length === 0) return '_No new architecture notes._';
+  return arch.map((o) => `- ${o.summary}`).join('\n');
+}
+
+function rewriteManagedSections(content, sections) {
+  let out = content;
+  for (const [key, header] of Object.entries(SECTION_HEADERS)) {
+    if (!(key in sections)) continue;
+    const body = sections[key];
+    out = replaceSection(out, header, body);
+  }
+  return out;
+}
+
+function replaceSection(content, header, body) {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex((l) => l.trim() === header);
+  if (startIdx === -1) return content;
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ') && lines[i].trim() !== header) {
+      endIdx = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, startIdx + 1);
+  const after = lines.slice(endIdx);
+  return [...before, '', body, '', ...after].join('\n');
+}

package/lib/worker/trace.mjs

@@ -26,15 +26,29 @@
  *   memory.written         — durable memory record persisted
  */
 
-import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
 import { createTelemetryClient } from '../telemetry/client.mjs';
 import { ensureCxDir } from '../project-init-shared.mjs';
+import { appendWithRotationSync } from '../logging/rotate.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
+// GitHub rejects single files > 100 MB. Keep every trace shard strictly
+// under 100 MB so an accidental commit + push doesn't brick the repo. Cap
+// is configurable via CONSTRUCT_TRACE_MAX_MB; default 100. Override of 0
+// disables rotation entirely (not recommended).
+
+function traceMaxBytes(env = process.env) {
+  const raw = env.CONSTRUCT_TRACE_MAX_MB;
+  if (raw === undefined) return 100 * 1024 * 1024;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
+  return Math.floor(parsed * 1024 * 1024);
+}
+
 export const TRACE_EVENT_TYPES = [
   'daemon.started',
   'daemon.heartbeat',
@@ -168,7 +182,10 @@ export function emitTraceEvent({
     metadata,
     createdAt: new Date().toISOString(),
   };
-  appendFileSync(path.join(dir, `${todayShard()}.jsonl`), `${JSON.stringify(event)}\n`, 'utf8');
+  const shardPath = path.join(dir, `${todayShard()}.jsonl`);
+  appendWithRotationSync(shardPath, `${JSON.stringify(event)}\n`, {
+    maxBytes: traceMaxBytes(env),
+  });
 
   // Fire-and-forget export to the configured remote adapter. Silent no-op when not configured.
   exportToRemote(event, env, rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.11",
+  "version": "1.0.14",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -27,6 +27,10 @@
   "engines": {
     "node": ">=20"
   },
+  "workspaces": [
+    "apps/*",
+    "packages/*"
+  ],
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -42,7 +46,7 @@
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "node --test --test-timeout=30000 tests/functional/*.functional.test.mjs",
+    "test:functional": "node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node lib/init-docs.mjs --yes",
     "docs:update": "node ./bin/construct docs:update",

package/platforms/claude/settings.template.json

@@ -14,19 +14,7 @@
           }
         ],
         "id": "session:start",
-        "description": "Load prior project context and git status at session start"
-      },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/env-check.mjs\"",
-            "timeout": 5
-          }
-        ],
-        "id": "session:env-check",
-        "description": "Warn about missing required env vars at session open"
+        "description": "Load prior project context, git status, and missing-env-var notice at session start"
       }
     ],
     "PreToolUse": [
@@ -215,19 +203,6 @@
         "id": "post:edit:dep-audit",
         "description": "Audit dependencies for vulnerabilities after manifest changes"
       },
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$HOME/.construct/lib/hooks/read-tracker.mjs\"",
-            "timeout": 3,
-            "async": true
-          }
-        ],
-        "id": "post:read-tracker",
-        "description": "Record file content hash after Read for staleness detection in edit-guard"
-      },
       {
         "matcher": "Read",
         "hooks": [
@@ -239,7 +214,7 @@
           }
         ],
         "id": "post:audit-reads",
-        "description": "Tamper-evident chain log of every Read tool call. Off by default — enable with CONSTRUCT_AUDIT_READS=1."
+        "description": "Update file-hashes.json for edit-guard staleness detection on every Read; optionally write a tamper-evident audit chain when CONSTRUCT_AUDIT_READS=1."
       },
       {
         "matcher": "mcp__.*",
@@ -305,6 +280,19 @@
         "id": "post:bash:post-merge-docs-check",
         "description": "Emit doc-drift events when a merge lands without matching docs/CHANGELOG updates"
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/post-merge-tracking.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "post:bash:post-merge-tracking",
+        "description": "After `gh pr merge` succeeds, parse the PR body's Refs/Closes/Fixes lines and close every referenced construct-XXX bead so plan.md and .cx/context.md don't drift behind merged work"
+      },
       {
         "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
         "hooks": [
@@ -473,6 +461,19 @@
         ],
         "id": "stop:auto-reflect",
         "description": "Deterministic session-end reflect: extracts a transcript summary into .cx/observations (500ms hard budget; CONSTRUCT_REFLECT_AUTO=off to disable)"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/session-tracking-refresh.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "stop:tracking-refresh",
+        "description": "Auto-refresh .cx/context.{md,json} from recent observations + commits + closed beads; sync plan.md bead-status table; archive plan.md to .cx/handoffs/ when all referenced beads are closed"
       }
     ],
     "UserPromptSubmit": [