@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/runtime.js

@@ -0,0 +1,219 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const pkg = require('../package.json');
+
+function projectRoot(cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, '.code-flow/config.yml'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error('Run code-flow inside an initialized project.');
+    current = parent;
+  }
+}
+
+function commands(root) {
+  const registry = JSON.parse(fs.readFileSync(path.join(root, '.code-flow/runtime-commands.json'), 'utf8'));
+  if (registry.schema_version !== 1) throw new Error('Unsupported runtime command contract.');
+  return registry.commands;
+}
+
+function projectCommandFamily(name) {
+  if (!name || name.startsWith('-')) return false;
+  let current = path.resolve(process.cwd());
+  while (true) {
+    if (fs.existsSync(path.join(current, '.code-flow/runtime-commands.json'))) {
+      try {
+        return Object.keys(commands(current)).some(command => command.split(' ')[0] === name);
+      } catch (error) {
+        process.stderr.write(`code-flow contract: ${error.message}\n`);
+        return false;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+function versionRepair(root) {
+  const file = path.join(root, '.code-flow/.version');
+  if (fs.existsSync(file)) {
+    const version = fs.readFileSync(file, 'utf8').trim();
+    if (/^\d+\.\d+\.\d+$/.test(version)) {
+      const installed = version.split('.').map(Number);
+      const current = pkg.version.split('.').map(Number);
+      const index = installed.findIndex((value, position) => value !== current[position]);
+      if (index >= 0 && installed[index] > current[index]) {
+        return `CLI ${pkg.version} is older than project runtime ${version}. Upgrade the CLI: npm install --global ${pkg.name}@${version}`;
+      }
+    }
+  }
+  return 'code-flow migrate --runtime --dry-run';
+}
+
+function digest(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function artifactDigest(relative, source) {
+  if (relative !== '.opencode/plugins/code-flow/package.json') return digest(source);
+  const data = JSON.parse(fs.readFileSync(source, 'utf8'));
+  data.version = pkg.version;
+  return crypto.createHash('sha256').update(JSON.stringify(data, null, 2) + '\n').digest('hex');
+}
+
+function filesUnder(directory, prefix) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    if (entry.name === '__pycache__' || entry.name === '.DS_Store') return [];
+    const relative = path.posix.join(prefix, entry.name);
+    return entry.isDirectory() ? filesUnder(path.join(directory, entry.name), relative) : [relative];
+  });
+}
+
+function artifactSources(platforms) {
+  const base = path.join(__dirname, 'core/code-flow');
+  const sources = { '.code-flow/runtime-commands.json': path.join(base, 'runtime-commands.json') };
+  for (const relative of filesUnder(path.join(base, 'scripts'), 'scripts')) {
+    sources[`.code-flow/${relative}`] = path.join(base, relative);
+  }
+  for (const platform of platforms) {
+    const adapter = path.join(__dirname, 'adapters', platform);
+    const area = platform === 'codex' ? 'skills' : 'commands';
+    const destination = platform === 'codex' ? '.agents' : `.${platform}`;
+    for (const relative of filesUnder(path.join(adapter, area), area)) {
+      sources[`${destination}/${relative}`] = path.join(adapter, relative);
+    }
+    if (platform === 'opencode') {
+      for (const relative of filesUnder(path.join(adapter, 'plugins'), 'plugins')) {
+        sources[`.opencode/${relative}`] = path.join(adapter, relative);
+      }
+    }
+  }
+  return sources;
+}
+
+function hookContracts(platforms) {
+  const contracts = {};
+  for (const platform of platforms.filter(value => value !== 'opencode')) {
+    const name = platform === 'codex' ? 'hooks.json' : 'settings.local.json';
+    const source = path.join(__dirname, 'adapters', platform, name);
+    contracts[`.${platform}/${name}`] = JSON.parse(fs.readFileSync(source, 'utf8')).hooks;
+  }
+  return contracts;
+}
+
+function writeInstall(root, platforms) {
+  const files = Object.fromEntries(Object.entries(artifactSources(platforms))
+    .map(([relative, source]) => [relative, artifactDigest(relative, source)]));
+  const manifest = { schema_version: 1, version: pkg.version, platforms,
+    files, hook_contracts: hookContracts(platforms) };
+  const target = path.join(root, '.code-flow/.runtime-install.json');
+  fs.writeFileSync(`${target}.tmp`, JSON.stringify(manifest, null, 2) + '\n');
+  fs.renameSync(`${target}.tmp`, target);
+}
+
+function verifyHooks(root, contracts) {
+  for (const [relative, expected] of Object.entries(contracts)) {
+    const actual = JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8')).hooks;
+    for (const [event, groups] of Object.entries(expected)) {
+      for (const group of groups) {
+        const candidates = (actual[event] || []).filter(item => (item.matcher || '') === (group.matcher || ''));
+        for (const hook of group.hooks) {
+          if (!candidates.some(item => item.hooks.some(value => JSON.stringify(value) === JSON.stringify(hook)))) {
+            throw new Error(`Managed hook has drifted: ${relative}:${event}`);
+          }
+        }
+      }
+    }
+  }
+}
+
+function verify(root, duringMigration = false) {
+  if (!duringMigration && fs.existsSync(path.join(root, '.code-flow/.runtime-migration.lock'))) {
+    throw new Error('Runtime migration is in progress or needs recovery.');
+  }
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, '.code-flow/.runtime-install.json'), 'utf8'));
+  const version = fs.readFileSync(path.join(root, '.code-flow/.version'), 'utf8').trim();
+  if (manifest.schema_version !== 1 || manifest.version !== version || version !== pkg.version) {
+    throw new Error(`Runtime ${version} and CLI ${pkg.version} versions differ.`);
+  }
+  if (!manifest.files || Object.keys(manifest.files).length === 0 || !manifest.hook_contracts) {
+    throw new Error('Runtime installation manifest is incomplete.');
+  }
+  const expected = artifactSources(manifest.platforms);
+  if (Object.keys(expected).length !== Object.keys(manifest.files).length) {
+    throw new Error('Installed artifact set differs from the CLI contract.');
+  }
+  for (const [relative, source] of Object.entries(expected)) {
+    if (manifest.files[relative] !== artifactDigest(relative, source)) {
+      throw new Error(`Installed contract differs from the CLI package: ${relative}`);
+    }
+  }
+  for (const [relative, hash] of Object.entries(manifest.files)) {
+    const target = path.resolve(root, relative);
+    if (!target.startsWith(root + path.sep) || digest(target) !== hash) {
+      throw new Error(`Managed runtime artifact has drifted: ${relative}`);
+    }
+  }
+  verifyHooks(root, manifest.hook_contracts);
+}
+
+function execute(root, contract, values, scripts = path.join(root, '.code-flow/scripts')) {
+  try {
+    if (values.length === 1 || (values.length === 2 && ['--help', '-h'].includes(values[1]))) {
+      const family = Object.keys(contract).filter(command => command.startsWith(values[0] + ' '));
+      if (family.length) {
+        process.stdout.write(`Usage:\n${family.map(command => `  code-flow ${command} [options]`).join('\n')}\nUse <command> --help for its actual parameters.\n`);
+        return 0;
+      }
+    }
+    const key = Object.keys(contract).sort((a, b) => b.length - a.length)
+      .find(command => command.split(' ').every((part, index) => values[index] === part));
+    if (!key) throw new Error(`Unknown runtime command. Available: ${Object.keys(contract).join(', ')}`);
+    const entry = contract[key];
+    if (!/^cf_[a-z_]+$/.test(entry.module)) throw new Error('Invalid runtime module in command contract.');
+    const script = path.join(scripts, `${entry.module}.py`);
+    const args = [...entry.prefix, ...values.slice(key.split(' ').length)];
+    const publicName = entry.prefix.length ? key.split(' ').slice(0, -entry.prefix.length).join(' ') : key;
+    const result = spawnSync('python3', [script, ...args], {
+      cwd: root, stdio: 'inherit', env: { ...process.env,
+        CF_RUNTIME_COMMAND: `code-flow ${publicName}`, CF_RUNTIME_ACTION: entry.prefix.join(' '),
+        CF_CLI_VERSION: pkg.version },
+    });
+    if (result.error) throw result.error;
+    return result.status === null ? 2 : result.status;
+  } catch (error) {
+    process.stderr.write(`code-flow runtime: ${error.message}\n`);
+    return 2;
+  }
+}
+
+function run(values) {
+  let root;
+  try {
+    root = projectRoot(process.cwd());
+  } catch (error) {
+    process.stderr.write(`code-flow runtime: ${error.message}\n`);
+    return 3;
+  }
+  try {
+    if (values[0] === 'spec' && values[1] === 'doctor') {
+      const base = path.join(__dirname, 'core/code-flow');
+      const contract = JSON.parse(fs.readFileSync(path.join(base, 'runtime-commands.json'), 'utf8')).commands;
+      return execute(root, { 'spec doctor': contract['spec doctor'] }, values, path.join(base, 'scripts'));
+    }
+    verify(root);
+    return execute(root, commands(root), values);
+  } catch (error) {
+    process.stderr.write(`code-flow installation: ${error.message}\nRepair: ${versionRepair(root)}\n`);
+    return 3;
+  }
+}
+
+module.exports = { artifactSources, commands, digest, hookContracts, projectCommandFamily, projectRoot, run, verify, writeInstall };

