@kontourai/flow-agents 0.1.1

package/src/cli.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { basename } from "node:path";
+import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
+import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
+import { main as flowKit } from "./cli/flow-kit.js";
+import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
+import { main as init } from "./cli/init.js";
+import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
+import { main as publishChange } from "./cli/publish-change-helper.js";
+import { main as pullWorkProvider } from "./cli/pull-work-provider.js";
+import { main as telemetryDoctor } from "./cli/telemetry-doctor.js";
+import { main as usageFeedback } from "./cli/usage-feedback.js";
+import { main as veritasGovernance } from "./cli/veritas-governance.js";
+import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
+import { main as buildBundles } from "./tools/build-universal-bundles.js";
+import { main as contextMap } from "./tools/generate-context-map.js";
+import { main as filterInstalledPacks } from "./tools/filter-installed-packs.js";
+import { main as validateSource } from "./tools/validate-source-tree.js";
+import { main as validatePackage } from "./tools/validate-package.js";
+import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
+import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
+
+const availableCommands = new Map<string, (argv: string[]) => number | Promise<number>>([
+  ["build-bundles", () => buildBundles()],
+  ["console-learning-projection", consoleLearningProjection],
+  ["context-map", contextMap],
+  ["effective-backlog-settings", effectiveBacklogSettings],
+  ["filter-installed-packs", filterInstalledPacks],
+  ["fixture-retirement-audit", fixtureRetirementAudit],
+  ["flow-kit", flowKit],
+  ["init", init],
+  ["promote-workflow-artifact", promoteWorkflowArtifact],
+  ["publish-change", publishChange],
+  ["pull-work-provider", pullWorkProvider],
+  ["runtime-adapter", runtimeAdapter],
+  ["telemetry-doctor", telemetryDoctor],
+  ["usage-feedback", usageFeedback],
+  ["veritas-governance", veritasGovernance],
+  ["validate-package", validatePackage],
+  ["validate-hook-influence", validateHookInfluence],
+  ["validate-source", validateSource],
+  ["workflow-artifact-cleanup-audit", workflowArtifactCleanupAudit],
+]);
+
+const aliases = new Map<string, string>([
+  ["flow-agents-build-bundles", "build-bundles"],
+  ["flow-agents-console-learning-projection", "console-learning-projection"],
+  ["flow-agents-context-map", "context-map"],
+  ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
+  ["flow-agents-filter-installed-packs", "filter-installed-packs"],
+  ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
+  ["flow-agents-flow-kit", "flow-kit"],
+  ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
+  ["flow-agents-publish-change", "publish-change"],
+  ["flow-agents-pull-work-provider", "pull-work-provider"],
+  ["flow-agents-runtime-adapter", "runtime-adapter"],
+  ["flow-agents-telemetry-doctor", "telemetry-doctor"],
+  ["flow-agents-usage-feedback", "usage-feedback"],
+  ["flow-agents-veritas-governance", "veritas-governance"],
+  ["flow-agents-validate-hook-influence", "validate-hook-influence"],
+  ["flow-agents-validate-source", "validate-source"],
+  ["flow-agents-workflow-artifact-cleanup-audit", "workflow-artifact-cleanup-audit"],
+]);
+
+function printHelp(): void {
+  console.log("Usage: flow-agents <command> [args]");
+  console.log("");
+  console.log("Available commands:");
+  for (const name of availableCommands.keys()) console.log(`  ${name}`);
+}
+
+const invokedAs = basename(process.argv[1] ?? "flow-agents");
+const commandName = aliases.get(invokedAs) ?? process.argv[2];
+const forwardedArgs = aliases.has(invokedAs) ? process.argv.slice(2) : process.argv.slice(3);
+
+async function run(): Promise<number> {
+  if (!commandName || commandName === "--help" || commandName === "-h" || commandName === "help") {
+    printHelp();
+    return 0;
+  }
+
+  if (commandName === "commands" || commandName === "list") {
+    for (const name of availableCommands.keys()) console.log(name);
+    return 0;
+  }
+
+  const availableCommand = availableCommands.get(commandName);
+  if (availableCommand) return await availableCommand(forwardedArgs);
+
+  console.error(`Unknown flow-agents command: ${commandName}`);
+  console.error("Run `flow-agents --help` for registered commands.");
+  return 64;
+}
+
+process.exit(await run());

package/src/flow-kit/validate.ts

