@guidobuilds/forge-ai 0.1.0 → 0.3.0

package/dist/src/cli.js

@@ -2,11 +2,15 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { readFileSync } from 'node:fs';
+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, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
 import { buildWritePlan, parsePlatform, parseScope } from './processor.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();
@@ -44,20 +48,49 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             return 1;
         }
     }
-    let plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: install && !options.dryRun, force: options.force });
-    if (install && !options.dryRun && !options.force && canOfferUpdate(plan.diagnostics)) {
-        const accepted = await promptForUpdate(plan, promptIO);
+    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) {
-            if (interactive)
-                p.cancel('Cancelled', clackIO(promptIO));
+            p.cancel('Cancelled', clackIO(promptIO));
             return 1;
         }
-        if (accepted) {
-            options.force = true;
-            plan = await buildWritePlan({ source: options.source, platform: options.platform, scope: options.scope, checkCollisions: true, force: true });
+        if (!accepted) {
+            p.outro(pc.yellow('Forge was not installed.'), clackIO(promptIO));
+            return 1;
         }
     }
-    printPlan(command, plan.sourceCount, plan.files, plan.diagnostics);
+    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));
@@ -69,6 +102,9 @@ export async function main(argv = process.argv.slice(2), 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) {
@@ -78,7 +114,14 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         }
         else {
             await writeOutputs(plan.files);
+            if (command === 'update' && options.prune)
+                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 if (install && interactive) {
@@ -90,13 +133,15 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
     return 0;
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, 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, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
             options.dryRun = true;
         else if (arg === '--force')
             options.force = true;
+        else if (arg === '--no-prune')
+            options.prune = false;
         else if (arg === '--yes' || arg === '-y')
             options.yes = true;
         else if (arg === '--platform') {
@@ -127,10 +172,26 @@ function parseArgs(argv) {
         }
     }
     const command = normalizeCommand(options.command);
+    if (command !== 'update' && !options.prune)
+        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' };
     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;
@@ -171,18 +232,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;
@@ -197,10 +267,6 @@ function normalizeCommand(command) {
         return 'validate';
     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 isInteractivePrompt(promptIO) {
     const env = promptIO.env ?? process.env;
     const interactive = promptIO.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -209,6 +275,9 @@ function isInteractivePrompt(promptIO) {
 function clackIO(promptIO) {
     return { input: promptIO.input, output: promptIO.output };
 }
+function resolveHome(promptIO) {
+    return promptIO.env?.HOME || os.homedir();
+}
 function bundledSourceRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 }
@@ -223,16 +292,35 @@ 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] [--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>]');
 }
-function printPlan(command, sourceCount, files, diagnostics) {
+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}`);
+        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`;
 }

package/dist/src/manifest.js

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function resolveManifestLocation(scope, cwd = process.cwd(), home) {
+    const stateRoot = path.join(home, '.forge-ai');
+    if (scope === 'user')
+        return { stateRoot, manifestPath: path.join(stateRoot, 'user-manifest.json'), scope };
+    const projectPath = await canonicalProjectPath(cwd);
+    const projectPathHash = hashProjectPath(projectPath);
+    return { stateRoot, manifestPath: path.join(stateRoot, 'projects', projectPathHash, 'manifest.json'), scope, projectPath, projectPathHash };
+}
+export async function loadManifest(manifestPath) {
+    try {
+        return JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function buildManifest(location, files, now = new Date()) {
+    const entries = await Promise.all(files.map(async (file) => ({
+        platform: file.platform,
+        kind: file.kind,
+        name: file.name,
+        path: file.path,
+        sourcePath: file.sourcePath,
+        checksum: sha256(await readFile(file.path, 'utf8'))
+    })));
+    return {
+        schemaVersion: 1,
+        scope: location.scope,
+        projectPath: location.projectPath,
+        projectPathHash: location.projectPathHash,
+        updatedAt: now.toISOString(),
+        entries
+    };
+}
+export async function saveManifest(manifestPath, manifest) {
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+export function lookupEntryByPath(manifest, filePath) {
+    return manifest?.entries.find((entry) => entry.path === filePath);
+}
+export function staleEntries(oldManifest, files) {
+    if (!oldManifest)
+        return [];
+    const currentPaths = new Set(files.map((file) => file.path));
+    return oldManifest.entries.filter((entry) => !currentPaths.has(entry.path));
+}
+export async function classifyPruneEntries(entries) {
+    const deletable = [];
+    const skipped = [];
+    for (const entry of entries) {
+        let content;
+        try {
+            content = await readFile(entry.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                skipped.push({ ...entry, reason: 'missing' });
+            else
+                throw error;
+            continue;
+        }
+        if (sha256(content) === entry.checksum)
+            deletable.push(entry);
+        else
+            skipped.push({ ...entry, reason: 'checksum-mismatch' });
+    }
+    return { deletable, skipped };
+}
+export async function pruneEntries(entries) {
+    for (const entry of entries) {
+        if (entry.backupPath) {
+            try {
+                const content = await readFile(entry.path, 'utf8');
+                await backupFile(entry.backupPath, content);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                // Source file is already gone; nothing to back up.
+            }
+        }
+        await rm(entry.path, { force: true });
+        if (entry.kind === 'skill')
+            await removeEmptyParent(path.dirname(entry.path));
+    }
+}
+export function resolveBackupRoot(location, now) {
+    const scopeKey = location.scope === 'user' ? 'user' : path.join('projects', location.projectPathHash ?? 'unknown');
+    return path.join(location.stateRoot, 'backups', scopeKey, isoTimestamp(now));
+}
+export function resolveBackupPath(backupRoot, originalAbsolutePath, anchor) {
+    const rel = path.relative(anchor, originalAbsolutePath);
+    const safe = rel.startsWith('..') || path.isAbsolute(rel)
+        ? originalAbsolutePath.replace(/^[\/\\]+/, '')
+        : rel;
+    return path.join(backupRoot, safe);
+}
+export async function backupFile(backupPath, content) {
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    await writeFile(backupPath, content, 'utf8');
+}
+export function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function hashProjectPath(projectPath) {
+    return sha256(projectPath).slice(0, 32);
+}
+function isoTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
+async function canonicalProjectPath(cwd) {
+    try {
+        return await realpath(cwd);
+    }
+    catch {
+        return path.resolve(cwd);
+    }
+}
+async function removeEmptyParent(directory) {
+    try {
+        await access(directory, constants.F_OK);
+        await rm(directory);
+    }
+    catch {
+        // Directory does not exist or is not empty; both are safe to ignore.
+    }
+}

package/dist/src/model.js

@@ -2,3 +2,6 @@ export const platforms = ['opencode', 'claude', 'codex'];
 export function isPlatform(value) {
     return platforms.includes(value);
 }
+export function hasPendingDecisions(pending) {
+    return pending.modifiedOverwrites.length > 0 || pending.foreignOverwrites.length > 0;
+}