@foundation0/api 1.0.0

package/agents.ts

@@ -0,0 +1,492 @@
+import fs from 'fs'
+import path from 'path'
+import { spawnSync } from 'child_process'
+import { pathToFileURL } from 'url'
+
+export interface VersionedFileSpec {
+  parts: string[]
+  base: string
+  version: string | null
+  ext: string | null
+}
+
+export interface ActiveFileResult {
+  agentName: string
+  sourceFile: string
+  activeFile: string
+  matchedFile: string
+  mode: 'symlink'
+}
+
+export interface AgentLoadResult {
+  agentName: string
+  loaded: unknown
+}
+
+interface ActiveConfigInput {
+  path: string
+  required: boolean
+}
+
+const CLI_NAME = 'f0'
+const VERSION_RE = 'v?\\d+(?:\\.\\d+){2,}'
+const VERSION_RE_CORE = `(?:${VERSION_RE})`
+const VERSION_WITH_EXT_RE = new RegExp(`^(.+)\\.(${VERSION_RE})\\.([A-Za-z][A-Za-z0-9_-]*)$`)
+const VERSION_ONLY_RE = new RegExp(`^(.+)\\.(${VERSION_RE})$`)
+const PRIORITIZED_EXTS = ['.md', '.json', '.yaml', '.yml', '.ts', '.js', '.txt']
+
+export function usage(): string {
+  return `Usage:\n  ${CLI_NAME} agents <agent-name> <file-path> --set-active\n  ${CLI_NAME} agents --list\n  ${CLI_NAME} agents <agent-name> load\n\n` +
+    `Examples:\n  ${CLI_NAME} agents coder /system/boot.v0.0.1 --set-active\n  ${CLI_NAME} agents coder /system/boot --set-active --latest\n  ${CLI_NAME} agents coder /skills/coding-standards.v0.0.1 --set-active\n  ${CLI_NAME} agents --list\n` +
+    `  ${CLI_NAME} agents coder load\n` +
+    `\n` +
+    `file-path is relative to the agent root (leading slash required).\n` +
+    `Use --latest to resolve /file-name to the latest version.\n` +
+    `The active file created is [file].active.<ext>.\n`
+}
+
+export function resolveAgentsRoot(processRoot: string = process.cwd()): string {
+  const candidates = [
+    path.join(processRoot, 'agents'),
+    path.join(processRoot, 'wireborn', 'agents'),
+  ]
+
+  for (const candidatesPath of candidates) {
+    if (existsDir(candidatesPath)) {
+      return candidatesPath
+    }
+  }
+
+  const checked = candidates.map((candidate) => `\n  checked path: ${candidate}`).join('')
+
+  throw new Error(
+    `Could not find agents directory relative to working directory.\n  cwd: ${processRoot}${checked}`
+  )
+}
+
+export const resolveAgentsRootFrom = resolveAgentsRoot
+
+export function listAgents(processRoot: string = process.cwd()): string[] {
+  const agentsPath = resolveAgentsRoot(processRoot)
+
+  return fs
+    .readdirSync(agentsPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b))
+}
+
+export function parseTargetSpec(spec: string): VersionedFileSpec {
+  if (!spec || typeof spec !== 'string') {
+    throw new Error('file-path is required.')
+  }
+
+  const normalized = spec.replace(/\\/g, '/').trim()
+
+  if (!normalized.startsWith('/')) {
+    throw new Error('file-path must start with a leading slash, e.g. /system/boot.v0.0.1')
+  }
+
+  const body = normalized.slice(1)
+  if (!body) {
+    throw new Error('file-path is empty.')
+  }
+
+  const parts = body.split('/').filter(Boolean)
+  if (parts.length < 2) {
+    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
+  }
+
+  const file = parts.pop()
+  if (!file) {
+    throw new Error('file-path must include a file name, for example /system/boot.v0.0.1')
+  }
+
+  const withExt = file.match(VERSION_WITH_EXT_RE)
+  const withoutExt = file.match(VERSION_ONLY_RE)
+  if (withExt) {
+    return {
+      parts,
+      base: withExt[1],
+      version: withExt[2],
+      ext: withExt[3],
+    }
+  }
+
+  if (withoutExt) {
+    return {
+      parts,
+      base: withoutExt[1],
+      version: withoutExt[2],
+      ext: null,
+    }
+  }
+
+  if (parts.length === 0) {
+    throw new Error('file-path must include a file name, for example /system/boot or /system/boot.v0.0.1.')
+  }
+
+  return {
+    parts,
+    base: file,
+    version: null,
+    ext: null,
+  }
+}
+
+function parseVersion(version: string): number[] {
+  const clean = version.replace(/^v/, '')
+  return clean.split('.').filter(Boolean).map((part) => Number.parseInt(part, 10))
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function compareVersions(left: string, right: string): number {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  const size = Math.max(a.length, b.length)
+
+  for (let i = 0; i < size; i += 1) {
+    const leftValue = a[i] ?? 0
+    const rightValue = b[i] ?? 0
+    if (leftValue > rightValue) return 1
+    if (leftValue < rightValue) return -1
+  }
+
+  return 0
+}
+
+function findLatestVersionedFile(targetDir: string, base: string, ext: string | null): string | null {
+  const fileEntries = fs
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  const safeBase = escapeRegExp(base)
+  const regex = new RegExp(`^${safeBase}\\.(${VERSION_RE_CORE})\\.([^.]+)$`)
+  const matches = fileEntries
+    .map((entry) => {
+      const match = entry.match(regex)
+      if (!match) return null
+
+      const version = match[1]
+      const detectedExt = `.${match[2]}`
+      if (ext && detectedExt !== `.${ext}`) {
+        return null
+      }
+
+      return { entry, version, detectedExt }
+    })
+    .filter((value): value is { entry: string; version: string; detectedExt: string } => value !== null)
+
+  if (matches.length === 0) return null
+
+  matches.sort((a, b) => compareVersions(a.version, b.version))
+  const selected = matches[matches.length - 1]
+
+  const version = selected.version
+  const sameVersion = matches
+    .filter((item) => compareVersions(item.version, version) === 0)
+    .map((item) => item.entry)
+    .sort()
+
+  if (sameVersion.length <= 1) {
+    return sameVersion[0]
+  }
+
+  for (const extName of PRIORITIZED_EXTS) {
+    const preferred = sameVersion.find((entryName) => entryName.endsWith(extName))
+    if (preferred) {
+      return preferred
+    }
+  }
+
+  return sameVersion.sort()[0]
+}
+
+export function resolveTargetFile(targetDir: string, spec: VersionedFileSpec, options: { latest?: boolean } = {}): string | null {
+  const entries = fs
+    .readdirSync(targetDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+
+  if (!spec.version) {
+    if (!options.latest) {
+      return null
+    }
+    return findLatestVersionedFile(targetDir, spec.base, null)
+  }
+
+  if (spec.ext) {
+    const exact = `${spec.base}.${spec.version}.${spec.ext}`
+    if (entries.includes(exact)) {
+      return exact
+    }
+    return null
+  }
+
+  const prefix = `${spec.base}.${spec.version}.`
+  const candidates = entries.filter((entry) => entry.startsWith(prefix))
+  if (candidates.length === 0) {
+    return null
+  }
+
+  for (const ext of PRIORITIZED_EXTS) {
+    const match = candidates.find((entry) => entry.endsWith(ext))
+    if (match) {
+      return match
+    }
+  }
+
+  return candidates.sort()[0]
+}
+
+export function setActiveLink(sourceFile: string, activeFile: string): 'symlink' {
+  if (!existsFile(sourceFile)) {
+    throw new Error(`Versioned file not found: ${sourceFile}`)
+  }
+
+  fs.mkdirSync(path.dirname(activeFile), { recursive: true })
+
+  if (fs.existsSync(activeFile)) {
+    fs.rmSync(activeFile, { force: true })
+  }
+
+  const linkTarget = path.relative(path.dirname(activeFile), sourceFile)
+
+  try {
+    fs.symlinkSync(linkTarget, activeFile, 'file')
+    return 'symlink'
+  } catch (error) {
+    if (process.platform === 'win32') {
+      const ok = createWindowsSymlink(activeFile, sourceFile)
+      if (ok) {
+        return 'symlink'
+      }
+      throw new Error(
+        `Failed to create symlink on Windows. Run shell as Administrator or enable Developer Mode.\n${String(error?.message ?? error)}`
+      )
+    }
+
+    throw error
+  }
+}
+
+function createWindowsSymlink(activeFile: string, sourceFile: string): boolean {
+  const quote = (value: string) => `"${value.replace(/\"/g, '""')}"`
+  const command = `mklink ${quote(path.resolve(activeFile))} ${quote(path.resolve(sourceFile))}`
+  const result = spawnSync('cmd', ['/c', command], {
+    shell: false,
+    encoding: 'utf8',
+  })
+
+  return result.status === 0
+}
+
+export function setActive(
+  agentName: string,
+  target: string,
+  processRoot: string = process.cwd(),
+  options: { latest?: boolean } = {}
+): ActiveFileResult {
+  const spec = parseTargetSpec(target)
+  const agentsRoot = resolveAgentsRootFrom(processRoot)
+  const targetDir = path.join(agentsRoot, agentName, ...spec.parts)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  if (!existsDir(targetDir)) {
+    throw new Error(`Target folder not found: ${targetDir}`)
+  }
+
+  const matchedFile = resolveTargetFile(targetDir, spec, options)
+  if (!matchedFile && !spec.version && options.latest) {
+    throw new Error(`No files found for /${spec.parts.join('/')}${spec.parts.length > 0 ? '/' : ''}${spec.base}`)
+  }
+  if (!matchedFile) {
+    if (!spec.version && !options.latest) {
+      throw new Error(
+        `Version missing for /${spec.parts.join('/')}/${spec.base}. Use --latest to select the latest version.`
+      )
+    }
+    const extensionHint = spec.ext ? `.${spec.ext}` : ' with any extension'
+    throw new Error(
+      `Versioned file not found for /${spec.parts.join('/')}/${spec.base}.${spec.version}${extensionHint}`
+    )
+  }
+
+  const sourceFile = path.join(targetDir, matchedFile)
+  const activeFile = path.join(targetDir, `${spec.base}.active${path.extname(matchedFile)}`)
+  const mode = setActiveLink(sourceFile, activeFile)
+
+  return {
+    agentName,
+    sourceFile,
+    activeFile,
+    matchedFile,
+    mode,
+  }
+}
+
+export async function loadAgent(agentName: string, processRoot: string = process.cwd()): Promise<AgentLoadResult> {
+  const agentsRoot = resolveAgentsRoot(processRoot)
+  const agentDir = path.join(agentsRoot, agentName)
+
+  if (!existsDir(agentDir)) {
+    throw new Error(`Agent folder not found: ${agentDir}`)
+  }
+
+  const loadFile = path.join(agentDir, 'load.ts')
+  if (!existsFile(loadFile)) {
+    throw new Error(`Load file not found for agent '${agentName}': ${loadFile}`)
+  }
+
+  validateActiveConfigInputs(agentDir)
+
+  const moduleUrl = pathToFileURL(loadFile).href
+  const module = await import(moduleUrl)
+  const loadFn = module.load
+
+  if (typeof loadFn !== 'function') {
+    throw new Error(`Load module for agent '${agentName}' must export a 'load' function.`)
+  }
+
+  return {
+    agentName,
+    loaded: await loadFn(),
+  }
+}
+
+function validateActiveConfigInputs(agentDir: string): void {
+  const issues: string[] = []
+
+  const requiredInputs = collectActiveConfigInputs(agentDir)
+
+  for (const input of requiredInputs) {
+    if (!existsFile(input.path)) {
+      if (input.required) {
+        issues.push(`missing: ${path.relative(agentDir, input.path)}`)
+      }
+      continue
+    }
+
+    if (!isSymbolicLink(input.path)) {
+      issues.push(`not a symlink: ${path.relative(agentDir, input.path)}`)
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new Error(`Config input check failed: ${issues.join(', ')}`)
+  }
+}
+
+function collectActiveConfigInputs(agentDir: string): ActiveConfigInput[] {
+  const systemDir = path.join(agentDir, 'system')
+  const skillsDir = path.join(agentDir, 'skills')
+
+  const required: ActiveConfigInput[] = [
+    { path: path.join(systemDir, 'boot.active.md'), required: true },
+    { path: path.join(systemDir, 'workflow.active.md'), required: true },
+    { path: path.join(systemDir, 'tools.active.json'), required: true },
+    { path: path.join(systemDir, 'model.active.json'), required: true },
+  ]
+
+  const enabledSkillsPath = path.join(skillsDir, 'enabled-skills.md')
+  if (!existsFile(enabledSkillsPath)) {
+    return required
+  }
+
+  const lines = fs.readFileSync(enabledSkillsPath, 'utf8')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+
+  for (const line of lines) {
+    required.push({ path: path.join(skillsDir, line), required: true })
+  }
+
+  return required
+}
+
+function isSymbolicLink(filePath: string): boolean {
+  try {
+    return fs.lstatSync(filePath).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+export async function main(argv: string[], processRoot: string = process.cwd()): Promise<string> {
+  if (
+    argv.length === 0 ||
+    argv.includes('--help') ||
+    argv.includes('-h')
+  ) {
+    return usage()
+  }
+
+  const [scope, maybeAgentOrFlag, maybeTarget, ...rest] = argv
+  const listMode = scope === 'agents' && maybeAgentOrFlag === '--list'
+
+  if (scope !== 'agents') {
+    throw new Error('Expected command `agents` as first positional argument.')
+  }
+
+  if (listMode) {
+    const unknownFlags = rest.filter(Boolean)
+    if (unknownFlags.length > 0) {
+      throw new Error(`Unknown flags for list mode: ${unknownFlags.join(', ')}`)
+    }
+    return listAgents(processRoot).join('\n')
+  }
+
+  const agentName = maybeAgentOrFlag
+  const target = maybeTarget
+  const setActive = rest.includes('--set-active')
+  const useLatest = rest.includes('--latest')
+
+  if (target === 'load') {
+    if (rest.length > 0) {
+      throw new Error(`Unknown flags for load mode: ${rest.join(', ')}`)
+    }
+    const result = await loadAgent(agentName, processRoot)
+    return JSON.stringify(result.loaded, null, 2)
+  }
+
+  if (!agentName || !target) {
+    throw new Error('Missing required arguments: <agent-name> and <file-path>.')
+  }
+
+  if (!setActive) {
+    throw new Error('`--set-active` is required for this operation.')
+  }
+
+  const unknownFlags = rest.filter((arg) => arg !== '--set-active' && arg !== '--latest')
+  if (unknownFlags.length > 0) {
+    throw new Error(`Unknown flags: ${unknownFlags.join(', ')}`)
+  }
+
+  const result = setActive(agentName, target, processRoot, { latest: useLatest })
+  return `[${CLI_NAME}] set active: ${result.matchedFile} -> ${path.basename(result.activeFile)} (${result.mode})`
+}
+
+function existsDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function existsFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile()
+  } catch {
+    return false
+  }
+}