@@ -0,0 +1,74 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readJson } from "../lib/fs.js";
+
+const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"] as const;
+
+export function validateKitRepository(kitDir: string): string[] {
+  const errors: string[] = [];
+  const manifestPath = path.join(kitDir, "kit.json");
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = readJson(manifestPath) as Record<string, unknown>;
+  } catch (error) {
+    errors.push(`${manifestPath}: invalid JSON: ${(error as Error).message}`);
+    return errors;
+  }
+  if (manifest.schema_version !== "1.0") errors.push(`${manifestPath}: .schema_version must be "1.0"`);
+  if (typeof manifest.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(manifest.id)) {
+    errors.push(`${manifestPath}: .id must be a stable kebab-case string`);
+  }
+  if (typeof manifest.name !== "string" || !manifest.name.trim()) errors.push(`${manifestPath}: .name must be a non-empty string`);
+
+  for (const section of ASSET_CLASSES) {
+    const entries = manifest[section];
+    if (entries === undefined) continue;
+    if (!Array.isArray(entries)) {
+      errors.push(`${manifestPath}: .${section} must be a list`);
+      continue;
+    }
+    const seen = new Set<string>();
+    entries.forEach((entry, index) => {
+      if (typeof entry !== "object" || entry === null) {
+        errors.push(`${manifestPath}: ${section}[${index}] must be an object`);
+        return;
+      }
+      const record = entry as Record<string, unknown>;
+      const id = record.id;
+      const rel = record.path;
+      if (typeof id === "string") {
+        if (seen.has(id)) errors.push(`${manifestPath}: ${section}[${index}].id duplicates`);
+        seen.add(id);
+      }
+      if (typeof rel !== "string" || !rel) {
+        errors.push(`${manifestPath}: ${section}[${index}].path must be a string`);
+        return;
+      }
+      if (path.isAbsolute(rel)) {
+        errors.push(`${manifestPath}: ${section}[${index}].path must be relative`);
+        return;
+      }
+      const resolved = path.resolve(kitDir, rel);
+      const root = path.resolve(kitDir);
+      if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+        errors.push(`${manifestPath}: ${section}[${index}].path must stay inside the kit directory`);
+        return;
+      }
+      if (!fs.existsSync(resolved)) {
+        const noun = section === "flows" ? "Flow Definition" : "asset";
+        errors.push(`${manifestPath}: ${section}[${index}].path points at missing ${noun}: ${rel}`);
+      }
+    });
+  }
+  return errors;
+}
+
+export function assertKitRepository(kitDir: string): Record<string, unknown> {
+  const errors = validateKitRepository(kitDir);
+  if (errors.length) {
+    const error = new Error("Flow Kit repository validation failed") as Error & { diagnostics?: string[] };
+    error.diagnostics = errors;
+    throw error;
+  }
+  return readJson(path.join(kitDir, "kit.json")) as Record<string, unknown>;
+}

package/src/lib/args.ts

@@ -0,0 +1,43 @@
+export type ParsedArgs = { positionals: string[]; flags: Record<string, string | boolean | string[]> };
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean | string[]> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    const key = arg.slice(2, eq === -1 ? undefined : eq);
+    const next = eq === -1 ? argv[index + 1] : arg.slice(eq + 1);
+    let value: string | boolean = true;
+    if (eq !== -1) value = String(next);
+    else if (next !== undefined && !String(next).startsWith("--")) {
+      value = String(next);
+      index += 1;
+    }
+    if (flags[key] === undefined) flags[key] = value;
+    else if (Array.isArray(flags[key])) (flags[key] as string[]).push(String(value));
+    else flags[key] = [String(flags[key]), String(value)];
+  }
+  return { positionals, flags };
+}
+
+export function flagString(flags: ParsedArgs["flags"], key: string, fallback?: string): string | undefined {
+  const value = flags[key];
+  if (Array.isArray(value)) return value[value.length - 1];
+  if (typeof value === "string") return value;
+  return fallback;
+}
+
+export function flagBool(flags: ParsedArgs["flags"], key: string): boolean {
+  return flags[key] === true || flags[key] === "true";
+}
+
+export function flagList(flags: ParsedArgs["flags"], key: string): string[] {
+  const value = flags[key];
+  if (value === undefined || value === true) return [];
+  return Array.isArray(value) ? value.map(String) : [String(value)];
+}

package/src/lib/fs.ts

@@ -0,0 +1,62 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function readJson(file: string): unknown {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function writeJson(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(src, dest, {
+    recursive: true,
+    filter: (source) => !source.split(path.sep).some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)),
+  });
+}
+
+export function assertPathContained(root: string, target: string): void {
+  const rootReal = fs.realpathSync(root);
+  let existingParent = path.dirname(target);
+  const missingParts = [path.basename(target)];
+  while (!fs.existsSync(existingParent)) {
+    missingParts.unshift(path.basename(existingParent));
+    const next = path.dirname(existingParent);
+    if (next === existingParent) break;
+    existingParent = next;
+  }
+  const parentReal = fs.realpathSync(existingParent);
+  const resolved = path.resolve(parentReal, ...missingParts);
+  const relative = path.relative(rootReal, resolved);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`path escapes root: ${target}`);
+  if (fs.existsSync(target)) {
+    const targetReal = fs.realpathSync(target);
+    const targetRelative = path.relative(rootReal, targetReal);
+    if (!targetRelative || targetRelative.startsWith("..") || path.isAbsolute(targetRelative)) throw new Error(`path escapes root: ${target}`);
+  }
+}
+
+export function walkFiles(root: string): string[] {
+  const out: string[] = [];
+  if (!fs.existsSync(root)) return out;
+  for (const name of fs.readdirSync(root).sort()) {
+    const file = path.join(root, name);
+    const stat = fs.statSync(file);
+    if (stat.isDirectory()) out.push(...walkFiles(file));
+    else if (stat.isFile()) out.push(file);
+  }
+  return out;
+}
+
+export function relPath(root: string, file: string): string {
+  const rel = path.relative(root, file);
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel.split(path.sep).join("/") : file.split(path.sep).join("/");
+}
+
+export function isoNow(): string {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}