agent-facets 0.1.1

package/src/commands/create-scaffold.ts

@@ -0,0 +1,180 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { FACET_MANIFEST_FILE } from '@agent-facets/core'
+
+// --- Types ---
+
+export interface CreateOptions {
+  name: string
+  version: string
+  description: string
+  skills: string[]
+  agents: string[]
+  commands: string[]
+}
+
+// --- Validation ---
+
+export const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+export const SEMVER = /^\d+\.\d+\.\d+$/
+
+export function isValidKebabCase(value: string): boolean {
+  return KEBAB_CASE.test(value)
+}
+
+export function isValidSemVer(value: string): boolean {
+  return SEMVER.test(value)
+}
+
+// --- Template generation ---
+
+function toTitleCase(kebab: string): string {
+  return kebab
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ')
+}
+
+function skillTemplate(name: string): string {
+  return `# ${toTitleCase(name)}
+
+<!-- This is a starter skill template. Replace this content with your skill's instructions. -->
+<!-- Skills provide reusable knowledge and guidelines that agents and commands can reference. -->
+<!-- A skill needs a description (required) — the description helps consumers decide -->
+<!-- whether to use this skill. The prompt content is this file. -->
+
+## Purpose
+
+Describe what this skill teaches or what guidelines it provides.
+
+## Guidelines
+
+- Add your skill's guidelines here
+- Each guideline should be clear and actionable
+`
+}
+
+function agentTemplate(name: string): string {
+  return `# ${toTitleCase(name)}
+
+<!-- This is a starter agent template. Replace this content with your agent's prompt. -->
+<!-- Agents are AI assistant personas with specific roles, behaviors, and tool access. -->
+
+## Role
+
+Describe this agent's role and responsibilities.
+
+## Behavior
+
+- Define how this agent should behave
+- Specify what tools it should use
+- Describe its communication style
+`
+}
+
+function commandTemplate(name: string): string {
+  return `# ${toTitleCase(name)}
+
+<!-- This is a starter command template. Replace this content with your command's prompt. -->
+<!-- Commands are user-invokable actions that perform specific tasks. -->
+
+## Task
+
+Describe what this command does when invoked.
+
+## Steps
+
+1. First step
+2. Second step
+3. Final step
+`
+}
+
+// --- Manifest generation ---
+
+export function generateManifest(opts: CreateOptions): string {
+  const manifest: Record<string, unknown> = {
+    name: opts.name,
+    version: opts.version,
+  }
+
+  if (opts.description) {
+    manifest.description = opts.description
+  }
+
+  if (opts.skills.length > 0) {
+    const skills: Record<string, { description: string }> = {}
+    for (const skill of opts.skills) {
+      skills[skill] = { description: `A ${toTitleCase(skill)} skill` }
+    }
+    manifest.skills = skills
+  }
+
+  if (opts.agents.length > 0) {
+    const agents: Record<string, { description: string }> = {}
+    for (const agent of opts.agents) {
+      agents[agent] = { description: `A ${toTitleCase(agent)} agent` }
+    }
+    manifest.agents = agents
+  }
+
+  if (opts.commands.length > 0) {
+    const commands: Record<string, { description: string }> = {}
+    for (const command of opts.commands) {
+      commands[command] = { description: `A ${toTitleCase(command)} command` }
+    }
+    manifest.commands = commands
+  }
+
+  return JSON.stringify(manifest, null, 2)
+}
+
+// --- File listing preview ---
+
+export function previewFiles(opts: CreateOptions): string[] {
+  const files: string[] = [FACET_MANIFEST_FILE]
+  for (const skill of opts.skills) {
+    files.push(`skills/${skill}.md`)
+  }
+  for (const agent of opts.agents) {
+    files.push(`agents/${agent}.md`)
+  }
+  for (const command of opts.commands) {
+    files.push(`commands/${command}.md`)
+  }
+  return files
+}
+
+// --- Scaffold writing ---
+
+export async function writeScaffold(opts: CreateOptions, targetDir: string): Promise<string[]> {
+  const files: string[] = []
+
+  // Write manifest
+  const manifestPath = join(targetDir, FACET_MANIFEST_FILE)
+  await Bun.write(manifestPath, generateManifest(opts))
+  files.push(FACET_MANIFEST_FILE)
+
+  // Write skill files
+  for (const skill of opts.skills) {
+    await mkdir(join(targetDir, 'skills'), { recursive: true })
+    await Bun.write(join(targetDir, `skills/${skill}.md`), skillTemplate(skill))
+    files.push(`skills/${skill}.md`)
+  }
+
+  // Write agent files
+  for (const agent of opts.agents) {
+    await mkdir(join(targetDir, 'agents'), { recursive: true })
+    await Bun.write(join(targetDir, `agents/${agent}.md`), agentTemplate(agent))
+    files.push(`agents/${agent}.md`)
+  }
+
+  // Write command files
+  for (const command of opts.commands) {
+    await mkdir(join(targetDir, 'commands'), { recursive: true })
+    await Bun.write(join(targetDir, `commands/${command}.md`), commandTemplate(command))
+    files.push(`commands/${command}.md`)
+  }
+
+  return files
+}

