@kontourai/flow-agents 0.1.1

package/src/cli/console-learning-projection.ts

@@ -0,0 +1,140 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
+
+type Summary = {
+  scanned_learning_file_count: number;
+  emitted_learning_count: number;
+  destination: string | null;
+  producer: string;
+  scope: {
+    kind: string;
+    id: string;
+  };
+  dry_run: boolean;
+};
+
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+
+function printHelp(): void {
+  console.log("Usage: flow-agents console-learning-projection [options]");
+  console.log("");
+  console.log("Build an inert Console learning projection from local workflow learning sidecars.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .flow-agents)");
+  console.log("  --kontour-root <path>   Local Kontour root to write under (default: .kontour)");
+  console.log("  --scope <id>            Projection scope id (default: current directory name)");
+  console.log("  --scope-kind <kind>     Projection scope kind (default: repo)");
+  console.log("  --producer <id>         Projection producer id (default: flow-agents-learning)");
+  console.log("  --generated-at <ISO>    Override generated timestamp for deterministic output");
+  console.log("  --dry-run               Do not write a projection file");
+  console.log("  --json                  Print stable JSON summary");
+  console.log("  --help                  Show this help");
+}
+
+function defaultScopeId(): string {
+  return path.basename(process.cwd()) || "local";
+}
+
+function requireSafeSegment(value: string, label: string): string {
+  if (!SAFE_SEGMENT.test(value)) {
+    throw new Error(`${label} must contain only letters, numbers, dot, underscore, or hyphen: ${value}`);
+  }
+  return value;
+}
+
+function ensureNoSymlinkPath(target: string): void {
+  const resolved = path.resolve(target);
+  const root = path.parse(resolved).root;
+  const parts = path.relative(root, resolved).split(path.sep).filter(Boolean);
+  let cursor = root;
+  for (const part of parts) {
+    cursor = path.join(cursor, part);
+    if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`refusing to write through symlink path: ${cursor}`);
+    }
+  }
+}
+
+function ensureDirectory(target: string): void {
+  ensureNoSymlinkPath(target);
+  fs.mkdirSync(target, { recursive: true });
+  ensureNoSymlinkPath(target);
+  const stat = fs.statSync(target);
+  if (!stat.isDirectory()) throw new Error(`destination directory is not a directory: ${target}`);
+}
+
+function containedPath(root: string, destination: string): void {
+  const relative = path.relative(root, destination);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`destination escapes kontour root: ${destination}`);
+  }
+}
+
+function destinationPath(kontourRoot: string, producer: string, scopeKind: string, scopeId: string): string {
+  const root = path.resolve(kontourRoot);
+  const destination = path.resolve(root, "projections", producer, `${scopeKind}-${scopeId}.json`);
+  containedPath(root, destination);
+  return destination;
+}
+
+function writeProjection(file: string, root: string, projection: unknown): void {
+  containedPath(root, file);
+  ensureDirectory(path.dirname(file));
+  if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) {
+    throw new Error(`refusing to write symlinked projection file: ${file}`);
+  }
+  fs.writeFileSync(file, `${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+
+function printText(summary: Summary): void {
+  console.log(`Scanned learning files: ${summary.scanned_learning_file_count}`);
+  console.log(`Emitted learnings: ${summary.emitted_learning_count}`);
+  if (summary.dry_run) console.log("Dry run: no projection written");
+  else console.log(`Projection: ${summary.destination}`);
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const { flags } = parseArgs(argv);
+  if (flagBool(flags, "help") || flagBool(flags, "h")) {
+    printHelp();
+    return 0;
+  }
+
+  try {
+    const artifactRoot = path.resolve(flagString(flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+    const kontourRoot = path.resolve(flagString(flags, "kontour-root", ".kontour") ?? ".kontour");
+    const producer = requireSafeSegment(flagString(flags, "producer", "flow-agents-learning") ?? "flow-agents-learning", "--producer");
+    const scope = {
+      kind: requireSafeSegment(flagString(flags, "scope-kind", "repo") ?? "repo", "--scope-kind"),
+      id: requireSafeSegment(flagString(flags, "scope", defaultScopeId()) ?? defaultScopeId(), "--scope"),
+    };
+    const dryRun = flagBool(flags, "dry-run");
+    const sources = readWorkflowLearningSources(artifactRoot);
+    const projection = buildWorkflowLearningProjection(sources, {
+      scope,
+      producer: { id: producer, product: "flow-agents" },
+      generatedAt: flagString(flags, "generated-at"),
+    });
+    const destination = dryRun ? null : destinationPath(kontourRoot, producer, scope.kind, scope.id);
+    if (destination) writeProjection(destination, kontourRoot, projection);
+    const summary: Summary = {
+      scanned_learning_file_count: sources.length,
+      emitted_learning_count: projection.learnings.length,
+      destination,
+      producer,
+      scope,
+      dry_run: dryRun,
+    };
+    if (flagBool(flags, "json")) console.log(JSON.stringify(summary, null, 2));
+    else printText(summary);
+    return 0;
+  } catch (error) {
+    console.error(`console-learning-projection: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());