package/src/core/code-flow/scripts/cf_acceptance_evidence.py

@@ -1,100 +0,0 @@
-"""Append execution history without erasing the user's acceptance contract."""
-from __future__ import annotations
-
-import json
-import re
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Mapping, Sequence
-from uuid import uuid4
-
-STATES = frozenset(("planned", "pending", "tbd", "verified", "unverified", "failed", "incomplete", "not_configured", "e2e_deferred", "manual_pending"))
-
-
-def scenario_line(line: str, scenario_id: str) -> bool:
-    return bool(re.match(rf"^\s*(?:\|\s*|[-*]\s+){re.escape(scenario_id)}(?=\s*[:|])", line))
-
-
-def line_status(line: str, scenario_id: str) -> str:
-    if not scenario_line(line, scenario_id):
-        return ""
-    if line.lstrip().startswith("|"):
-        cells = [cell.strip().lower() for cell in line.strip().strip("|").split("|")]
-        return next((cell for cell in reversed(cells) if cell in STATES), "")
-    match = re.match(r"^\s*[-*]\s+[^:]+:\s*([a-z0-9_]+)\b", line, re.I)
-    return match.group(1).lower() if match and match.group(1).lower() in STATES else ""
-
-
-def _status_line(line: str, scenario_id: str, status: str) -> str:
-    if not scenario_line(line, scenario_id):
-        return line
-    if line.lstrip().startswith("|"):
-        cells = line.split("|")
-        for index in range(len(cells) - 1, 0, -1):
-            if cells[index].strip().lower() in STATES:
-                cells[index] = f" {status} "
-                return "|".join(cells)
-        return line.rstrip().rstrip("|") + f"| {status} |"
-    prefix = r"(^\s*[-*]\s+[^:]+:\s*)"
-    if line_status(line, scenario_id):
-        return re.sub(prefix + r"(?:" + "|".join(sorted(STATES)) + r")\b", rf"\g<1>{status}", line, count=1, flags=re.I)
-    return re.sub(prefix, rf"\g<1>{status} — ", line, count=1)
-
-
-def _patch_section(section: str, scenario_id: str, status: str, record: str) -> str:
-    contract = re.search(r"(?ms)^### Acceptance Contract[^\n]*\n(.*?)(?=^### |^## |\Z)", section)
-    if contract:
-        body = "\n".join(_status_line(line, scenario_id, status) for line in contract.group(1).splitlines()) + "\n"
-        section = section[:contract.start(1)] + body + section[contract.end(1):]
-    evidence = re.search(r"(?ms)^### Acceptance Evidence[^\n]*\n(.*?)(?=^### |^## |\Z)", section)
-    if evidence:
-        body = evidence.group(1)
-        if record not in body.splitlines():
-            body = body.rstrip() + "\n" + record + "\n\n"
-        section = section[:evidence.start(1)] + body + section[evidence.end(1):]
-    else:
-        section = section.rstrip() + "\n\n### Acceptance Evidence\n" + record + "\n"
-    return section
-
-
-def sync_task_evidence(task: Path, scenario_id: str, confirmed_by: str, evidence: str, owner: str = "", status: str = "verified") -> None:
-    text = task.read_text(encoding="utf-8")
-    task_pattern = re.escape(owner) if owner else r"TASK-\d+"
-    match = re.search(rf"(?ms)^##\s+{task_pattern}:.*?(?=^## |\Z)", text)
-    if match is None:
-        raise ValueError(f"acceptance owner missing: {owner}")
-    record = f"- {scenario_id}: {status} — {evidence} (confirmed_by: {confirmed_by})"
-    section = _patch_section(match.group(0), scenario_id, status, record)
-    text = text[:match.start()] + section + text[match.end():]
-    coverage = re.search(r"(?ms)^## Acceptance Coverage[^\n]*\n(.*?)(?=^## |\Z)", text)
-    if coverage:
-        body = "\n".join(_status_line(line, scenario_id, status) for line in coverage.group(1).splitlines()) + "\n"
-        text = text[:coverage.start(1)] + body + text[coverage.end(1):]
-    from cf_spec_context import _atomic_text
-    _atomic_text(task, text)
-
-
-def persist_results(path: Path, data: dict[str, object], results: Sequence[Mapping[str, object]]) -> None:
-    rows = {row["id"]: row for row in data["scenarios"]}
-    run_id, executed_at = uuid4().hex, datetime.now(timezone.utc).isoformat()
-    updates = []
-    for result in results:
-        state = str(result["status"])
-        if state in ("not_included", "manual_pending"):
-            continue
-        row = rows[result["id"]]
-        row["revision"] = int(row.get("revision", 0)) + 1
-        status = "verified" if state == "passed" else state
-        row["status"] = status
-        record = {**result, "revision": row["revision"], "run_id": run_id, "executed_at": executed_at}
-        row["evidence"] = record
-        row.setdefault("runs", []).append(record)
-        updates.append((row, record, status))
-    from cf_spec_context import _atomic_text
-    _atomic_text(path, json.dumps(data, ensure_ascii=False, indent=2) + "\n")
-    task_name = data.get("task_file")
-    if isinstance(task_name, str) and task_name:
-        task = Path(task_name) if Path(task_name).is_absolute() else path.parent / task_name
-        for row, record, status in updates:
-            detail = f"automated command {record['status']}; run_id={run_id}"
-            sync_task_evidence(task, str(row["id"]), "runner", detail, str(row.get("owner", "")), status)

