@guidobuilds/forge-ai 0.2.0 → 0.5.0

package/dist/src/adapters/grok.js

@@ -0,0 +1,41 @@
+import { stringifyYaml } from '../frontmatter.js';
+import { diagnostic } from '../diagnostics.js';
+import { isKnownGrokModel, isKnownGrokTool } from './grok-known.js';
+import { isRecord, patternList, stringList } from './shared.js';
+export function renderGrokAgent(artifact) {
+    const diagnostics = [];
+    const fm = { name: artifact.name, description: artifact.description };
+    if (artifact.grok?.model) {
+        fm.model = artifact.grok.model;
+        if (!isKnownGrokModel(artifact.grok.model)) {
+            diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_MODEL', `Unknown Grok model "${artifact.grok.model}" for ${artifact.name}`, { platform: 'grok' }));
+        }
+    }
+    const permissions = artifact.grok?.permissions;
+    const tools = isRecord(permissions) ? stringList(permissions.tools) : stringList(permissions);
+    if (tools) {
+        fm.tools = tools; // YAML sequence — Grok expects tools as a list, not comma-joined
+        for (const tool of tools) {
+            if (!isKnownGrokTool(tool)) {
+                diagnostics.push(diagnostic('warning', 'GROK_UNKNOWN_TOOL', `Unknown Grok tool "${tool}" for ${artifact.name}`, { platform: 'grok' }));
+            }
+        }
+    }
+    else if (permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_AGENT_TOOLS_IGNORED', `Grok agent permissions must be a tools string list for ${artifact.name}`, { platform: 'grok' }));
+    }
+    const disallowedTools = isRecord(permissions) ? patternList(permissions['disallowedTools']) : undefined;
+    if (disallowedTools)
+        fm.disallowedTools = disallowedTools;
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics };
+}
+export function renderGrokSkill(artifact) {
+    const diagnostics = [];
+    if (artifact.grok?.permissions !== undefined) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_PERMISSIONS_IGNORED', `Grok skill permissions are not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    if (artifact.grok?.model) {
+        diagnostics.push(diagnostic('info', 'GROK_SKILL_MODEL_IGNORED', `Grok skill model is not emitted for ${artifact.name}`, { platform: 'grok' }));
+    }
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
+}

package/dist/src/adapters/opencode.js

@@ -1,20 +1,20 @@
 import { stringifyYaml } from '../frontmatter.js';
 import { diagnostic } from '../diagnostics.js';
-export function renderOpenCodeAgent(agent) {
-    const fm = { description: agent.description };
-    if (agent.opencode?.mode)
-        fm.mode = agent.opencode.mode;
-    if (agent.opencode?.model)
-        fm.model = agent.opencode.model;
-    if (agent.opencode?.permissions)
-        fm.permission = agent.opencode.permissions;
-    return { content: `${stringifyYaml(fm)}${agent.definition}\n`, diagnostics: [] };
+export function renderOpenCodeAgent(artifact) {
+    const fm = { description: artifact.description };
+    if (artifact.opencode?.mode)
+        fm.mode = artifact.opencode.mode;
+    if (artifact.opencode?.model)
+        fm.model = artifact.opencode.model;
+    if (artifact.opencode?.permissions)
+        fm.permission = artifact.opencode.permissions;
+    return { content: `${stringifyYaml(fm)}${artifact.body}\n`, diagnostics: [] };
 }
-export function renderOpenCodeSkill(skill) {
+export function renderOpenCodeSkill(artifact) {
     const diagnostics = [];
-    if (skill.opencode?.permissions)
-        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${skill.name}`, { platform: 'opencode' }));
-    if (skill.opencode?.model)
-        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${skill.name}`, { platform: 'opencode' }));
-    return { content: `${stringifyYaml({ name: skill.name, description: skill.description })}${skill.instructions}\n`, diagnostics };
+    if (artifact.opencode?.permissions)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_PERMISSIONS_IGNORED', `OpenCode skill permissions are not emitted for ${artifact.name}`, { platform: 'opencode' }));
+    if (artifact.opencode?.model)
+        diagnostics.push(diagnostic('info', 'OPENCODE_SKILL_MODEL_IGNORED', `OpenCode skill model is not emitted for ${artifact.name}`, { platform: 'opencode' }));
+    return { content: `${stringifyYaml({ name: artifact.name, description: artifact.description })}${artifact.body}\n`, diagnostics };
 }