package/src/commands.ts

@@ -0,0 +1,31 @@
+import { buildCommand } from './commands/build.ts'
+import { createCommand } from './commands/create/index.ts'
+
+export type Command = {
+  name: string
+  description: string
+  run: (args: string[]) => Promise<number>
+}
+
+function stubCommand(name: string, description: string): Command {
+  return {
+    name,
+    description,
+    run: async () => {
+      console.log(`"${name}" is not yet implemented.`)
+      return 0
+    },
+  }
+}
+
+export const commands: Record<string, Command> = {
+  add: stubCommand('add', 'Add a facet to the project'),
+  build: buildCommand,
+  create: createCommand,
+  info: stubCommand('info', 'Show information about a facet'),
+  install: stubCommand('install', 'Install all facets from the lockfile'),
+  list: stubCommand('list', 'List installed facets'),
+  publish: stubCommand('publish', 'Publish a facet to the registry'),
+  remove: stubCommand('remove', 'Remove a facet from the project'),
+  upgrade: stubCommand('upgrade', 'Upgrade installed facets'),
+}

package/src/help.ts

@@ -0,0 +1,36 @@
+import type { Command } from './commands.ts'
+import { commands } from './commands.ts'
+import { version } from './version.ts'
+
+export function printGlobalHelp(): void {
+  const entries = Object.values(commands)
+  const maxNameLength = Math.max(...entries.map((c) => c.name.length))
+
+  const lines = [
+    `facet v${version}`,
+    '',
+    'Usage: facet <command> [options]',
+    '',
+    'Commands:',
+    ...entries.map((c) => `  ${c.name.padEnd(maxNameLength + 2)}${c.description}`),
+    '',
+    'Options:',
+    '  --help       Show help',
+    '  --version    Show version',
+  ]
+
+  console.log(lines.join('\n'))
+}
+
+export function printCommandHelp(command: Command): void {
+  const lines = [
+    `Usage: facet ${command.name} [options]`,
+    '',
+    `  ${command.description}`,
+    '',
+    'Options:',
+    '  --help    Show help',
+  ]
+
+  console.log(lines.join('\n'))
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { run } from './run.ts'
+
+try {
+  const code = await run(process.argv.slice(2))
+  process.exit(code)
+} catch (error) {
+  console.error(error instanceof Error ? error.message : 'An unexpected error occurred.')
+  process.exit(2)
+}

package/src/run.ts

@@ -0,0 +1,55 @@
+import { parse } from '@bomb.sh/args'
+import { commands } from './commands.ts'
+import { printCommandHelp, printGlobalHelp } from './help.ts'
+import { findClosestCommand } from './suggest.ts'
+import { version } from './version.ts'
+
+export async function run(argv: string[]): Promise<number> {
+  const args = parse(argv, {
+    boolean: ['help', 'version'],
+  })
+
+  if (args.version) {
+    console.log(version)
+    return 0
+  }
+
+  const commandName = String(args._[0] ?? '')
+
+  // No command given — show global help
+  if (!commandName) {
+    printGlobalHelp()
+    return 0
+  }
+
+  // Explicit `help` command: `facets help` or `facets help build`
+  if (commandName === 'help') {
+    const subCommandName = String(args._[1] ?? '')
+    const subCommand = subCommandName ? commands[subCommandName] : undefined
+    if (subCommand) {
+      printCommandHelp(subCommand)
+    } else {
+      printGlobalHelp()
+    }
+    return 0
+  }
+
+  const command = commands[commandName]
+
+  if (!command) {
+    const suggestion = findClosestCommand(commandName, Object.keys(commands))
+    const message = suggestion
+      ? `Unknown command "${commandName}". Did you mean "${suggestion}"?`
+      : `Unknown command "${commandName}".`
+    console.error(message)
+    return 1
+  }
+
+  // Per-command help: `facets build --help`
+  if (args.help) {
+    printCommandHelp(command)
+    return 0
+  }
+
+  return command.run(argv.slice(1))
+}

package/src/suggest.ts

@@ -0,0 +1,35 @@
+function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const row: number[] = []
+
+  for (let j = 0; j <= n; j++) row.push(j)
+
+  for (let i = 1; i <= m; i++) {
+    let prev = row[0] ?? 0
+    row[0] = i
+    for (let j = 1; j <= n; j++) {
+      const current = row[j] ?? 0
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      row[j] = Math.min(current + 1, (row[j - 1] ?? 0) + 1, prev + cost)
+      prev = current
+    }
+  }
+
+  return row[n] ?? 0
+}
+
+export function findClosestCommand(input: string, commandNames: string[]): string | undefined {
+  let best: string | undefined
+  let bestDistance = Infinity
+
+  for (const name of commandNames) {
+    const distance = levenshtein(input, name)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = name
+    }
+  }
+
+  return bestDistance <= 3 ? best : undefined
+}