package/src/core/code-flow/scripts/cf_acceptance_schema.py

@@ -1,83 +0,0 @@
-"""Validated acceptance records shared by execution and lifecycle gates."""
-from __future__ import annotations
-
-import json
-import math
-from pathlib import Path
-from typing import Mapping
-
-
-def verified_evidence(row: Mapping[str, object]) -> bool:
-    evidence = row.get("evidence")
-    if row.get("status") != "verified" or not isinstance(evidence, dict):
-        return False
-    if row.get("kind") != "manual":
-        return evidence.get("status") == "passed" and evidence.get("exit_code") == 0
-    author, detail = evidence.get("confirmed_by"), evidence.get("evidence")
-    agents = {"agent", "assistant", "codex", "claude", "opencode", "costrict"}
-    return (isinstance(author, str) and bool(author.strip())
-            and author.strip().lower().split(":", 1)[0] not in agents
-            and isinstance(detail, str) and bool(detail.strip()))
-
-
-def validate_scenarios(value: object) -> list[dict[str, object]]:
-    if not isinstance(value, list):
-        raise ValueError("invalid manifest scenarios: expected list")
-    seen: set[str] = set()
-    for item in value:
-        if not isinstance(item, dict):
-            raise ValueError("invalid scenario: expected object")
-        scenario_id = item.get("id")
-        if not isinstance(scenario_id, str) or not scenario_id.strip():
-            raise ValueError("scenario id missing")
-        if scenario_id in seen:
-            raise ValueError(f"duplicate scenario id: {scenario_id}")
-        seen.add(scenario_id)
-        for field in ("kind", "owner", "cwd"):
-            if field in item and not isinstance(item[field], str):
-                raise ValueError(f"invalid scenario {scenario_id}:{field}")
-        command = item.get("command")
-        if command is not None and (not isinstance(command, list) or not all(isinstance(x, str) for x in command)):
-            raise ValueError(f"invalid scenario {scenario_id}:command")
-        timeout = item.get("timeout", 60)
-        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)) or not math.isfinite(timeout) or timeout <= 0:
-            raise ValueError(f"invalid scenario {scenario_id}:timeout")
-        deps = item.get("depends_on", [])
-        if not isinstance(deps, list) or not all(isinstance(x, str) for x in deps):
-            raise ValueError(f"invalid scenario {scenario_id}:depends_on")
-        if "runs" in item and not isinstance(item["runs"], list):
-            raise ValueError(f"invalid scenario {scenario_id}:runs")
-        revision = item.get("revision", 0)
-        if isinstance(revision, bool) or not isinstance(revision, int) or revision < 0:
-            raise ValueError(f"invalid scenario {scenario_id}:revision")
-    for item in value:
-        unknown = set(item.get("depends_on", [])) - seen
-        if unknown:
-            raise ValueError(f"acceptance scenario dependency missing: {', '.join(sorted(unknown))}")
-    return value
-
-
-def load_manifest(path: Path) -> dict[str, object]:
-    data = json.loads(path.read_text(encoding="utf-8"))
-    if not isinstance(data, dict):
-        raise ValueError("invalid acceptance manifest: expected object")
-    validate_scenarios(data.get("scenarios"))
-    if "task_file" in data and not isinstance(data["task_file"], str):
-        raise ValueError("invalid acceptance manifest: task_file")
-    return data
-
-
-def validate_execution_baseline(path: Path, data: Mapping[str, object]) -> None:
-    """Legacy standalone manifests remain usable; locked plans must match."""
-    task_name = data.get("task_file")
-    if not isinstance(task_name, str) or not task_name:
-        return
-    task = Path(task_name)
-    task = task if task.is_absolute() else path.parent / task
-    if not task.is_file():
-        raise ValueError(f"acceptance task file missing: {task}")
-    if "## Acceptance Coverage" in task.read_text(encoding="utf-8"):
-        from cf_acceptance_manifest import validate_manifest
-        valid, reason = validate_manifest(str(task), str(path))
-        if not valid:
-            raise ValueError(reason)