package/dist/src/adapters/shared.js

@@ -1,8 +1,13 @@
 export function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
+const toolNamePattern = /^[A-Za-z0-9_*-]+$/;
+const patternBodyPattern = /^[^,\n]+$/;
 export function stringList(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string' && /^[A-Za-z0-9_*.,:-]+$/.test(item)) ? value : undefined;
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && toolNamePattern.test(item)) ? value : undefined;
+}
+export function patternList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0 && patternBodyPattern.test(item)) ? value : undefined;
 }
 export function tomlString(value) {
     return JSON.stringify(value);

package/dist/src/cli.js

@@ -6,9 +6,13 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { formatDiagnostic, hasErrors } from './diagnostics.js';
-import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
+import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
 import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
+import { runSelfUpdate } from './self-update.js';
+import { checkLatestVersion, formatVersionNotice } from './version-check.js';
 import { writeOutputs } from './writer.js';
+import { hasPendingDecisions } from './model.js';
+const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [] };
 export async function main(argv = process.argv.slice(2), promptIO = {}) {
     if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
         showUsage();
@@ -30,88 +34,129 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         showUsage();
         return 1;
     }
-    const install = command === 'install' || command === 'update';
-    if (install && !options.sourceExplicit)
-        options.source = bundledSourceRoot();
-    if (command === 'update' || options.yes)
-        options.force = true;
-    const interactive = install && isInteractivePrompt(promptIO);
-    if (interactive)
-        p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
-    if (install) {
-        const prompted = await promptForMissingInstallOptions(options, promptIO);
-        if (!prompted) {
-            if (interactive)
+    if (command === 'self-update') {
+        return runSelfUpdate({
+            binaryPath: process.argv[1] ?? bundledSourceRoot(),
+            version: options.targetVersion,
+            dryRun: options.dryRun,
+            skipSpecUpdate: options.skipSpecUpdate,
+        });
+    }
+    const versionCheckPromise = shouldCheckForUpdates(options, promptIO)
+        ? checkLatestVersion({ current: readPackageVersion(), cachePath: path.join(resolveHome(promptIO), '.forge-ai', 'version-check.json') }).catch(() => undefined)
+        : Promise.resolve(undefined);
+    try {
+        const install = command === 'install' || command === 'update';
+        if (install && !options.sourceExplicit)
+            options.source = bundledSourceRoot();
+        if (command === 'update' || options.yes)
+            options.force = true;
+        const interactive = install && isInteractivePrompt(promptIO);
+        if (interactive)
+            p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
+        if (install) {
+            const prompted = await promptForMissingInstallOptions(options, promptIO);
+            if (!prompted) {
+                if (interactive)
+                    p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
+        }
+        const cwd = process.cwd();
+        const home = resolveHome(promptIO);
+        const now = new Date();
+        let manifestLocation;
+        let oldManifest;
+        let backupRoot;
+        if (install) {
+            manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+            oldManifest = await loadManifest(manifestLocation.manifestPath);
+            backupRoot = resolveBackupRoot(manifestLocation, now);
+        }
+        const plan = await buildWritePlan({
+            source: options.source,
+            platform: options.platform,
+            scope: options.scope,
+            cwd,
+            home,
+            manifest: oldManifest,
+            backupRoot,
+            checkCollisions: install,
+        });
+        let prunePlan = emptyPrunePlan;
+        if (install && command === 'update' && options.prune) {
+            prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home);
+        }
+        const needsConfirm = install && !options.force && (hasPendingDecisions(plan.pending) || prunePlan.modifiedWithConsent.length > 0);
+        if (install && !options.dryRun && needsConfirm) {
+            if (!interactive) {
+                printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+                console.error('Forge needs your decision on edited or untracked files; re-run with --yes or --force to accept overwrites + backups.');
+                return 1;
+            }
+            const accepted = await promptForUpdate(plan, prunePlan, backupRoot, promptIO);
+            if (accepted === undefined) {
                 p.cancel('Cancelled', clackIO(promptIO));
-            return 1;
+                return 1;
+            }
+            if (!accepted) {
+                p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+                return 1;
+            }
         }
-    }
-    const cwd = process.cwd();
-    const home = resolveHome(promptIO);
-    let plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, cwd, home, checkCollisions: install && !options.dryRun, force: options.force });
-    if (install && !options.dryRun && !options.force && canOfferUpdate(plan.diagnostics)) {
-        const accepted = await promptForUpdate(plan, promptIO);
-        if (accepted === undefined) {
+        printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
+        if (hasErrors(plan.diagnostics)) {
             if (interactive)
-                p.cancel('Cancelled', clackIO(promptIO));
+                p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
             return 1;
         }
-        if (accepted) {
-            options.force = true;
-            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, cwd, home, checkCollisions: true, force: true });
-        }
-    }
-    let prunePlan = { deletable: [], skipped: [] };
-    let manifestLocation;
-    if (install) {
-        manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
-        const oldManifest = await loadManifest(manifestLocation.manifestPath);
-        if (command === 'update' && options.prune)
-            prunePlan = await classifyPruneEntries(staleEntries(oldManifest, plan.files));
-    }
-    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics, prunePlan);
-    if (hasErrors(plan.diagnostics)) {
-        if (interactive)
-            p.outro(pc.red('Forge was not installed.'), clackIO(promptIO));
-        return 1;
-    }
-    if (install && !options.dryRun) {
-        if (interactive) {
-            const spinner = p.spinner(clackIO(promptIO));
-            spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
-            try {
+        if (install && !options.dryRun) {
+            if (interactive) {
+                const spinner = p.spinner(clackIO(promptIO));
+                spinner.start(options.force ? 'Updating Forge files' : 'Installing Forge files');
+                try {
+                    await writeOutputs(plan.files);
+                    if (command === 'update' && options.prune)
+                        await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
+                    await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
+                    spinner.stop(`Wrote ${plan.files.length} file(s).`);
+                }
+                catch (error) {
+                    spinner.error('Failed to write Forge files');
+                    throw error;
+                }
+            }
+            else {
                 await writeOutputs(plan.files);
                 if (command === 'update' && options.prune)
-                    await pruneEntries(prunePlan.deletable);
-                await saveManifest(manifestLocation.manifestPath, buildManifest(manifestLocation, plan.files));
-                spinner.stop(`Wrote ${plan.files.length} file(s).`);
-            }
-            catch (error) {
-                spinner.error('Failed to write Forge files');
-                throw error;
+                    await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
+                await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
+                console.log(`Wrote ${plan.files.length} file(s).`);
+                const totalDeleted = prunePlan.deletable.length + prunePlan.modifiedWithConsent.length;
+                if (command === 'update' && options.prune && totalDeleted > 0)
+                    console.log(`Deleted ${totalDeleted} stale file(s).`);
+                console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
             }
         }
-        else {
-            await writeOutputs(plan.files);
-            if (command === 'update' && options.prune)
-                await pruneEntries(prunePlan.deletable);
-            await saveManifest(manifestLocation.manifestPath, buildManifest(manifestLocation, plan.files));
-            console.log(`Wrote ${plan.files.length} file(s).`);
-            if (command === 'update' && options.prune && prunePlan.deletable.length > 0)
-                console.log(`Deleted ${prunePlan.deletable.length} stale file(s).`);
-            console.log(`Updated manifest ${manifestLocation.manifestPath}.`);
+        else if (install && interactive) {
+            p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
         }
+        if (install && interactive) {
+            p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+        }
+        return 0;
     }
-    else if (install && interactive) {
-        p.log.info(`Dry run only. ${plan.files.length} file(s) would be written.`, clackIO(promptIO));
-    }
-    if (install && interactive) {
-        p.outro(options.dryRun ? pc.cyan('Dry run complete.') : pc.green('Forge is ready.'), clackIO(promptIO));
+    finally {
+        const result = await versionCheckPromise;
+        if (result) {
+            const notice = formatVersionNotice(result);
+            if (notice)
+                console.log(notice);
+        }
     }
-    return 0;
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
+    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, noUpdateCheck: false, skipSpecUpdate: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
@@ -122,6 +167,16 @@ function parseArgs(argv) {
             options.prune = false;
         else if (arg === '--yes' || arg === '-y')
             options.yes = true;
+        else if (arg === '--no-update-check')
+            options.noUpdateCheck = true;
+        else if (arg === '--skip-spec-update')
+            options.skipSpecUpdate = true;
+        else if (arg === '--to') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --to value' };
+            options.targetVersion = value;
+        }
         else if (arg === '--platform') {
             const value = argv[++index];
             const platform = value ? parsePlatform(value) : undefined;
@@ -154,8 +209,26 @@ function parseArgs(argv) {
         return { error: '--no-prune is only accepted for update' };
     if (command === 'validate' && (options.dryRun || options.force || options.yes || options.scopeExplicit))
         return { error: 'validate only accepts --platform and --source' };
+    if (command !== 'self-update' && (options.targetVersion !== undefined || options.skipSpecUpdate))
+        return { error: '--to and --skip-spec-update are only accepted for self-update' };
+    if (command === 'self-update' && (options.platformExplicit || options.scopeExplicit || options.sourceExplicit || options.force || options.yes))
+        return { error: 'self-update only accepts --to, --dry-run, --skip-spec-update' };
     return { options };
 }
+async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home) {
+    const stale = staleEntries(oldManifest, files);
+    const classified = await classifyPruneEntries(stale);
+    const anchor = scope === 'user' ? home : cwd;
+    const modifiedWithConsent = [];
+    const skippedMissing = [];
+    for (const item of classified.skipped) {
+        if (item.reason === 'checksum-mismatch')
+            modifiedWithConsent.push({ ...item, backupPath: resolveBackupPath(backupRoot, item.path, anchor) });
+        else
+            skippedMissing.push(item);
+    }
+    return { deletable: classified.deletable, modifiedWithConsent, skippedMissing };
+}
 async function promptForMissingInstallOptions(options, promptIO) {
     if (options.yes)
         return true;
@@ -169,10 +242,11 @@ async function promptForMissingInstallOptions(options, promptIO) {
             message: 'Install Forge for which coding agent?',
             initialValue: 'all',
             options: [
-                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, and Claude Code' },
+                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, Claude Code, and Grok Build' },
                 { value: 'opencode', label: 'OpenCode' },
                 { value: 'codex', label: 'Codex' },
-                { value: 'claude', label: 'Claude Code' }
+                { value: 'claude', label: 'Claude Code' },
+                { value: 'grok', label: 'Grok Build' }
             ],
             ...io
         });
@@ -196,18 +270,27 @@ async function promptForMissingInstallOptions(options, promptIO) {
     }
     return true;
 }
-async function promptForUpdate(plan, promptIO) {
+async function promptForUpdate(plan, prunePlan, backupRoot, promptIO) {
     if (!isInteractivePrompt(promptIO))
         return false;
-    const existing = plan.diagnostics.filter((item) => item.code === 'DESTINATION_EXISTS');
-    const count = existing.length;
-    p.log.warn(`${count} Forge output${count === 1 ? '' : 's'} already exist.`, clackIO(promptIO));
+    const io = clackIO(promptIO);
+    const sections = [];
+    if (plan.pending.modifiedOverwrites.length > 0) {
+        sections.push(`${pc.yellow('Edited by you, will be overwritten (backup):')}\n${plan.pending.modifiedOverwrites.map((file) => `  - ${file.path}`).join('\n')}`);
+    }
+    if (prunePlan.modifiedWithConsent.length > 0) {
+        sections.push(`${pc.yellow('Edited by you, will be deleted (backup):')}\n${prunePlan.modifiedWithConsent.map((entry) => `  - ${entry.path}`).join('\n')}`);
+    }
+    if (plan.pending.foreignOverwrites.length > 0) {
+        sections.push(`${pc.yellow('Untracked files in Forge install paths, will be overwritten:')}\n${plan.pending.foreignOverwrites.map((file) => `  - ${file.path}`).join('\n')}`);
+    }
+    p.log.warn(`The following actions need your confirmation:\n\n${sections.join('\n\n')}\n\nBackups → ${backupRoot ?? '(none)'}`, io);
     const accepted = await p.confirm({
-        message: 'Update the existing Forge files?',
-        active: 'Update',
+        message: 'Continue with overwrites + backups?',
+        active: 'Continue',
         inactive: 'Cancel',
         initialValue: false,
-        ...clackIO(promptIO)
+        ...io
     });
     if (p.isCancel(accepted))
         return undefined;
@@ -220,11 +303,22 @@ function normalizeCommand(command) {
         return 'update';
     if (command === 'validate')
         return 'validate';
+    if (command === 'self-update')
+        return 'self-update';
     return undefined;
 }
-function canOfferUpdate(diagnostics) {
-    const errors = diagnostics.filter((item) => item.severity === 'error');
-    return errors.length > 0 && errors.every((item) => item.code === 'DESTINATION_EXISTS');
+function shouldCheckForUpdates(options, promptIO) {
+    if (options.noUpdateCheck)
+        return false;
+    const env = promptIO.env ?? process.env;
+    if (env.CI === 'true')
+        return false;
+    if (env.FORGE_NO_UPDATE_CHECK === '1' || env.FORGE_NO_UPDATE_CHECK === 'true')
+        return false;
+    // Skip in non-interactive runs (pipes, CI, scripts): the notice is a UX nudge for terminal users.
+    if (!isInteractivePrompt(promptIO))
+        return false;
+    return true;
 }
 function isInteractivePrompt(promptIO) {
     const env = promptIO.env ?? process.env;
@@ -250,23 +344,39 @@ function readPackageVersion() {
     }
 }
 function showUsage() {
-    console.log('Usage: forge-ai install [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
-    console.log('       forge-ai update [--platform opencode|claude|codex|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
-    console.log('       forge-ai validate [--platform opencode|claude|codex|all] [--source <dir>]');
+    console.log('Usage: forge-ai install [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
+    console.log('       forge-ai update [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
+    console.log('       forge-ai validate [--platform opencode|claude|codex|grok|all] [--source <dir>]');
+    console.log('       forge-ai self-update [--to <version>] [--dry-run] [--skip-spec-update]');
+    console.log('');
+    console.log('Global flags: --no-update-check (also FORGE_NO_UPDATE_CHECK=1 or CI=true)');
 }
-function printPlan(command, sourceCount, files, diagnostics, prunePlan = { deletable: [], skipped: [] }) {
+function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
     console.log(`${command}: ${sourceCount} source(s), ${files.length} output(s)`);
     for (const file of files)
-        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}`);
-    for (const file of prunePlan.deletable)
-        console.log(`- delete stale ${file.platform} ${file.kind} ${file.name} -> ${file.path}`);
-    for (const file of prunePlan.skipped) {
-        if (file.reason === 'checksum-mismatch')
-            console.log(`warning CHECKSUM_MISMATCH: Skipping stale managed file with local changes ${file.path}`);
-    }
+        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}${statusSuffix(file)}`);
+    for (const item of prunePlan.deletable)
+        console.log(`- delete stale ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
+    for (const item of prunePlan.modifiedWithConsent)
+        console.log(`- delete stale ${item.platform} ${item.kind} ${item.name} -> ${item.path} [backup -> ${item.backupPath}]`);
+    for (const item of prunePlan.skippedMissing)
+        console.log(`- skip missing ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
     for (const item of diagnostics)
         console.log(formatDiagnostic(item));
 }
+function statusSuffix(file) {
+    if (file.status === 'managed-modified' && file.backupPath)
+        return ` [overwrite, backup -> ${file.backupPath}]`;
+    if (file.status === 'managed-modified')
+        return ' [overwrite]';
+    if (file.status === 'foreign')
+        return ' [foreign overwrite]';
+    if (file.status === 'managed-unmodified')
+        return ' [refresh]';
+    if (file.status === 'new')
+        return ' [new]';
+    return '';
+}
 if (import.meta.url === `file://${process.argv[1]}`) {
     main().then((code) => { process.exitCode = code; }, (error) => { console.error(error); process.exitCode = 1; });
 }

package/dist/src/discovery.js

@@ -6,35 +6,33 @@ export async function discoverSources(source) {
     const root = path.resolve(source);
     const sources = [];
     const diagnostics = [];
-    await discoverAgents(root, sources, diagnostics);
-    await discoverSkills(root, sources, diagnostics);
+    await discoverArtifacts(root, sources, diagnostics);
     if (sources.length === 0)
-        diagnostics.push(diagnostic('error', 'NO_SOURCES', 'No canonical agents or skills found', { sourcePath: root }));
+        diagnostics.push(diagnostic('error', 'NO_SOURCES', 'No canonical artifacts found', { sourcePath: root }));
     sources.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
     return { sources, diagnostics };
 }
-async function discoverAgents(root, sources, diagnostics) {
-    const dir = path.join(root, 'agents');
-    for (const entry of await safeReaddir(dir)) {
-        if (!entry.isFile() || !entry.name.endsWith('.md'))
-            continue;
-        const sourcePath = path.join(dir, entry.name);
-        await readSource('agent', sourcePath, path.basename(entry.name, '.md'), sources, diagnostics);
-    }
-}
-async function discoverSkills(root, sources, diagnostics) {
-    const dir = path.join(root, 'skills');
+async function discoverArtifacts(root, sources, diagnostics) {
+    const dir = path.join(root, 'artifacts');
     for (const entry of await safeReaddir(dir)) {
         if (!entry.isDirectory())
             continue;
-        const sourcePath = path.join(dir, entry.name, 'SKILL.md');
-        await readSource('skill', sourcePath, entry.name, sources, diagnostics);
+        const name = entry.name;
+        const artifactDir = path.join(dir, name);
+        const mainFile = `${name}.md`;
+        const supportFiles = (await safeReaddir(artifactDir))
+            .filter((file) => file.isFile() && file.name !== mainFile)
+            .map((file) => path.join(artifactDir, file.name));
+        await readSource(path.join(artifactDir, mainFile), name, supportFiles, sources, diagnostics);
     }
 }
-async function readSource(kind, sourcePath, expectedName, sources, diagnostics) {
+async function readSource(sourcePath, expectedName, supportFiles, sources, diagnostics) {
     try {
         const parsed = parseFrontmatter(await readFile(sourcePath, 'utf8'));
-        sources.push({ kind, sourcePath, expectedName, data: parsed.data, body: parsed.body });
+        sources.push({ sourcePath, expectedName, data: parsed.data, body: parsed.body, supportFiles: supportFiles.length > 0 ? supportFiles : undefined });
+        if (supportFiles.length > 0) {
+            diagnostics.push(diagnostic('info', 'SUPPORT_FILES_NOT_COPIED', `Support files alongside ${expectedName} are not copied yet`, { sourcePath }));
+        }
     }
     catch (error) {
         diagnostics.push(diagnostic('error', 'PARSE_ERROR', error instanceof Error ? error.message : String(error), { sourcePath }));

package/dist/src/frontmatter.js

@@ -1,5 +1,6 @@
+import { parse, stringify } from 'yaml';
 export function parseFrontmatter(content) {
-    const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+    const normalized = content.replace(/^/, '').replace(/\r\n/g, '\n');
     if (!normalized.startsWith('---\n')) {
         return { data: {}, body: normalized.trim() };
     }
@@ -8,74 +9,13 @@ export function parseFrontmatter(content) {
         throw new Error('Missing closing frontmatter delimiter');
     const rawYaml = normalized.slice(4, end);
     const body = normalized.slice(normalized.indexOf('\n', end + 1) + 1).trim();
-    return { data: parseSimpleYaml(rawYaml), body };
-}
-export function parseSimpleYaml(input) {
-    const root = {};
-    const stack = [{ indent: -1, object: root }];
-    const lines = input.split('\n');
-    for (let index = 0; index < lines.length; index += 1) {
-        const raw = lines[index];
-        if (!raw.trim() || raw.trimStart().startsWith('#'))
-            continue;
-        const indent = raw.match(/^ */)?.[0].length ?? 0;
-        const trimmed = raw.trim();
-        const match = trimmed.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
-        if (!match)
-            throw new Error(`Invalid YAML at line ${index + 1}`);
-        while (stack.length > 1 && indent <= stack[stack.length - 1].indent)
-            stack.pop();
-        const parent = stack[stack.length - 1].object;
-        const key = match[1];
-        const value = match[2] ?? '';
-        if (value === '') {
-            const child = {};
-            parent[key] = child;
-            stack.push({ indent, object: child });
-        }
-        else {
-            parent[key] = parseScalar(value);
-        }
-    }
-    return root;
-}
-function parseScalar(value) {
-    const trimmed = value.trim();
-    if (trimmed === 'true')
-        return true;
-    if (trimmed === 'false')
-        return false;
-    if (trimmed === 'null')
-        return null;
-    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
-        const inner = trimmed.slice(1, -1).trim();
-        if (!inner)
-            return [];
-        return inner.split(',').map((item) => String(parseScalar(item.trim())));
-    }
-    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        return trimmed.slice(1, -1);
+    const parsed = rawYaml.trim() === '' ? {} : parse(rawYaml);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Frontmatter must be a YAML mapping');
     }
-    return trimmed;
+    return { data: parsed, body };
 }
 export function stringifyYaml(data) {
-    const lines = Object.entries(data).flatMap(([key, value]) => stringifyYamlValue(key, value, 0));
-    return `---\n${lines.join('\n')}\n---\n\n`;
-}
-function stringifyYamlValue(key, value, indent) {
-    const prefix = ' '.repeat(indent);
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-        return [`${prefix}${key}:`, ...Object.entries(value).flatMap(([childKey, childValue]) => stringifyYamlValue(childKey, childValue, indent + 2))];
-    }
-    if (Array.isArray(value))
-        return [`${prefix}${key}: [${value.map(formatScalar).join(', ')}]`];
-    return [`${prefix}${key}: ${formatScalar(value)}`];
-}
-function formatScalar(value) {
-    if (typeof value === 'boolean')
-        return value ? 'true' : 'false';
-    if (typeof value === 'number')
-        return String(value);
-    const text = String(value ?? '');
-    return /^[A-Za-z0-9_./,@* -]+$/.test(text) && text !== '' ? text : JSON.stringify(text);
+    const yaml = stringify(data, { lineWidth: 0, defaultKeyType: 'PLAIN' });
+    return `---\n${yaml}---\n\n`;
 }