@polymorphism-tech/morph-spec 8.1.1 → 8.2.0

package/src/lib/worktree/env-allocator.js

@@ -0,0 +1,149 @@
+/**
+ * env-allocator.js — deterministic per-worktree port-block allocation (fleet).
+ *
+ * Two parallel features that both start `next dev` (or `dotnet run`) collide on
+ * the same default port, and the failure is invisible until one server kills
+ * the other. Worktrees isolate files and branches, not runtime — this module
+ * closes that gap by giving every feature worktree its own stable block of
+ * ports.
+ *
+ * The registry lives at `<git-common-dir>/morph-spec/env-registry.json` — under
+ * `.git/` on purpose, for the same reasons as `finish-backup/`: it can never
+ * dirty the `git status` the worktree-finish gates read, it survives
+ * `git clean -fdx`, and the COMMON dir is the one location every linked
+ * worktree of the repo shares.
+ *
+ * Allocation is deterministic (first free index), idempotent per feature, and
+ * released only when `worktree finish` actually removed the worktree. Writes
+ * are tmp+rename so a crash never leaves a torn registry; a corrupt registry
+ * is treated as empty (fail-open — the cost is a re-allocation, never a crash).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+const DEFAULT_BASE_PORT = 4000;
+const DEFAULT_BLOCK_SIZE = 10;
+const MAX_PORT = 65535;
+
+/** Registry file path for a repo's common git dir. */
+export function registryPath(gitCommonDir) {
+  return join(gitCommonDir, 'morph-spec', 'env-registry.json');
+}
+
+function readRegistry(gitCommonDir) {
+  try {
+    const raw = readFileSync(registryPath(gitCommonDir), 'utf8').replace(/^/, '');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.allocations === 'object' && parsed.allocations !== null) {
+      return parsed;
+    }
+  } catch { /* fail-open: corrupt or absent registry restarts empty */ }
+  return { version: 1, allocations: {} };
+}
+
+function writeRegistry(gitCommonDir, registry) {
+  const path = registryPath(gitCommonDir);
+  mkdirSync(join(gitCommonDir, 'morph-spec'), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+  renameSync(tmp, path);
+}
+
+/**
+ * Read fleet overrides from the project's committed config.json.
+ * Fail-open: missing/malformed config (or a Windows BOM) → defaults.
+ *
+ * @param {string} rootPath - primary root of the project
+ * @returns {{ basePort: number, blockSize: number }}
+ */
+export function resolveFleetConfig(rootPath) {
+  const defaults = { basePort: DEFAULT_BASE_PORT, blockSize: DEFAULT_BLOCK_SIZE };
+  try {
+    const raw = readFileSync(join(rootPath, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '');
+    const cfg = JSON.parse(raw);
+    const fleet = cfg?.fleet || {};
+    return {
+      basePort: Number.isInteger(fleet.basePort) && fleet.basePort > 0 ? fleet.basePort : defaults.basePort,
+      blockSize: Number.isInteger(fleet.blockSize) && fleet.blockSize > 0 ? fleet.blockSize : defaults.blockSize,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+/**
+ * Allocate (or return the existing) port block for a feature.
+ * First-free-index policy: released slots are reused, so long-lived repos
+ * don't creep toward the port ceiling.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string, basePort?: number, blockSize?: number }} opts
+ * @returns {{ index: number, base: number, range: [number, number], created: boolean }}
+ */
+export function allocateEnvBlock(feature, { gitCommonDir, basePort = DEFAULT_BASE_PORT, blockSize = DEFAULT_BLOCK_SIZE }) {
+  const registry = readRegistry(gitCommonDir);
+
+  const existing = registry.allocations[feature];
+  if (existing && Number.isInteger(existing.index)) {
+    const base = basePort + existing.index * blockSize;
+    return { index: existing.index, base, range: [base, base + blockSize - 1], created: false };
+  }
+
+  const used = new Set(
+    Object.values(registry.allocations)
+      .map((a) => a?.index)
+      .filter((i) => Number.isInteger(i)),
+  );
+  let index = 0;
+  while (used.has(index)) index += 1;
+
+  const base = basePort + index * blockSize;
+  if (base + blockSize - 1 > MAX_PORT) {
+    throw new Error(`env-allocator: port block ${base}-${base + blockSize - 1} exceeds ${MAX_PORT}`);
+  }
+
+  registry.allocations[feature] = { index, base, createdAt: new Date().toISOString() };
+  writeRegistry(gitCommonDir, registry);
+  return { index, base, range: [base, base + blockSize - 1], created: true };
+}
+
+/**
+ * Release a feature's block. Returns false when nothing was allocated.
+ *
+ * @param {string} feature
+ * @param {{ gitCommonDir: string }} opts
+ * @returns {boolean}
+ */
+export function releaseEnvBlock(feature, { gitCommonDir }) {
+  const registry = readRegistry(gitCommonDir);
+  if (!registry.allocations[feature]) return false;
+  delete registry.allocations[feature];
+  writeRegistry(gitCommonDir, registry);
+  return true;
+}
+
+/**
+ * Render the `.morph/worktree.env` contents for a block, stack-aware.
+ * `PORT` covers next/vite/node dev servers; dotnet gets its own URL on base+1
+ * so a full-stack worktree runs web and api side by side inside one block.
+ *
+ * @param {string} feature
+ * @param {{ base: number, range: [number, number] }} block
+ * @param {string} [stack] - config.json `project.stack` (e.g. "nextjs+dotnet")
+ * @returns {string}
+ */
+export function buildEnvFileContent(feature, block, stack = '') {
+  const lines = [
+    `# Managed by morph-spec — fleet env desta worktree (feature: ${feature}).`,
+    '# Derivado e local: nunca commitar, nunca editar à mão (regenerado pelo worktree setup).',
+    `MORPH_FEATURE=${feature}`,
+    `MORPH_PORT_BASE=${block.base}`,
+    `MORPH_PORT_RANGE=${block.range[0]}-${block.range[1]}`,
+    `PORT=${block.base}`,
+  ];
+  if (/\bdotnet\b/i.test(String(stack))) {
+    lines.push(`ASPNETCORE_URLS=http://localhost:${block.base + 1}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/lib/worktree/fleet-scanner.js

@@ -0,0 +1,156 @@
+/**
+ * fleet-scanner.js — aggregate view of every active feature across the fleet.
+ *
+ * A fleet is N Claude Code instances, one per feature worktree, plus whatever
+ * is active in the primary root. Each instance only sees its own cwd; the
+ * operator loses track of "what is each session doing, what is waiting on me".
+ * This scanner answers that from the primary root's vantage point: one entry
+ * per active feature, worktree or root-resident, with the operational facts
+ * (phase, pending gates, task counts, port block, handoff freshness, last
+ * commit, dirtiness) resolved per entry.
+ *
+ * Read-only and fail-open per FIELD: a corrupt feature.json or a git hiccup
+ * nulls that field, never the scan.
+ */
+
+import { execSync, execFileSync } from 'child_process';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { isGitRepo, resolvePrimaryRoot, parseWorktreeList } from '../../commands/project/worktree.js';
+import { registryPath, resolveFleetConfig } from './env-allocator.js';
+import {
+  getFeature,
+  derivePhaseForFeature,
+  getPendingGates,
+} from '../../../framework/hooks/shared/state-reader.js';
+
+function taskCounts(featureDir) {
+  try {
+    const data = JSON.parse(readFileSync(join(featureDir, '2-plan', 'tasks.json'), 'utf8'));
+    if (!Array.isArray(data.tasks)) return null;
+    return { done: data.tasks.filter((t) => t.status === 'done').length, total: data.tasks.length };
+  } catch {
+    return null;
+  }
+}
+
+function handoffInfo(featureDir) {
+  try {
+    const path = join(featureDir, 'handoff.md');
+    if (!existsSync(path)) return { exists: false, generatedAt: null };
+    const generatedAt = readFileSync(path, 'utf8').match(/gerado em (\d{4}-\d{2}-\d{2}T[\d:.]+Z)/)?.[1] || null;
+    return { exists: true, generatedAt };
+  } catch {
+    return { exists: false, generatedAt: null };
+  }
+}
+
+function lastCommitRelative(root, branch) {
+  try {
+    return execFileSync('git', ['log', '-1', '--format=%cr', branch], { cwd: root, stdio: 'pipe' })
+      .toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function dirtyCount(worktreePath) {
+  try {
+    const out = execFileSync('git', ['status', '--porcelain'], { cwd: worktreePath, stdio: 'pipe' }).toString();
+    return out.split('\n').filter((l) => l.trim()).length;
+  } catch {
+    return null;
+  }
+}
+
+function buildEntry(feature, { location, path, branch, root, allocations, blockSize }) {
+  let workType = null;
+  let status = 'unknown';
+  let phase = 'proposal';
+  let pendingGates = [];
+  try {
+    const fj = getFeature(feature, path);
+    workType = fj?.workType || null;
+    status = fj?.status || 'unknown';
+    phase = derivePhaseForFeature(feature, path);
+    pendingGates = getPendingGates(feature, path);
+  } catch { /* field-level fail-open */ }
+
+  const featureDir = join(path, '.morph', 'features', feature);
+  const alloc = allocations[feature];
+  return {
+    feature,
+    workType,
+    phase,
+    status,
+    pendingGates,
+    location,
+    path,
+    branch,
+    tasks: taskCounts(featureDir),
+    env: alloc && Number.isInteger(alloc.base)
+      ? { base: alloc.base, range: [alloc.base, alloc.base + blockSize - 1] }
+      : null,
+    handoff: handoffInfo(featureDir),
+    lastCommit: location === 'worktree' && branch ? lastCommitRelative(root, branch) : null,
+    dirty: location === 'worktree' ? dirtyCount(path) : null,
+  };
+}
+
+/**
+ * Scan the fleet from anywhere inside the repo.
+ *
+ * @param {string} [cwd]
+ * @returns {{ root: string, entries: object[] }}
+ */
+export function scanFleet(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) {
+    return { root: resolve(cwd).replace(/\\/g, '/'), entries: [] };
+  }
+  const root = resolvePrimaryRoot(cwd);
+
+  let allocations = {};
+  try {
+    const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
+    if (common) {
+      const reg = JSON.parse(readFileSync(registryPath(resolve(root, common)), 'utf8'));
+      if (reg && typeof reg.allocations === 'object' && reg.allocations !== null) allocations = reg.allocations;
+    }
+  } catch { /* no registry yet — env stays null per entry */ }
+  const { blockSize } = resolveFleetConfig(root);
+
+  const entries = [];
+  const inWorktree = new Set();
+
+  for (const e of parseWorktreeList(root)) {
+    const m = e.branch && e.branch.match(/^refs\/heads\/morph\/(.+)$/);
+    if (!m) continue; // primary root entry and non-morph worktrees
+    inWorktree.add(m[1]);
+    entries.push(buildEntry(m[1], {
+      location: 'worktree',
+      path: e.path,
+      branch: e.branch.replace(/^refs\/heads\//, ''),
+      root,
+      allocations,
+      blockSize,
+    }));
+  }
+
+  // Root-resident features (no live worktree): whatever has a feature.json.
+  try {
+    const featuresDir = join(root, '.morph', 'features');
+    if (existsSync(featuresDir)) {
+      const names = readdirSync(featuresDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .filter((name) => !inWorktree.has(name) && existsSync(join(featuresDir, name, 'feature.json')));
+      for (const name of names) {
+        entries.push(buildEntry(name, {
+          location: 'root', path: root, branch: null, root, allocations, blockSize,
+        }));
+      }
+    }
+  } catch { /* fail-open */ }
+
+  return { root, entries };
+}

package/src/lib/context/context-builder.js

@@ -1,289 +0,0 @@
-/**
- * @fileoverview Context-Aware Dispatch — Agent Context Builder
- *
- * Assembles curated context payloads per agent, based on domain persona,
- * phase, and active task. Agents get only what they need — not everything.
- *
- * @module context-builder
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
-const STANDARDS_JSON_PATH = join(__dirname, '../../../framework/standards/STANDARDS.json');
-
-let _agentsCache = null;
-let _standardsCache = null;
-
-function loadAgents() {
-  if (_agentsCache) return _agentsCache;
-  if (!existsSync(AGENTS_JSON_PATH)) return { agents: {} };
-  try {
-    _agentsCache = JSON.parse(readFileSync(AGENTS_JSON_PATH, 'utf8'));
-    return _agentsCache;
-  } catch { return { agents: {} }; }
-}
-
-function loadStandards() {
-  if (_standardsCache) return _standardsCache;
-  if (!existsSync(STANDARDS_JSON_PATH)) return { standards: [] };
-  try {
-    _standardsCache = JSON.parse(readFileSync(STANDARDS_JSON_PATH, 'utf8'));
-    return _standardsCache;
-  } catch { return { standards: [] }; }
-}
-
-/** Max chars for spec content (flat — v5 has no tier hierarchy) */
-const SPEC_BUDGET = 8000;
-
-/** Max number of standard digests */
-const STANDARDS_BUDGET = 10;
-
-/**
- * Context assembly rules by phase.
- * Controls which context sections are included.
- */
-const PHASE_CONTEXT_PROFILES = {
-  proposal: {
-    includeSpec: false,
-    includeStandards: false,
-    includeTask: false,
-    includeCodePaths: false,
-    includePhaseArtifacts: false,
-  },
-  uiux: {
-    includeSpec: false,
-    includeStandards: true,
-    includeTask: false,
-    includeCodePaths: false,
-    includePhaseArtifacts: false,
-  },
-  plan: {
-    includeSpec: true,
-    includeStandards: true,
-    includeTask: false,
-    includeCodePaths: false,
-    includePhaseArtifacts: true,
-  },
-  implement: {
-    includeSpec: true,
-    includeStandards: true,
-    includeTask: true,
-    includeCodePaths: true,
-    includePhaseArtifacts: false,
-  },
-  review: {
-    includeSpec: true,
-    includeStandards: true,
-    includeTask: false,
-    includeCodePaths: true,
-    includePhaseArtifacts: true,
-  },
-};
-
-/**
- * Extract only the FR sections referenced by a task.
- *
- * @param {string} specContent - Full spec.md content
- * @param {string[]} frIds - FR IDs (e.g., ['FR001', 'FR003'])
- * @returns {string} Scoped spec with only referenced FRs
- */
-export function scopeSpecToFRs(specContent, frIds) {
-  if (!frIds || frIds.length === 0 || !specContent) return specContent;
-
-  const sections = [];
-
-  // Always include overview/context sections
-  const overviewMatch = specContent.match(/^(#[^#][\s\S]*?)(?=\n##\s+FR\d)/m);
-  if (overviewMatch) {
-    sections.push(overviewMatch[1].trim());
-  }
-
-  // Extract each referenced FR section
-  for (const frId of frIds) {
-    const pattern = new RegExp(
-      `(##\\s+${frId}[:\\s—–\\-][\\s\\S]*?)(?=\\n##\\s+FR\\d|\\n##\\s+[^F]|$)`,
-      'm'
-    );
-    const match = pattern.exec(specContent);
-    if (match) {
-      sections.push(match[1].trim());
-    }
-  }
-
-  return sections.length > 0 ? sections.join('\n\n---\n\n') : specContent;
-}
-
-/**
- * Build standard digests for an agent based on their standards[] array.
- *
- * @param {string} agentId - Agent ID from agents.json
- * @returns {string[]} Array of digest paragraphs
- */
-export function buildAgentDigests(agentId) {
-  const agents = loadAgents();
-  const agentData = agents.agents?.[agentId];
-  if (!agentData?.standards || agentData.standards.length === 0) return [];
-
-  const standards = loadStandards();
-  const standardsList = standards.standards || [];
-
-  const digests = [];
-  for (const stdId of agentData.standards) {
-    const std = standardsList.find(s => s.id === stdId);
-    if (std?.digest) {
-      digests.push(`[${std.id}] ${std.name}: ${std.digest}`);
-    }
-  }
-
-  return digests;
-}
-
-/**
- * Extract FR IDs referenced by a task. Reads `[FR001, FR003]` markers from the
- * task title and any `FR...` references in the task description/body.
- *
- * @param {string} taskTitle - Task title that may contain [FR...] references
- * @param {string} [taskBlock] - Task description/body for further references
- * @returns {string[]}
- */
-export function extractFRIds(taskTitle, taskBlock) {
-  const frIds = new Set();
-
-  // From title: [FR001, FR003]
-  const titleMatch = (taskTitle || '').match(/\[([^\]]*FR\d+[^\]]*)\]/);
-  if (titleMatch) {
-    const matches = titleMatch[1].match(/FR\d+/g);
-    if (matches) matches.forEach(id => frIds.add(id));
-  }
-
-  // From body: **FRs:** FR001, FR002
-  if (taskBlock) {
-    const bodyMatch = taskBlock.match(/\*\*FRs?:\*\*\s*(.+)/i);
-    if (bodyMatch) {
-      const matches = bodyMatch[1].match(/FR\d+/g);
-      if (matches) matches.forEach(id => frIds.add(id));
-    }
-  }
-
-  return [...frIds];
-}
-
-/**
- * Build a curated context payload for a specific agent.
- *
- * @param {string} agentId - Agent ID from agents.json
- * @param {Object} options
- * @param {string} options.feature - Feature name
- * @param {string} options.phase - Current phase
- * @param {string} [options.taskId] - Active task ID (implement phase)
- * @param {string} [options.projectPath='.'] - Project root
- * @returns {AgentContext}
- *
- * @typedef {Object} AgentContext
- * @property {string|null} spec - Full spec or task-scoped section
- * @property {string[]} standards - Digest paragraphs for this agent's standards
- * @property {string|null} task - Mandate task section or null
- * @property {string[]} codeContext - Relevant file paths
- * @property {string|null} phaseArtifacts - Previous phase outputs
- * @property {Object} budget - Context budget hints
- */
-export async function buildAgentContext(agentId, { feature, phase, taskId, projectPath = '.' }) {
-  const agents = loadAgents();
-  const profile = PHASE_CONTEXT_PROFILES[phase] || PHASE_CONTEXT_PROFILES.implement;
-  const maxSpecChars = SPEC_BUDGET;
-  const maxStandards = STANDARDS_BUDGET;
-
-  const result = {
-    spec: null,
-    standards: [],
-    task: null,
-    codeContext: [],
-    phaseArtifacts: null,
-    budget: { maxSpecChars, maxStandards },
-  };
-
-  // Standards digests
-  if (profile.includeStandards) {
-    result.standards = buildAgentDigests(agentId).slice(0, maxStandards);
-  }
-
-  // Spec content (scoped by task FRs when possible)
-  if (profile.includeSpec) {
-    try {
-      const specPath = getAbsoluteOutputPath(projectPath, feature, 'spec');
-      if (existsSync(specPath)) {
-        let specContent = readFileSync(specPath, 'utf8');
-
-        // If task-scoped, extract mandate section for this task
-        if (taskId) {
-          const mandatePath = getAbsoluteOutputPath(projectPath, feature, 'mandate');
-          if (existsSync(mandatePath)) {
-            try {
-              const { extractTaskSection } = await import('../../lib/generators/mandate-generator.js');
-              const section = extractTaskSection(readFileSync(mandatePath, 'utf8'), taskId);
-              if (section) {
-                result.spec = section.slice(0, maxSpecChars);
-                result.task = section;
-              }
-            } catch { /* fall through to raw spec */ }
-          }
-        }
-
-        if (!result.spec) {
-          result.spec = specContent.slice(0, maxSpecChars);
-        }
-      }
-    } catch { /* spec not available */ }
-  }
-
-  // Task mandate section
-  if (profile.includeTask && taskId && !result.task) {
-    try {
-      const mandatePath = getAbsoluteOutputPath(projectPath, feature, 'mandate');
-      if (existsSync(mandatePath)) {
-        const { extractTaskSection } = await import('../../lib/generators/mandate-generator.js');
-        const section = extractTaskSection(readFileSync(mandatePath, 'utf8'), taskId);
-        if (section) result.task = section;
-      }
-    } catch { /* mandate not available */ }
-  }
-
-  // Code paths from task
-  if (profile.includeCodePaths && taskId) {
-    try {
-      const planPath = getAbsoluteOutputPath(projectPath, feature, 'plan');
-      if (existsSync(planPath)) {
-        const planContent = readFileSync(planPath, 'utf8');
-        const backtickPaths = planContent.match(/`([^`]+\.[a-z]{1,4})`/g);
-        if (backtickPaths) {
-          result.codeContext = [...new Set(backtickPaths.map(p => p.replace(/`/g, '')))].slice(0, 20);
-        }
-      }
-    } catch { /* plan not available */ }
-  }
-
-  // Phase artifacts (decisions, previous outputs)
-  if (profile.includePhaseArtifacts) {
-    try {
-      const decisionsPath = getAbsoluteOutputPath(projectPath, feature, 'decisions');
-      if (existsSync(decisionsPath)) {
-        result.phaseArtifacts = readFileSync(decisionsPath, 'utf8').slice(0, 3000);
-      }
-    } catch { /* decisions not available */ }
-  }
-
-  return result;
-}
-
-/**
- * Invalidate module-level caches. Used in tests.
- */
-export function clearCache() {
-  _agentsCache = null;
-  _standardsCache = null;
-}