package/src/tui/components/asset-inline-input.tsx

@@ -0,0 +1,79 @@
+import { Box, Text, useInput } from 'ink'
+import TextInput from 'ink-text-input'
+import { THEME } from '../theme.ts'
+
+export function AssetInlineInput({
+  value,
+  placeholder,
+  error,
+  isFocused,
+  onChange,
+  validate,
+  onError,
+  onSubmit,
+  onCancel,
+}: {
+  id: string
+  value: string
+  placeholder?: string
+  error: string
+  isFocused: boolean
+  onChange: (value: string) => void
+  validate?: (value: string) => string | undefined
+  onError: (error: string) => void
+  onSubmit: (name: string) => void
+  onCancel: () => void
+}) {
+  useInput(
+    (_input, key) => {
+      if (!isFocused) return
+      if (key.return) {
+        const name = value || placeholder || ''
+        if (!name) {
+          onCancel()
+          return
+        }
+        if (validate) {
+          const err = validate(name)
+          if (err) {
+            onError(err)
+            return
+          }
+        }
+        onSubmit(name)
+        return
+      }
+      if (key.escape) {
+        onCancel()
+        return
+      }
+      if (key.tab && !value && placeholder) {
+        onChange(placeholder)
+        return
+      }
+    },
+    { isActive: isFocused },
+  )
+
+  return (
+    <Box marginLeft={2} gap={1}>
+      <Text color={THEME.tertiary}>{'>'}</Text>
+      <TextInput value={value} onChange={onChange} placeholder={placeholder} focus={isFocused} />
+      {error ? (
+        <Text color={THEME.warning}>· {error}</Text>
+      ) : value ? (
+        <Text color={THEME.hint}>
+          · <Text color={THEME.keyword}>Enter</Text> to save · <Text color={THEME.keyword}>Escape</Text> to revert
+        </Text>
+      ) : placeholder ? (
+        <Text color={THEME.hint}>
+          · <Text color={THEME.keyword}>Tab</Text> to fill · <Text color={THEME.keyword}>Escape</Text> to cancel
+        </Text>
+      ) : (
+        <Text color={THEME.hint}>
+          · <Text color={THEME.keyword}>Enter</Text> to add · <Text color={THEME.keyword}>Escape</Text> to cancel
+        </Text>
+      )}
+    </Box>
+  )
+}

package/src/tui/components/asset-item.tsx

@@ -0,0 +1,48 @@
+import { Box, Text, useInput } from 'ink'
+import { THEME } from '../theme.ts'
+
+export function AssetItem({
+  name,
+  isFocused,
+  onEdit,
+  onRemove,
+}: {
+  id: string
+  name: string
+  isFocused: boolean
+  onEdit: () => void
+  onRemove: () => void
+}) {
+  useInput(
+    (_input, key) => {
+      if (key.return) {
+        onEdit()
+      }
+      if (key.delete || key.backspace) {
+        onRemove()
+      }
+    },
+    { isActive: isFocused },
+  )
+
+  return (
+    <Box gap={1} marginLeft={2}>
+      {isFocused ? (
+        <>
+          <Text color={THEME.primary} bold>
+            ▸
+          </Text>
+          <Text color={THEME.primary}>{name}</Text>
+          <Text color={THEME.hint}>
+            <Text color={THEME.keyword}>Enter</Text> to edit · <Text color={THEME.keyword}>Delete</Text> to remove
+          </Text>
+        </>
+      ) : (
+        <>
+          <Text color={THEME.success}>•</Text>
+          <Text>{name}</Text>
+        </>
+      )}
+    </Box>
+  )
+}

