@guidobuilds/forge-ai 0.6.0 → 0.8.0

package/dist/src/processor.js

@@ -1,14 +1,18 @@
 import { access, readFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { homedir } from 'node:os';
 import path from 'node:path';
 import { renderClaudeAgent, renderClaudeSkill } from './adapters/claude.js';
 import { renderCodexAgent, renderCodexSkill } from './adapters/codex.js';
 import { renderGrokAgent, renderGrokSkill } from './adapters/grok.js';
 import { renderOpenCodeAgent, renderOpenCodeSkill } from './adapters/opencode.js';
+import { composeBody } from './compose.js';
 import { diagnostic } from './diagnostics.js';
 import { discoverSources } from './discovery.js';
 import { lookupEntryByPath, resolveBackupPath, sha256 } from './manifest.js';
-import { resolveOutputPath } from './paths.js';
+import { getModelPreference } from './model-preferences.js';
+import { openCodeUserRoots, resolveOpenCodeUserV2Path, resolveOutputPath } from './paths.js';
+import { supportsModel } from './platform-capabilities.js';
 import { isPlatform, platforms } from './model.js';
 const namePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const platformKeys = new Set(['claude', 'opencode', 'codex', 'grok']);
@@ -29,29 +33,39 @@ export function parsePlatform(value) {
 export function parseScope(value) {
     return value === 'user' || value === 'project' ? value : undefined;
 }
-export async function buildWritePlan(options) {
-    const { sources, diagnostics } = await discoverSources(options.source);
+export async function discoverArtifacts(source) {
+    const { sources, diagnostics } = await discoverSources(source);
     const artifacts = [];
     const seen = new Set();
-    for (const source of sources) {
-        const converted = convertSource(source, options.source);
+    for (const item of sources) {
+        const converted = convertSource(item, source);
         diagnostics.push(...converted.diagnostics);
         if (!converted.item)
             continue;
         if (seen.has(converted.item.name)) {
-            diagnostics.push(diagnostic('error', 'DUPLICATE_NAME', `Duplicate artifact name ${converted.item.name}`, { sourcePath: source.sourcePath }));
+            diagnostics.push(diagnostic('error', 'DUPLICATE_NAME', `Duplicate artifact name ${converted.item.name}`, { sourcePath: item.sourcePath }));
             continue;
         }
         seen.add(converted.item.name);
         artifacts.push(converted.item);
     }
+    return { artifacts, diagnostics, sourceCount: sources.length };
+}
+export async function buildWritePlan(options) {
+    const { artifacts, diagnostics, sourceCount } = await discoverArtifacts(options.source);
     const files = [];
     const pending = { modifiedOverwrites: [], foreignOverwrites: [] };
     if (!diagnostics.some((item) => item.severity === 'error')) {
         for (const platform of resolvePlatforms(options.platform)) {
             for (const artifact of artifacts) {
                 const effectiveKind = artifact[platform]?.kind ?? artifact.kind;
-                files.push(renderFile(platform, effectiveKind, artifact, options, diagnostics));
+                const rendered = renderFile(platform, effectiveKind, artifact, options, diagnostics);
+                if (platform === 'opencode' && options.scope === 'user') {
+                    files.push(...await expandOpenCodeUserTargets(rendered, options.home ?? homedir(), diagnostics));
+                }
+                else {
+                    files.push(rendered);
+                }
             }
         }
         files.sort((a, b) => `${a.platform}:${a.kind}:${a.name}`.localeCompare(`${b.platform}:${b.kind}:${b.name}`));
@@ -60,7 +74,7 @@ export async function buildWritePlan(options) {
             diagnostics.push(...await classifyDestinations(files, options.manifest, options.backupRoot, anchor, pending));
         }
     }
-    return { files, diagnostics, pending, sourceCount: sources.length };
+    return { files, diagnostics, pending, sourceCount };
 }
 function convertSource(source, sourceRoot) {
     const diagnostics = [];
@@ -122,10 +136,6 @@ function convertSource(source, sourceRoot) {
         diagnostics.push(diagnostic('error', 'INVALID_KIND', 'artifact kind must be one of agent, skill', { sourcePath: source.sourcePath }));
     if (!source.body.trim())
         diagnostics.push(diagnostic('error', 'EMPTY_BODY', 'artifact body is required', { sourcePath: source.sourcePath }));
-    const bodyLines = source.body.split('\n').length;
-    const bodyBudget = bodyLineBudgets[name ?? source.expectedName] ?? defaultBodyBudget;
-    if (bodyLines > bodyBudget)
-        diagnostics.push(diagnostic('info', 'BODY_OVER_BUDGET', `artifact body is ${bodyLines} lines (soft budget ${bodyBudget}); keep always-loaded harness files small`, { sourcePath: source.sourcePath }));
     if (!name || !description || !artifactKinds.has(kind) || !source.body.trim() || diagnostics.some((item) => item.severity === 'error'))
         return { diagnostics };
     return {
@@ -149,21 +159,64 @@ function productConfig(value) {
         : undefined;
 }
 function renderFile(platform, kind, artifact, options, diagnostics) {
+    const composedBody = composeBody(artifact.body, platform);
+    const bodyLines = composedBody.split('\n').length;
+    const bodyBudget = bodyLineBudgets[artifact.name] ?? defaultBodyBudget;
+    if (bodyLines > bodyBudget)
+        diagnostics.push(diagnostic('info', 'BODY_OVER_BUDGET', `${platform} ${artifact.name} body is ${bodyLines} lines (soft budget ${bodyBudget}); keep always-loaded harness files small`, { sourcePath: artifact.sourcePath, platform }));
+    let composed = { ...artifact, body: composedBody };
+    const modelOverride = options.modelPreferences && supportsModel(platform, kind) ? getModelPreference(options.modelPreferences, platform, artifact.name) : undefined;
+    if (modelOverride)
+        composed = { ...composed, [platform]: { ...composed[platform], model: modelOverride } };
     const rendered = kind === 'agent'
-        ? platform === 'opencode' ? renderOpenCodeAgent(artifact) : platform === 'claude' ? renderClaudeAgent(artifact) : platform === 'grok' ? renderGrokAgent(artifact) : renderCodexAgent(artifact)
-        : platform === 'opencode' ? renderOpenCodeSkill(artifact) : platform === 'claude' ? renderClaudeSkill(artifact) : platform === 'grok' ? renderGrokSkill(artifact) : renderCodexSkill(artifact);
+        ? platform === 'opencode' ? renderOpenCodeAgent(composed) : platform === 'claude' ? renderClaudeAgent(composed) : platform === 'grok' ? renderGrokAgent(composed) : renderCodexAgent(composed)
+        : platform === 'opencode' ? renderOpenCodeSkill(composed) : platform === 'claude' ? renderClaudeSkill(composed) : platform === 'grok' ? renderGrokSkill(composed) : renderCodexSkill(composed);
     diagnostics.push(...rendered.diagnostics);
     return { platform, kind, scope: options.scope, name: artifact.name, sourcePath: artifact.sourcePath, path: resolveOutputPath(platform, kind, options.scope, artifact.name, options.cwd, options.home), content: rendered.content };
 }
+// `renderFile` above always computes OpenCode's v1 path (`~/.config/opencode/...`) for user scope
+// — that stays the default target. v1 and the v2 preview (`opencode2`) read user-scope
+// agents/skills from different directories (see src/paths.ts), and a machine can have either,
+// both, or — before OpenCode has ever run — neither. Writing v2's directory unconditionally would
+// silently create config for a generation that isn't actually installed; skipping v1 whenever v2
+// is present would regress the long-supported default. So: write to each generation's directory
+// only if it already exists on disk, and if neither does, keep today's behavior (write v1) rather
+// than silently installing nothing.
+async function expandOpenCodeUserTargets(base, home, diagnostics) {
+    const roots = openCodeUserRoots(home);
+    const [v1Exists, v2Exists] = await Promise.all([pathExists(roots.v1), pathExists(roots.v2)]);
+    if (!v1Exists && !v2Exists) {
+        diagnostics.push(diagnostic('info', 'OPENCODE_USER_ROOT_NOT_FOUND', `Neither ${roots.v1} (v1) nor ${roots.v2} (v2) exists yet; installing to the v1 default. Run OpenCode at least once, then re-run \`forge-ai install\`/\`update\`, to also cover whichever generation you actually use.`, { platform: 'opencode', sourcePath: base.sourcePath }));
+        return [base];
+    }
+    const files = [];
+    if (v1Exists)
+        files.push(base);
+    if (v2Exists)
+        files.push({ ...base, path: resolveOpenCodeUserV2Path(base.kind, base.name, home) });
+    return files;
+}
+async function pathExists(target) {
+    try {
+        await access(target, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function classifyDestinations(files, manifest, backupRoot, anchor, pending) {
     const diagnostics = [];
     for (const file of files) {
-        const status = await classifyFile(file.path, manifest);
+        const { status, checksum } = await classifyFile(file.path, manifest);
         file.status = status;
-        if (status === 'managed-modified' && backupRoot) {
-            file.backupPath = resolveBackupPath(backupRoot, file.path, anchor);
-            pending.modifiedOverwrites.push(file);
-            diagnostics.push(diagnostic('warning', 'MANAGED_FILE_OVERWRITE', `Will overwrite locally edited Forge file ${file.path}; backup → ${file.backupPath}`, { platform: file.platform }));
+        if (status === 'managed-modified') {
+            file.expectedChecksum = checksum;
+            if (backupRoot) {
+                file.backupPath = resolveBackupPath(backupRoot, file.path, anchor);
+                pending.modifiedOverwrites.push(file);
+                diagnostics.push(diagnostic('warning', 'MANAGED_FILE_OVERWRITE', `Will overwrite locally edited Forge file ${file.path}; backup → ${file.backupPath}`, { platform: file.platform }));
+            }
         }
         else if (status === 'foreign') {
             pending.foreignOverwrites.push(file);
@@ -177,11 +230,12 @@ async function classifyFile(filePath, manifest) {
         await access(filePath, constants.F_OK);
     }
     catch {
-        return 'new';
+        return { status: 'new' };
     }
     const entry = lookupEntryByPath(manifest, filePath);
     if (!entry)
-        return 'foreign';
+        return { status: 'foreign' };
     const content = await readFile(filePath, 'utf8');
-    return sha256(content) === entry.checksum ? 'managed-unmodified' : 'managed-modified';
+    const checksum = sha256(content);
+    return checksum === entry.checksum ? { status: 'managed-unmodified' } : { status: 'managed-modified', checksum };
 }

package/dist/src/self-update.js

@@ -1,6 +1,31 @@
 import { realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { resolveExecutable } from './executable-resolution.js';
 const PACKAGE = '@guidobuilds/forge-ai';
+const TRUSTED_COMMANDS = new Set(['pnpm', 'npm', 'forge-ai']);
+// --to allowlist: the literal 'latest' or a semver X.Y.Z (optional -prerelease / +build), optionally
+// 'v'-prefixed. Rejects ranges (^1.0.0, ~1.0.0), git URLs, and any other dist-tag, so no arbitrary
+// spec ever reaches `npm/pnpm install -g`.
+export function isValidVersionSpec(value) {
+    return value === 'latest' || /^v?\d+\.\d+\.\d+([-+].*)?$/.test(value);
+}
+// 'v0.4.0' -> '0.4.0'; leaves 'latest' and bare semvers untouched.
+export function normalizeVersionSpec(value) {
+    return value.replace(/^v(?=\d)/, '');
+}
+function resolveAndValidate(command, resolver, log) {
+    const resolved = resolver(command);
+    if (!resolved) {
+        log(`Could not resolve a trusted ${command} binary; refusing to run.`);
+        return { ok: false };
+    }
+    if (!TRUSTED_COMMANDS.has(path.basename(resolved))) {
+        log(`Refusing to run ${resolved}: unexpected binary name (expected ${[...TRUSTED_COMMANDS].join(', ')}).`);
+        return { ok: false };
+    }
+    return { ok: true, resolved };
+}
 export function detectInstallMethod(realPath) {
     if (/[/\\]\.npm[/\\]_npx[/\\]/.test(realPath))
         return 'npx';
@@ -31,6 +56,7 @@ export async function runSelfUpdate(options) {
     const log = options.log ?? ((message) => console.log(message));
     const resolver = options.realPathResolver ?? ((p) => realpathSync(p));
     const spawner = options.spawner ?? defaultSpawner;
+    const resolveCommand = options.resolveCommand ?? ((command) => resolveExecutable(command, { cwd: process.cwd() }));
     let realPath;
     try {
         realPath = resolver(options.binaryPath);
@@ -42,7 +68,12 @@ export async function runSelfUpdate(options) {
     // fall back to the resolved real path (catches standard global installs whose bin dir is generic).
     const symlinkMethod = detectInstallMethod(options.binaryPath);
     const method = symlinkMethod !== 'unknown' ? symlinkMethod : detectInstallMethod(realPath);
-    const cmd = buildUpdateCommand(method, options.version ?? 'latest');
+    const version = normalizeVersionSpec(options.version ?? 'latest');
+    if (!isValidVersionSpec(version)) {
+        log(`Invalid --to ${options.version}; expected a semver or "latest".`);
+        return 1;
+    }
+    const cmd = buildUpdateCommand(method, version);
     log(`Detected install: ${cmd.description} at ${realPath}`);
     if (cmd.instructions) {
         log(cmd.instructions);
@@ -53,7 +84,16 @@ export async function runSelfUpdate(options) {
         log('(dry-run, not executing)');
         return 0;
     }
-    const updateResult = spawner(cmd.command, cmd.args);
+    const spawn = (command, args) => {
+        if (options.resolveCommand) {
+            const checked = resolveAndValidate(command, resolveCommand, log);
+            if (!checked.ok)
+                return { status: 1 };
+            return spawner(checked.resolved, args);
+        }
+        return spawner(command, args);
+    };
+    const updateResult = spawn(cmd.command, cmd.args);
     if (updateResult.status !== 0) {
         log(`CLI update failed with exit code ${updateResult.status}`);
         return updateResult.status ?? 1;
@@ -61,10 +101,16 @@ export async function runSelfUpdate(options) {
     if (options.skipSpecUpdate)
         return 0;
     log('\nApplying spec kit with the updated CLI...');
-    const specResult = spawner('forge-ai', ['update']);
+    const specResult = spawn('forge-ai', ['update']);
     return specResult.status ?? 1;
 }
+// Trust boundary: package managers are developer-facing binaries resolved to an absolute path via
+// resolveExecutable (which rejects candidates inside the current working tree) and checked against
+// the { pnpm, npm, forge-ai } basename allowlist — never a bare name that PATH/cwd could shadow.
 function defaultSpawner(command, args) {
-    const result = spawnSync(command, args, { stdio: 'inherit' });
+    const checked = resolveAndValidate(command, (c) => resolveExecutable(c, { cwd: process.cwd() }), (m) => console.error(m));
+    if (!checked.ok)
+        return { status: 1 };
+    const result = spawnSync(checked.resolved, args, { stdio: 'inherit' });
     return { status: result.status };
 }

package/dist/src/writer.js

@@ -1,19 +1,24 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { backupFile } from './manifest.js';
+import { backupFile, sha256 } from './manifest.js';
 export async function writeOutputs(files) {
     for (const file of files) {
-        if (file.backupPath) {
+        let existing;
+        if (file.expectedChecksum || file.backupPath) {
             try {
-                const existing = await readFile(file.path, 'utf8');
-                await backupFile(file.backupPath, existing);
+                existing = await readFile(file.path, 'utf8');
             }
             catch (error) {
                 if (error.code !== 'ENOENT')
                     throw error;
-                // Original file disappeared between classification and write; no backup needed.
             }
         }
+        if (file.expectedChecksum && existing !== undefined && sha256(existing) !== file.expectedChecksum) {
+            throw new Error(`File ${file.path} changed after classification; aborting to avoid overwriting recent edits.`);
+        }
+        if (file.backupPath && existing !== undefined) {
+            await backupFile(file.backupPath, existing);
+        }
         await mkdir(path.dirname(file.path), { recursive: true });
         await writeFile(file.path, file.content, 'utf8');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guidobuilds/forge-ai",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Forge AI framework",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
     "build": "tsc -p tsconfig.build.json",
     "build:test": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build:test && node --test dist/tests/*.test.js"
+    "test": "npm run build:test && node --test dist/tests/*.test.js",
+    "generate-fixtures": "npm run build && node scripts/generate-fixtures.mjs"
   }
 }