package/src/core/code-flow/scripts/cf_exec_base.py

@@ -1,112 +0,0 @@
-#!/usr/bin/env python3
-"""Shared execution substrate: deadline-aware argv subprocess runner.
-
-All check executors (acceptance scenarios, Spec verifiers, session
-validators) funnel through here so one entry deadline constrains the whole
-chain, commands never pass through a shell, and unrun work is reported as
-`incomplete` instead of silently skipped or falsely passed.
-"""
-
-from __future__ import annotations
-
-import shlex
-import json
-import subprocess
-import time
-from contextlib import contextmanager
-from contextvars import ContextVar
-from pathlib import Path
-from typing import Iterator, Mapping, Optional, Sequence
-
-_EXECUTIONS: ContextVar[Optional[dict[str, dict[str, object]]]] = ContextVar("cf_executions", default=None)
-
-
-@contextmanager
-def execution_session() -> Iterator[None]:
-    """Share results only inside one validation operation, never across turns."""
-    if _EXECUTIONS.get() is not None:
-        yield
-        return
-    token = _EXECUTIONS.set({})
-    try:
-        yield
-    finally:
-        _EXECUTIONS.reset(token)
-
-
-def invalidate_executions() -> None:
-    cache = _EXECUTIONS.get()
-    if cache is not None:
-        cache.clear()
-
-
-def execution_key(argv: Sequence[str], cwd: str, timeout: float) -> str:
-    """Identity of a command under the current process environment."""
-    return json.dumps([list(argv), str(Path(cwd).resolve()), float(timeout)], ensure_ascii=False)
-
-
-def remaining_seconds(deadline: Optional[float]) -> Optional[float]:
-    """Seconds left until the absolute monotonic deadline (None = unbounded)."""
-    if deadline is None:
-        return None
-    return deadline - time.monotonic()
-
-
-def build_argv(template: str, files: Sequence[str]) -> list[str]:
-    """Expand a validator command template into argv without a shell.
-
-    `{files}` must be a standalone token and expands to one argv entry per
-    file (spaces/metachars safe). Embedded usage is a config error — refusing
-    is safer than reintroducing shell splitting.
-    """
-    tokens = shlex.split(template or "")
-    if not tokens:
-        return []
-    argv: list[str] = []
-    for token in tokens:
-        if token == "{files}":
-            argv.extend(files)
-        elif "{files}" in token:
-            raise ValueError(f"validator command must keep {{files}} as a standalone token: {template!r}")
-        else:
-            argv.append(token)
-    return argv
-
-
-def run_command(
-    argv: Sequence[str],
-    cwd: str,
-    timeout: float,
-    deadline: Optional[float] = None,
-) -> dict[str, object]:
-    """Run argv synchronously under timeout+deadline. Never uses a shell."""
-    key = execution_key(argv, cwd, timeout)
-    cache = _EXECUTIONS.get()
-    if cache is not None and key in cache:
-        return dict(cache[key])
-    result = _execute(argv, cwd, timeout, deadline)
-    if cache is not None and result["status"] == "ok":
-        cache[key] = result
-    return result
-
-
-def _execute(argv: Sequence[str], cwd: str, timeout: float, deadline: Optional[float]) -> dict[str, object]:
-    remaining = remaining_seconds(deadline)
-    if remaining is not None and remaining <= 0:
-        return {"status": "deadline_exceeded", "returncode": None, "stdout": "", "stderr": ""}
-    effective = min(timeout, remaining) if remaining is not None else timeout
-    try:
-        proc = subprocess.run(
-            list(argv), cwd=cwd, capture_output=True, text=True, timeout=max(effective, 0.01)
-        )
-    except subprocess.TimeoutExpired as exc:
-        out = exc.stdout
-        return {
-            "status": "timeout",
-            "returncode": None,
-            "stdout": (out.decode() if isinstance(out, bytes) else (out or ""))[-4000:],
-            "stderr": "",
-        }
-    except OSError as exc:
-        return {"status": "spawn_error", "returncode": None, "stdout": "", "stderr": str(exc)}
-    return {"status": "ok", "returncode": proc.returncode, "stdout": proc.stdout or "", "stderr": proc.stderr or ""}