package/src/tui/components/asset-section.tsx

@@ -0,0 +1,145 @@
+import { Box, Text } from 'ink'
+import { useState } from 'react'
+import { useFocusMode } from '../context/focus-mode-context.ts'
+import { useFocusOrder } from '../context/focus-order-context.ts'
+import type { AssetSectionKey } from '../context/form-state-context.ts'
+import { useFormState } from '../context/form-state-context.ts'
+import { AssetInlineInput } from './asset-inline-input.tsx'
+import { AssetItem } from './asset-item.tsx'
+import { Button } from './button.tsx'
+
+export function AssetSection({
+  section,
+  label,
+  defaultName,
+  dimmed,
+  validate,
+}: {
+  section: AssetSectionKey
+  label: string
+  defaultName?: string
+  dimmed?: boolean
+  validate?: (value: string) => string | undefined
+}) {
+  const { form, addAsset, removeAsset, renameAsset, setAssetAdding, setAssetEditing } = useFormState()
+  const { items, editing, adding } = form.assets[section]
+  const { setMode } = useFocusMode()
+  const { focusedId, focus } = useFocusOrder()
+  const [inputValue, setInputValue] = useState('')
+  const [error, setError] = useState('')
+
+  const startAdding = () => {
+    setAssetAdding(section, true)
+    setInputValue('')
+    setError('')
+    setMode('field-revision')
+  }
+
+  const startEditing = (name: string) => {
+    setAssetEditing(section, name)
+    setInputValue(name)
+    setError('')
+    setMode('field-revision')
+  }
+
+  const closeInput = () => {
+    setAssetAdding(section, false)
+    setAssetEditing(section, undefined)
+    setInputValue('')
+    setError('')
+    setMode('form-navigation')
+    focus(`add-${section}`)
+  }
+
+  const handleRemove = (name: string) => {
+    const index = items.indexOf(name)
+    removeAsset(section, name)
+
+    if (index < items.length - 1) {
+      focus(`item-${section}-${index}`)
+    } else if (index > 0) {
+      focus(`item-${section}-${index - 1}`)
+    } else {
+      focus(`add-${section}`)
+    }
+  }
+
+  return (
+    <Box flexDirection="column" gap={0}>
+      <Box gap={1}>
+        <Text bold dimColor={dimmed}>
+          {label}
+        </Text>
+        {items.length === 0 && !adding && <Text dimColor>(none)</Text>}
+      </Box>
+
+      {items.map((item, i) => {
+        const itemId = `item-${section}-${i}`
+        const isFocusedItem = focusedId === itemId
+
+        if (editing === item) {
+          return (
+            <AssetInlineInput
+              key={itemId}
+              id={itemId}
+              value={inputValue}
+              placeholder={item}
+              error={error}
+              isFocused={isFocusedItem}
+              onChange={setInputValue}
+              validate={validate}
+              onError={setError}
+              onSubmit={(newName) => {
+                renameAsset(section, item, newName)
+                closeInput()
+              }}
+              onCancel={closeInput}
+            />
+          )
+        }
+
+        return (
+          <AssetItem
+            key={itemId}
+            id={itemId}
+            name={item}
+            isFocused={isFocusedItem}
+            onEdit={() => startEditing(item)}
+            onRemove={() => handleRemove(item)}
+          />
+        )
+      })}
+
+      {adding ? (
+        <AssetInlineInput
+          id={`add-${section}`}
+          value={inputValue}
+          placeholder={defaultName}
+          error={error}
+          isFocused={focusedId === `add-${section}`}
+          onChange={setInputValue}
+          validate={validate}
+          onError={setError}
+          onSubmit={(name) => {
+            addAsset(section, name)
+            closeInput()
+          }}
+          onCancel={closeInput}
+        />
+      ) : (
+        <Box marginLeft={2}>
+          <Button
+            id={`add-${section}`}
+            label="+ Add"
+            hint={
+              <Text dimColor>
+                <Text>Enter</Text> to add
+              </Text>
+            }
+            onPress={startAdding}
+          />
+        </Box>
+      )}
+    </Box>
+  )
+}