package/src/cli/effective-backlog-settings.ts

@@ -0,0 +1,99 @@
+import * as child_process from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagBool } from "../lib/args.js";
+import { readJson } from "../lib/fs.js";
+
+const PROJECT_SETTINGS_RELATIVE_PATH = path.join("context", "settings", "backlog-provider-settings.json");
+
+function loadSettings(file: string): Record<string, unknown> | null {
+  if (!fs.existsSync(file)) return null;
+  const data = readJson(file) as Record<string, unknown>;
+  if (data.schema_version !== "1.0") throw new Error(`${file}: unsupported schema_version ${String(data.schema_version)}`);
+  return data;
+}
+
+function repoFromText(text: string): { owner: string; name: string } | null {
+  const match = text.trim().match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+  return match ? { owner: match[1], name: match[2] } : null;
+}
+
+function currentRepo(repoPath: string): { owner: string; name: string } | null {
+  try {
+    const out = child_process.execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const repo = repoFromText(out);
+    if (repo) return repo;
+  } catch {}
+  const packagePath = path.join(repoPath, "package.json");
+  if (fs.existsSync(packagePath)) {
+    const data = readJson(packagePath) as Record<string, unknown>;
+    const repository = data.repository;
+    const url = typeof repository === "object" && repository !== null ? (repository as Record<string, unknown>).url : repository;
+    if (typeof url === "string") return repoFromText(url);
+  }
+  return null;
+}
+
+function merge(base: unknown, override: unknown): Record<string, unknown> | null {
+  if (!base && !override) return null;
+  if (!base) return structuredClone(override) as Record<string, unknown>;
+  if (!override) return structuredClone(base) as Record<string, unknown>;
+  const out = structuredClone(base) as Record<string, unknown>;
+  for (const [key, value] of Object.entries(override as Record<string, unknown>)) {
+    out[key] = typeof value === "object" && value !== null && typeof out[key] === "object" && out[key] !== null && !Array.isArray(value)
+      ? merge(out[key], value)
+      : structuredClone(value);
+  }
+  return out;
+}
+
+function findProject(settings: Record<string, unknown> | null, repo: { owner: string; name: string }): Record<string, unknown> | null {
+  const projects = settings?.projects;
+  if (!Array.isArray(projects)) return null;
+  return (projects.find((project) => {
+    const projectRepo = (((project as Record<string, unknown>).project as Record<string, unknown> | undefined)?.repo ?? {}) as Record<string, unknown>;
+    return projectRepo.owner === repo.owner && projectRepo.name === repo.name;
+  }) as Record<string, unknown> | undefined) ?? null;
+}
+
+function defaultProjectSettingsPath(): string {
+  let cursor = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(cursor, PROJECT_SETTINGS_RELATIVE_PATH);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return path.resolve(PROJECT_SETTINGS_RELATIVE_PATH);
+    cursor = parent;
+  }
+}
+
+function effective(repoPath: string, projectSettings: string, globalSettings: string): [Record<string, unknown>, number] {
+  const repo = currentRepo(repoPath);
+  const projectDoc = loadSettings(projectSettings);
+  const globalDoc = loadSettings(globalSettings);
+  if (!repo) return [{ status: "ask_user", reason: "could_not_identify_current_repo", message: "Ask the user which backlog WorkItemProvider and BoardProvider to use for this workspace.", resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings } }, 2];
+  const effectiveSettings = merge(merge(merge(globalDoc?.defaults, findProject(globalDoc, repo)), projectDoc?.defaults), findProject(projectDoc, repo));
+  if (!effectiveSettings) return [{ status: "ask_user", reason: "no_backlog_provider_settings", message: "Ask the user which backlog WorkItemProvider and BoardProvider to use before selecting work.", current_repo: repo, resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings, checked: ["project", "global"] } }, 2];
+  return [{ status: "configured", current_repo: repo, source: findProject(projectDoc, repo) || projectDoc?.defaults ? "project" : "global", precedence: ["project.projects match", "project.defaults", "global.projects match", "global.defaults"], settings: effectiveSettings }, 0];
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const args = parseArgs(argv);
+  try {
+    const [result, code] = effective(
+      path.resolve(flagString(args.flags, "repo-path", ".") ?? "."),
+      path.resolve(flagString(args.flags, "project-settings", defaultProjectSettingsPath()) ?? ""),
+      path.resolve(flagString(args.flags, "global-settings", path.join(os.homedir(), ".config", "flow-agents", "backlog-provider-settings.json")) ?? ""),
+    );
+    if (flagBool(args.flags, "json")) console.log(JSON.stringify(result, null, 2));
+    else console.log(`status: ${String(result.status)}`);
+    return code;
+  } catch (error) {
+    console.error(`error: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());

package/src/cli/fixture-retirement-audit.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+type FixtureAuditItem = {
+  fixture: string;
+  classification: "kept" | "retire_candidate";
+  owners: string[];
+  direct_refs: string[];
+  reasons: string[];
+};
+
+type FixtureAuditResult = {
+  fixture_root: string;
+  totals: {
+    scanned: number;
+    kept: number;
+    retire_candidates: number;
+  };
+  fixtures: FixtureAuditItem[];
+};
+
+const root = path.resolve(".");
+const fixtureRoot = "evals/fixtures";
+const ownerScanRoots = ["evals/static", "evals/integration", "scripts"];
+const textExtensions = new Set([".md", ".yaml", ".yml", ".json", ".sh", ".js", ".ts"]);
+const selfAuditRefs = new Set([
+  "evals/integration/test_fixture_retirement_audit.sh",
+]);
+
+function printHelp(): void {
+  console.log("Usage: flow-agents fixture-retirement-audit [--json]");
+  console.log("");
+  console.log("Read-only audit for canonical eval fixture retirement candidates.");
+  console.log("");
+  console.log("A fixture group is kept when docs/fixture-ownership.md lists existing");
+  console.log("owners and at least one live eval/script reference still points at it.");
+  console.log("The command never deletes, archives, or rewrites fixtures.");
+}
+
+function readText(file: string): string {
+  return fs.readFileSync(path.join(root, file), "utf8");
+}
+
+function walkFiles(dir: string): string[] {
+  const abs = path.join(root, dir);
+  if (!fs.existsSync(abs)) return [];
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+    const full = path.join(abs, entry.name);
+    if (entry.isDirectory()) out.push(...walkFiles(path.relative(root, full).split(path.sep).join("/")));
+    else if (entry.isFile()) out.push(path.relative(root, full).split(path.sep).join("/"));
+  }
+  return out;
+}
+
+function fixtureDirs(): string[] {
+  const abs = path.join(root, fixtureRoot);
+  return fs.readdirSync(abs, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `${fixtureRoot}/${entry.name}`)
+    .sort();
+}
+
+function ownerInventory(): Map<string, string[]> {
+  const doc = readText("docs/fixture-ownership.md");
+  const rows = new Map<string, string[]>();
+  for (const line of doc.split(/\r?\n/)) {
+    if (!line.startsWith("| `evals/fixtures/")) continue;
+    const cells = line.split("|").map((cell) => cell.trim());
+    const fixture = cells[1]?.replace(/^`|`$/g, "");
+    const ownersCell = cells[3] ?? "";
+    if (!fixture) continue;
+    const owners = [...ownersCell.matchAll(/`([^`]+)`/g)].map((match) => match[1]).sort();
+    rows.set(fixture, owners);
+  }
+  return rows;
+}
+
+function scanFiles(): string[] {
+  return ownerScanRoots
+    .flatMap((dir) => walkFiles(dir))
+    .filter((file) => textExtensions.has(path.extname(file)))
+    .sort();
+}
+
+function audit(): FixtureAuditResult {
+  const inventory = ownerInventory();
+  const files = scanFiles();
+  const fixtures = fixtureDirs().map((fixture): FixtureAuditItem => {
+    const owners = inventory.get(fixture) ?? [];
+    const directRefs = files
+      .filter((file) => readText(file).includes(fixture))
+      .filter((file) => !file.startsWith(`${fixture}/`))
+      .filter((file) => !selfAuditRefs.has(file))
+      .sort();
+    const reasons: string[] = [];
+    if (!inventory.has(fixture)) reasons.push("missing from docs/fixture-ownership.md");
+    const missingOwners = owners.filter((owner) => !fs.existsSync(path.join(root, owner)));
+    if (missingOwners.length) reasons.push(`owner path missing: ${missingOwners.join(", ")}`);
+    if (!owners.length) reasons.push("no owners listed");
+    if (!directRefs.length) reasons.push("no direct eval/script references");
+    const unlistedRefs = directRefs.filter((ref) => !owners.includes(ref));
+    if (unlistedRefs.length) reasons.push(`direct references not listed as owners: ${unlistedRefs.join(", ")}`);
+    return {
+      fixture,
+      classification: reasons.length ? "retire_candidate" : "kept",
+      owners,
+      direct_refs: directRefs,
+      reasons: reasons.length ? reasons : ["owned fixture with live eval/script references"],
+    };
+  });
+  return {
+    fixture_root: path.join(root, fixtureRoot),
+    totals: {
+      scanned: fixtures.length,
+      kept: fixtures.filter((item) => item.classification === "kept").length,
+      retire_candidates: fixtures.filter((item) => item.classification === "retire_candidate").length,
+    },
+    fixtures,
+  };
+}
+
+function printText(result: FixtureAuditResult): void {
+  console.log("Fixture retirement audit (dry run, read-only)");
+  console.log(`Fixture root: ${result.fixture_root}`);
+  console.log(`Scanned fixture groups: ${result.totals.scanned}`);
+  console.log(`Kept: ${result.totals.kept}`);
+  console.log(`Retire candidates: ${result.totals.retire_candidates}`);
+  for (const item of result.fixtures) {
+    console.log(`- ${item.classification}: ${item.fixture}`);
+    console.log(`  owners: ${item.owners.join(", ") || "none"}`);
+    console.log(`  direct_refs: ${item.direct_refs.join(", ") || "none"}`);
+    for (const reason of item.reasons) console.log(`  reason: ${reason}`);
+  }
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  try {
+    if (argv.includes("--help") || argv.includes("-h")) {
+      printHelp();
+      return 0;
+    }
+    const result = audit();
+    if (argv.includes("--json")) console.log(JSON.stringify(result, null, 2));
+    else printText(result);
+    return 0;
+  } catch (error) {
+    console.error(`fixture-retirement-audit: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());

package/src/cli/flow-kit.ts

@@ -0,0 +1,139 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseArgs, flagBool, flagString } from "../lib/args.js";
+import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
+import { assertKitRepository } from "../flow-kit/validate.js";
+import { activateCodexLocal } from "../runtime-adapters.js";
+
+const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
+const REPOSITORIES_REL = path.join("kits", "local", "repositories");
+
+function registryPath(dest: string): string { return path.join(dest, REGISTRY_REL); }
+function installedPath(dest: string, kitId: string): string { return path.join(dest, REPOSITORIES_REL, kitId); }
+
+function loadRegistry(dest: string): { schema_version: string; kits: Record<string, unknown>[] } {
+  const file = registryPath(dest);
+  if (!fs.existsSync(file)) return { schema_version: "1.0", kits: [] };
+  const data = readJson(file) as { schema_version?: string; kits?: unknown[] };
+  return { schema_version: data.schema_version ?? "1.0", kits: Array.isArray(data.kits) ? data.kits.filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null) : [] };
+}
+
+function contentHash(root: string): string {
+  const hash = crypto.createHash("sha256");
+  for (const file of walkFiles(root)) {
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function installLocal(argv: string[]): number {
+  const args = parseArgs(argv);
+  const source = path.resolve(args.positionals[0] ?? "");
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = assertKitRepository(source);
+  } catch (error) {
+    console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
+    console.log("Flow Kit repository validation failed:");
+    for (const diagnostic of ((error as Error & { diagnostics?: string[] }).diagnostics ?? [(error as Error).message])) console.log(` - ${diagnostic}`);
+    return 1;
+  }
+  console.log("warning: Flow validation surface unavailable; local kit check uses the minimal Flow Definition fallback");
+  const kitId = String(manifest.id);
+  const hash = contentHash(source);
+  const registry = loadRegistry(dest);
+  const existing = registry.kits.find((entry) => entry.id === kitId);
+  const target = installedPath(dest, kitId);
+  assertPathContained(dest, target);
+  const sourceText = source;
+  if (existing && existing.source !== sourceText && !flagBool(args.flags, "update")) {
+    console.log(`conflict: kit '${kitId}' is already installed from ${existing.source}; rerun with --update to replace it`);
+    return 2;
+  }
+  if (existing && existing.source === sourceText && existing.hash === hash && fs.existsSync(target) && !flagBool(args.flags, "force")) {
+    console.log(`kit '${kitId}' is already installed from ${sourceText}`);
+    return 0;
+  }
+  copyDir(source, target);
+  const entry: Record<string, unknown> = {
+    id: kitId,
+    source: sourceText,
+    hash,
+    installed_at: existing && existing.source === sourceText && !flagBool(args.flags, "update") ? existing.installed_at : isoNow(),
+    installed_path: target,
+    state: "installed",
+  };
+  if (typeof manifest.version === "string" && manifest.version) entry.version = manifest.version;
+  registry.kits = existing ? registry.kits.map((item) => item.id === kitId ? entry : item) : [...registry.kits, entry];
+  writeJson(registryPath(dest), registry);
+  console.log(`${existing ? "updated" : "installed"} local kit '${kitId}' at ${target}`);
+  return 0;
+}
+
+function list(argv: string[]): number {
+  const args = parseArgs(argv);
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const entries = loadRegistry(dest).kits;
+  if (!entries.length) {
+    console.log("No local Flow Kits installed.");
+    return 0;
+  }
+  for (const entry of entries.sort((a, b) => String(a.id ?? "").localeCompare(String(b.id ?? "")))) {
+    console.log(`${entry.id} | source=${entry.source} | hash=${entry.hash} | installed_at=${entry.installed_at} | path=${entry.installed_path} | state=${entry.state ?? "unknown"}`);
+  }
+  return 0;
+}
+
+function status(argv: string[]): number {
+  const args = parseArgs(argv);
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  let entries = loadRegistry(dest).kits;
+  const kitId = args.positionals[0];
+  if (kitId) {
+    entries = entries.filter((entry) => entry.id === kitId);
+    if (!entries.length) {
+      console.log(`local Flow Kit '${kitId}' is not installed`);
+      return 1;
+    }
+  }
+  if (!entries.length) {
+    console.log("No local Flow Kits installed.");
+    return 0;
+  }
+  for (const entry of entries.sort((a, b) => String(a.id ?? "").localeCompare(String(b.id ?? "")))) {
+    console.log(JSON.stringify({ ...entry, state: fs.existsSync(String(entry.installed_path ?? "")) ? "installed" : "missing" }, null, 2));
+  }
+  return 0;
+}
+
+function activate(argv: string[]): number {
+  const args = parseArgs(argv);
+  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
+  const adapter = flagString(args.flags, "adapter");
+  if (adapter && adapter !== "codex-local") {
+    console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+    return 2;
+  }
+  const result = activateCodexLocal(sourceRoot, dest);
+  console.log(JSON.stringify(result, null, 2));
+  return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const [command, ...rest] = argv;
+  if (command === "install-local") return installLocal(rest);
+  if (command === "list") return list(rest);
+  if (command === "status") return status(rest);
+  if (command === "activate") return activate(rest);
+  console.error("usage: flow-kit <install-local|list|status|activate> ...");
+  return 2;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) process.exit(main());