agent-facets 0.1.2 → 0.2.1

package/src/commands/build.ts

@@ -2,12 +2,21 @@ import { render } from 'ink'
 import { createElement } from 'react'
 import type { Command } from '../commands.ts'
 import { BuildView } from '../tui/views/build/build-view.tsx'
+import { resolveTargetDir } from './resolve-dir.ts'
 
 export const buildCommand: Command = {
   name: 'build',
   description: 'Build a facet from the current directory',
-  run: async (args: string[]): Promise<number> => {
-    const rootDir = args[0] || process.cwd()
+  usage: '[directory]',
+  run: async (args: string[], _flags: Record<string, unknown>): Promise<number> => {
+    const resolved = await resolveTargetDir(args[0], { mustExist: true, facetMustExist: true })
+    if (!resolved.ok) {
+      console.error(resolved.message)
+      return 1
+    }
+
+    const rootDir = resolved.dir
+    const displayDir = resolved.display
 
     // Track result for stdout summary after Ink exits
     let buildName = ''
@@ -35,10 +44,14 @@ export const buildCommand: Command = {
       await instance.waitUntilExit()
       // Ink has unmounted — print stdout summary for scroll-back
       const shortHash = integrity.length > 20 ? `${integrity.slice(0, 20)}...` : integrity
-      process.stdout.write(`✓ Built ${buildName} v${buildVersion} → dist/ (${artifactCount} assets, ${shortHash})\n`)
+      process.stdout.write(
+        `✓ Built ${buildName} v${buildVersion} → ${displayDir}/dist/ (${artifactCount} assets, ${shortHash})\n`,
+      )
       return 0
     } catch {
-      process.stdout.write(`✗ Build failed — ${errorCount} error${errorCount !== 1 ? 's' : ''}\n`)
+      process.stdout.write(
+        `✗ Build failed — ${errorCount} error${errorCount !== 1 ? 's' : ''}. Run \`facet edit${args[0] ? ` ${displayDir}` : ''}\` to fix.\n`,
+      )
       return 1
     }
   },

package/src/commands/create/index.ts

@@ -1,15 +1,61 @@
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { FACET_MANIFEST_FILE } from '@agent-facets/core'
+import { type } from 'arktype'
 import type { Command } from '../../commands.ts'
 import { writeScaffold } from '../create-scaffold.ts'
+import { resolveTargetDir } from '../resolve-dir.ts'
 import { runCreateWizardInk } from './wizard.tsx'
 
 export type { CreateOptions } from '../create-scaffold.ts'
 export { writeScaffold } from '../create-scaffold.ts'
 
+const CreateFlags = type({ 'force?': 'boolean' })
+
+async function confirmOverwrite(display: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+  return new Promise((resolve) => {
+    rl.question(`A facet already exists in ${display}. Overwrite? (y/N) `, (answer) => {
+      rl.close()
+      resolve(answer.toLowerCase() === 'y')
+    })
+  })
+}
+
 export const createCommand: Command = {
   name: 'create',
   description: 'Create a new facet project interactively',
-  run: async (args: string[]): Promise<number> => {
-    const targetDir = args[0] || process.cwd()
+  usage: '[directory]',
+  flags: {
+    force: { type: 'boolean', description: 'Overwrite existing facet.json' },
+  },
+  run: async (args: string[], flags: Record<string, unknown>): Promise<number> => {
+    const resolved = await resolveTargetDir(args[0], { mustExist: false })
+    if (!resolved.ok) {
+      console.error(resolved.message)
+      return 1
+    }
+
+    const targetDir = resolved.dir
+    const displayDir = resolved.display
+
+    // Validate flags via Arktype
+    const validatedFlags = CreateFlags(flags)
+    if (validatedFlags instanceof type.errors) {
+      console.error(`Invalid flags: ${validatedFlags.summary}`)
+      return 1
+    }
+
+    // Overwrite protection
+    const manifestExists = await Bun.file(join(targetDir, FACET_MANIFEST_FILE)).exists()
+    if (manifestExists && !validatedFlags.force) {
+      const confirmed = await confirmOverwrite(displayDir)
+      if (!confirmed) {
+        console.log('Cancelled.')
+        return 1
+      }
+    }
 
     const opts = await runCreateWizardInk()
     if (!opts) {
@@ -19,11 +65,11 @@ export const createCommand: Command = {
 
     const files = await writeScaffold(opts, targetDir)
 
-    console.log(`\nFacet created: ${opts.name}`)
+    console.log(`\nFacet created: ${opts.name} → ${displayDir}`)
     for (const file of files) {
-      console.log(`  ${file}`)
+      console.log(`  ${displayDir}/${file}`)
     }
-    console.log('\nRun "facet build" to validate your facet.')
+    console.log(`\nRun "facet build${args[0] ? ` ${displayDir}` : ''}" to validate your facet.`)
 
     return 0
   },

package/src/commands/create/wizard.tsx

@@ -1,24 +1,75 @@
 import { render } from 'ink'
+import type { AssetSectionKey } from '../../tui/context/form-state-context.ts'
+import { openInEditorSync } from '../../tui/editor.ts'
+import type { WizardSnapshot } from '../../tui/views/create/wizard.tsx'
 import { CreateWizard } from '../../tui/views/create/wizard.tsx'
 import type { CreateOptions } from '../create-scaffold.ts'
 
+interface EditorRequest {
+  section: AssetSectionKey
+  name: string
+  description: string
+}
+
 export async function runCreateWizardInk(): Promise<CreateOptions | null> {
-  return new Promise<CreateOptions | null>((resolve) => {
-    let result: CreateOptions | null = null
+  let result: CreateOptions | null = null
+  let snapshot: WizardSnapshot | undefined
+  let pendingEditor: EditorRequest | null = null
+  let done = false
+
+  while (!done) {
+    pendingEditor = null
 
-    const instance = render(
-      <CreateWizard
-        onComplete={(opts) => {
-          result = opts
-        }}
-        onCancel={() => {
-          result = null
-        }}
-      />,
-    )
+    await new Promise<void>((resolve) => {
+      const instance = render(
+        <CreateWizard
+          snapshot={snapshot}
+          onComplete={(opts) => {
+            result = opts
+          }}
+          onCancel={() => {
+            result = null
+          }}
+          onSnapshot={(s) => {
+            snapshot = s
+          }}
+          onRequestEditor={(section, name, description) => {
+            pendingEditor = { section, name, description }
+            instance.unmount()
+          }}
+        />,
+      )
 
-    instance.waitUntilExit().then(() => {
-      resolve(result)
+      instance.waitUntilExit().then(() => resolve())
     })
-  })
+
+    if (pendingEditor) {
+      const req = pendingEditor as EditorRequest
+      const edited = openInEditorSync(req.description, `${req.name}.md`)
+      if (snapshot) {
+        const section = snapshot.form.assets[req.section]
+        snapshot = {
+          ...snapshot,
+          selectedItem: undefined,
+          form: {
+            ...snapshot.form,
+            assets: {
+              ...snapshot.form.assets,
+              [req.section]: {
+                ...section,
+                descriptions: {
+                  ...section.descriptions,
+                  ...(edited !== null ? { [req.name]: edited.trim() } : {}),
+                },
+              },
+            },
+          },
+        }
+      }
+    } else {
+      done = true
+    }
+  }
+
+  return result
 }

package/src/commands/create-scaffold.ts

@@ -1,6 +1,6 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import { FACET_MANIFEST_FILE } from '@agent-facets/core'
+import { FACET_MANIFEST_FILE, KEBAB_CASE } from '@agent-facets/core'
 
 // --- Types ---
 
@@ -13,9 +13,13 @@ export interface CreateOptions {
   commands: string[]
 }
 
+// --- Defaults ---
+
+export const DEFAULT_VERSION = '0.0.0'
+
 // --- Validation ---
 
-export const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+export { KEBAB_CASE }
 export const SEMVER = /^\d+\.\d+\.\d+$/
 
 export function isValidKebabCase(value: string): boolean {
@@ -35,7 +39,7 @@ function toTitleCase(kebab: string): string {
     .join(' ')
 }
 
-function skillTemplate(name: string): string {
+export function skillTemplate(name: string): string {
   return `# ${toTitleCase(name)}
 
 <!-- This is a starter skill template. Replace this content with your skill's instructions. -->
@@ -54,7 +58,7 @@ Describe what this skill teaches or what guidelines it provides.
 `
 }
 
-function agentTemplate(name: string): string {
+export function agentTemplate(name: string): string {
   return `# ${toTitleCase(name)}
 
 <!-- This is a starter agent template. Replace this content with your agent's prompt. -->
@@ -72,7 +76,7 @@ Describe this agent's role and responsibilities.
 `
 }
 
-function commandTemplate(name: string): string {
+export function commandTemplate(name: string): string {
   return `# ${toTitleCase(name)}
 
 <!-- This is a starter command template. Replace this content with your command's prompt. -->
@@ -134,7 +138,7 @@ export function generateManifest(opts: CreateOptions): string {
 export function previewFiles(opts: CreateOptions): string[] {
   const files: string[] = [FACET_MANIFEST_FILE]
   for (const skill of opts.skills) {
-    files.push(`skills/${skill}.md`)
+    files.push(`skills/${skill}/SKILL.md`)
   }
   for (const agent of opts.agents) {
     files.push(`agents/${agent}.md`)
@@ -155,11 +159,11 @@ export async function writeScaffold(opts: CreateOptions, targetDir: string): Pro
   await Bun.write(manifestPath, generateManifest(opts))
   files.push(FACET_MANIFEST_FILE)
 
-  // Write skill files
+  // Write skill files (Agent Skills directory convention: skills/<name>/SKILL.md)
   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`)
+    await mkdir(join(targetDir, 'skills', skill), { recursive: true })
+    await Bun.write(join(targetDir, `skills/${skill}/SKILL.md`), skillTemplate(skill))
+    files.push(`skills/${skill}/SKILL.md`)
   }
 
   // Write agent files

package/src/commands/edit/index.ts

@@ -0,0 +1,144 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  type FacetManifest,
+  hasFrontMatter,
+  loadManifest,
+  reconcile,
+  scanAssets,
+  writeManifest,
+} from '@agent-facets/core'
+import type { Command } from '../../commands.ts'
+import type { EditContext, EditOperation, EditResult, ReconciliationItem } from '../../tui/views/edit/edit-types.ts'
+import { agentTemplate, commandTemplate, skillTemplate } from '../create-scaffold.ts'
+import { resolveTargetDir } from '../resolve-dir.ts'
+import { runEditWizardInk } from './wizard.tsx'
+
+export async function buildEditContext(
+  rootDir: string,
+): Promise<{ ok: true; context: EditContext } | { ok: false; exitCode: number }> {
+  // Load manifest
+  const loadResult = await loadManifest(rootDir)
+  if (!loadResult.ok) {
+    // Hard error — show errors and exit
+    console.error('Manifest is invalid:')
+    for (const err of loadResult.errors) {
+      console.error(`  ${err.message}`)
+    }
+    console.error('\nFix facet.json and try again.')
+    return { ok: false, exitCode: 1 }
+  }
+
+  const manifest = loadResult.data
+
+  // Scan disk for assets
+  const discovered = await scanAssets(rootDir)
+
+  // Run reconciliation
+  const recon = reconcile(manifest, discovered)
+
+  // Build reconciliation items
+  const items: ReconciliationItem[] = []
+
+  for (const addition of recon.additions) {
+    items.push({ kind: 'addition', type: addition.type, name: addition.name, path: addition.path })
+  }
+
+  for (const missing of recon.missing) {
+    items.push({ kind: 'missing', type: missing.type, name: missing.name, expectedPath: missing.expectedPath })
+  }
+
+  // Check matched assets for front matter
+  for (const matched of recon.matched) {
+    const filePath = join(rootDir, matched.path)
+    const content = await Bun.file(filePath).text()
+    if (hasFrontMatter(content)) {
+      items.push({ kind: 'front-matter', type: matched.type, name: matched.name, path: matched.path })
+    }
+  }
+
+  return { ok: true, context: { rootDir, manifest, reconciliationItems: items } }
+}
+
+export async function applyOperations(
+  manifest: FacetManifest,
+  operations: EditOperation[],
+  rootDir: string,
+): Promise<void> {
+  for (const op of operations) {
+    switch (op.op) {
+      case 'write-manifest':
+        await writeManifest(manifest, rootDir)
+        break
+
+      case 'scaffold': {
+        if (op.type === 'skills') {
+          const dir = join(rootDir, 'skills', op.name)
+          await mkdir(dir, { recursive: true })
+          await Bun.write(join(dir, 'SKILL.md'), skillTemplate(op.name))
+        } else if (op.type === 'agents') {
+          await mkdir(join(rootDir, 'agents'), { recursive: true })
+          await Bun.write(join(rootDir, `agents/${op.name}.md`), agentTemplate(op.name))
+        } else if (op.type === 'commands') {
+          await mkdir(join(rootDir, 'commands'), { recursive: true })
+          await Bun.write(join(rootDir, `commands/${op.name}.md`), commandTemplate(op.name))
+        }
+        break
+      }
+
+      case 'delete-file': {
+        const path =
+          op.type === 'skills' ? join(rootDir, 'skills', op.name, 'SKILL.md') : join(rootDir, op.type, `${op.name}.md`)
+        try {
+          const { unlink } = await import('node:fs/promises')
+          await unlink(path)
+        } catch {
+          // File already gone — that's fine
+        }
+        break
+      }
+
+      case 'strip-front-matter': {
+        const { extractFrontMatter } = await import('@agent-facets/core')
+        const filePath = join(rootDir, op.path)
+        const raw = await Bun.file(filePath).text()
+        const { content } = extractFrontMatter(raw)
+        await Bun.write(filePath, content)
+        break
+      }
+    }
+  }
+}
+
+export const editCommand: Command = {
+  name: 'edit',
+  description: 'Edit a facet project interactively',
+  usage: '[directory]',
+  run: async (args: string[], _flags: Record<string, unknown>): Promise<number> => {
+    const resolved = await resolveTargetDir(args[0], { mustExist: true, facetMustExist: true })
+    if (!resolved.ok) {
+      console.error(resolved.message)
+      return 1
+    }
+
+    const rootDir = resolved.dir
+    const displayDir = resolved.display
+
+    const loaded = await buildEditContext(rootDir)
+    if (!loaded.ok) return loaded.exitCode
+
+    const result: EditResult = await runEditWizardInk(loaded.context)
+
+    if (result.outcome === 'cancelled') {
+      console.log('\nCancelled — no changes applied.')
+      return 1
+    }
+
+    await applyOperations(result.manifest, result.operations, rootDir)
+
+    console.log(`\nChanges applied to ${displayDir}`)
+    console.log(`Run "facet build${args[0] ? ` ${displayDir}` : ''}" to validate your facet.`)
+
+    return 0
+  },
+}

package/src/commands/edit/wizard.tsx

@@ -0,0 +1,74 @@
+import { render } from 'ink'
+import type { AssetSectionKey } from '../../tui/context/form-state-context.ts'
+import { openInEditorSync } from '../../tui/editor.ts'
+import type { EditContext, EditResult } from '../../tui/views/edit/edit-types.ts'
+import type { EditWizardSnapshot } from '../../tui/views/edit/wizard.tsx'
+import { EditWizard } from '../../tui/views/edit/wizard.tsx'
+
+interface EditorRequest {
+  section: AssetSectionKey
+  name: string
+  description: string
+}
+
+export async function runEditWizardInk(context: EditContext): Promise<EditResult> {
+  let result: EditResult = { outcome: 'cancelled' }
+  let snapshot: EditWizardSnapshot | undefined
+  let pendingEditor: EditorRequest | null = null
+  let done = false
+
+  while (!done) {
+    pendingEditor = null
+
+    await new Promise<void>((resolve) => {
+      const instance = render(
+        <EditWizard
+          context={context}
+          snapshot={snapshot}
+          onComplete={(r) => {
+            result = r
+          }}
+          onSnapshot={(s) => {
+            snapshot = s
+          }}
+          onRequestEditor={(section, name, description) => {
+            pendingEditor = { section, name, description }
+            instance.unmount()
+          }}
+        />,
+      )
+
+      instance.waitUntilExit().then(() => resolve())
+    })
+
+    if (pendingEditor) {
+      const req = pendingEditor as EditorRequest
+      const edited = openInEditorSync(req.description, `${req.name}.md`)
+      if (snapshot) {
+        snapshot = {
+          ...snapshot,
+          selectedItem: undefined,
+          formState: snapshot.formState
+            ? {
+                ...snapshot.formState,
+                assets: {
+                  ...snapshot.formState.assets,
+                  [req.section]: {
+                    ...snapshot.formState.assets[req.section],
+                    descriptions: {
+                      ...snapshot.formState.assets[req.section].descriptions,
+                      ...(edited !== null ? { [req.name]: edited.trim() } : {}),
+                    },
+                  },
+                },
+              }
+            : undefined,
+        }
+      }
+    } else {
+      done = true
+    }
+  }
+
+  return result
+}

package/src/commands/resolve-dir.ts

@@ -0,0 +1,98 @@
+import { mkdir, stat } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { FACET_MANIFEST_FILE } from '@agent-facets/core'
+
+export interface ResolvedDir {
+  ok: true
+  dir: string
+  display: string
+}
+
+export interface ResolvedDirError {
+  ok: false
+  message: string
+}
+
+export type ResolveResult = ResolvedDir | ResolvedDirError
+
+export interface ResolveOptions {
+  mustExist: boolean
+  facetMustExist?: boolean
+}
+
+/**
+ * Validates and resolves a directory argument for CLI commands.
+ *
+ * Handles:
+ * - No argument → uses process.cwd(), display as '.'
+ * - Argument ending with facet.json → silently uses parent directory
+ * - Argument is a non-directory file → error
+ * - Directory doesn't exist + mustExist false → auto-creates it
+ * - Directory doesn't exist + mustExist true → error
+ * - facetMustExist true but no facet.json → error
+ */
+export async function resolveTargetDir(arg: string | undefined, opts: ResolveOptions): Promise<ResolveResult> {
+  const display = arg || '.'
+
+  // No argument → current directory
+  if (!arg) {
+    const dir = process.cwd()
+
+    if (opts.facetMustExist) {
+      const manifestExists = await Bun.file(join(dir, FACET_MANIFEST_FILE)).exists()
+      if (!manifestExists) {
+        return { ok: false, message: `No ${FACET_MANIFEST_FILE} found in ${display}` }
+      }
+    }
+
+    return { ok: true, dir, display }
+  }
+
+  // Pointing to facet.json directly → use parent directory
+  if (arg === FACET_MANIFEST_FILE || arg.endsWith(`/${FACET_MANIFEST_FILE}`)) {
+    const dir = resolve(dirname(arg))
+
+    const dirStat = await stat(dir).catch(() => null)
+    if (!dirStat?.isDirectory()) {
+      return { ok: false, message: `Directory does not exist: ${dirname(arg)}` }
+    }
+
+    if (opts.facetMustExist) {
+      const manifestExists = await Bun.file(join(dir, FACET_MANIFEST_FILE)).exists()
+      if (!manifestExists) {
+        return { ok: false, message: `No ${FACET_MANIFEST_FILE} found in ${display}` }
+      }
+    }
+
+    return { ok: true, dir, display: dirname(arg) || '.' }
+  }
+
+  // Check if the path exists
+  const pathStat = await stat(arg).catch(() => null)
+
+  // Path exists but is a file, not a directory
+  if (pathStat && !pathStat.isDirectory()) {
+    return { ok: false, message: `Expected a directory, not a file: ${arg}` }
+  }
+
+  // Path doesn't exist
+  if (!pathStat) {
+    if (opts.mustExist) {
+      return { ok: false, message: `Directory does not exist: ${arg}` }
+    }
+
+    // Auto-create for commands that allow it (e.g., create)
+    await mkdir(arg, { recursive: true })
+  }
+
+  const dir = resolve(arg)
+
+  if (opts.facetMustExist) {
+    const manifestExists = await Bun.file(join(dir, FACET_MANIFEST_FILE)).exists()
+    if (!manifestExists) {
+      return { ok: false, message: `No ${FACET_MANIFEST_FILE} found in ${display}` }
+    }
+  }
+
+  return { ok: true, dir, display }
+}

package/src/commands.ts

@@ -1,17 +1,25 @@
 import { buildCommand } from './commands/build.ts'
 import { createCommand } from './commands/create/index.ts'
+import { editCommand } from './commands/edit/index.ts'
+
+export type FlagDef = {
+  type: 'boolean' | 'string'
+  description: string
+}
 
 export type Command = {
   name: string
   description: string
-  run: (args: string[]) => Promise<number>
+  usage?: string
+  flags?: Record<string, FlagDef>
+  run: (args: string[], flags: Record<string, unknown>) => Promise<number>
 }
 
 function stubCommand(name: string, description: string): Command {
   return {
     name,
     description,
-    run: async () => {
+    run: async (_args, _flags) => {
       console.log(`"${name}" is not yet implemented.`)
       return 0
     },
@@ -22,6 +30,7 @@ export const commands: Record<string, Command> = {
   add: stubCommand('add', 'Add a facet to the project'),
   build: buildCommand,
   create: createCommand,
+  edit: editCommand,
   info: stubCommand('info', 'Show information about a facet'),
   install: stubCommand('install', 'Install all facets from the lockfile'),
   list: stubCommand('list', 'List installed facets'),

package/src/help.ts

@@ -1,8 +1,7 @@
 import type { Command } from './commands.ts'
-import { commands } from './commands.ts'
 import { version } from './version.ts'
 
-export function printGlobalHelp(): void {
+export function printGlobalHelp(commands: Record<string, Command>): void {
   const entries = Object.values(commands)
   const maxNameLength = Math.max(...entries.map((c) => c.name.length))
 
@@ -23,14 +22,22 @@ export function printGlobalHelp(): void {
 }
 
 export function printCommandHelp(command: Command): void {
-  const lines = [
-    `Usage: facet ${command.name} [options]`,
-    '',
-    `  ${command.description}`,
-    '',
-    'Options:',
-    '  --help    Show help',
-  ]
+  const usage = command.usage ? ` ${command.usage}` : ''
+
+  const lines = [`Usage: facet ${command.name}${usage} [options]`, '', `  ${command.description}`, '', 'Options:']
+
+  if (command.flags) {
+    const flagEntries = Object.entries(command.flags)
+    const maxFlagLength = Math.max(...flagEntries.map(([name]) => `--${name}`.length), '--help'.length)
+
+    for (const [name, def] of flagEntries) {
+      lines.push(`  ${`--${name}`.padEnd(maxFlagLength + 4)}${def.description}`)
+    }
+
+    lines.push(`  ${'--help'.padEnd(maxFlagLength + 4)}Show help`)
+  } else {
+    lines.push('  --help    Show help')
+  }
 
   console.log(lines.join('\n'))
 }

package/src/index.ts

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