@ikarmic/forge-core 4.5.0 → 5.1.0

package/dist/settings-export.js

@@ -36,4 +36,3 @@ export async function importSettings(data, opts) {
     await saveForgeConfigFile(data.config, opts.configPath);
     await saveSpecialistsToConfig(data.specialists ?? [], opts.specialistsPath);
 }
-//# sourceMappingURL=settings-export.js.map

package/dist/skills/activator.d.ts

@@ -49,4 +49,3 @@ export declare function buildSkillsBlock(skills: Skill[]): string;
  * Returns an empty string when no skills are selected.
  */
 export declare function composeSkillsPrompt(skills: Skill[]): string;
-//# sourceMappingURL=activator.d.ts.map

package/dist/skills/activator.js

@@ -116,4 +116,3 @@ export function composeSkillsPrompt(skills) {
         block,
     ].join('\n');
 }
-//# sourceMappingURL=activator.js.map

package/dist/skills/builtin.d.ts

@@ -0,0 +1,2 @@
+import type { Skill } from './types.js';
+export declare function builtinSkills(): Skill[];

package/dist/skills/builtin.js

@@ -0,0 +1,68 @@
+import { USER_ONLY_CONFIG_KEYS } from '../config-merge.js';
+/** One line per key of `~/.forge/config.json`. Typed against the file's keys: a new key does not compile until it has a line. */
+const KEY_HELP = {
+    provider: 'default provider id',
+    model: 'default model id, alias or provider:model',
+    completionModel: 'model for inline completion',
+    compactionModel: 'model that writes the summary when a long chat is condensed',
+    disabledProviders: 'providers hidden from the model picker',
+    reasoningEffort: 'none, minimal, low, medium, high or xhigh',
+    autoApproveTools: 'tools that run without asking',
+    autoApproveCommands: 'commands you chose "Always allow"; written by Forge, do not hand-edit',
+    permission: 'ordered rules per tool kind (read, edit, bash, webfetch, websearch, task, external_directory), each allow, ask or deny; the last match wins',
+    customProviders: 'providers beyond the built-in ones: id to { name, baseUrl, apiKeyEnv or apiKey, headers, api, timeoutMs, models }',
+    modelOverrides: 'context and output limits and prices per model',
+    modelFilters: 'per provider whitelist and blacklist of model ids',
+    subagentModel: 'model sub-agents use when none is named',
+    instructions: 'extra instruction files, globs and http(s) URLs added to the system prompt',
+    skillPaths: 'extra folders, or http(s) URLs of a skill file or a skill index ({ "skills": [{ "url": "..." }] }), to read skills from',
+    caCertificates: 'PEM files of extra certificate authorities to trust; needs a reload',
+    aliases: 'short names for models',
+    modeModels: 'model per chat mode',
+    sessionRetentionDays: 'delete saved chats older than this many days',
+    display: 'blockDefault (collapsed or expanded), detail (compact or full), showReasoning (true or false), and blocks: per kind of block, reasoning (hidden, collapsed or expanded) and terminal, edit, mcp (collapsed or expanded). The kinds are exactly reasoning, terminal, edit and mcp; use no other name',
+};
+function configBody() {
+    const userOnly = USER_ONLY_CONFIG_KEYS.join(', ');
+    const keys = Object.keys(KEY_HELP).map((k) => `- \`${k}\`: ${KEY_HELP[k]}`).join('\n');
+    return `# Changing Forge's settings
+
+Use this when the user asks to change how Forge behaves: a model, a provider, permissions, MCP servers, agents, commands, skills.
+
+## Where things live
+
+- \`~/.forge/config.json\`: the user's own settings. Applies in every project.
+- \`<workspace>/.forge/config.json\`: the project's settings, read only when the workspace is trusted. It can set provider, model, completionModel, compactionModel, reasoningEffort, subagentModel, modelOverrides, aliases, modeModels and display, and add stricter permission rules (ask, deny). It can never loosen anything.
+- User-only keys (a project file cannot set them, Forge ignores them there with a warning): ${userOnly}.
+- \`~/.forge/mcp.json\` and \`<workspace>/.forge/mcp.json\`: MCP servers, \`{ "mcpServers": { "name": { "command", "args", "env" } or { "url", "headers" } } }\`.
+- \`<workspace>/.forge/agents/*.md\` and \`~/.forge/agents/*.md\`: agents; front matter (description, mode, model, tools, deny, steps, temperature) then the system prompt.
+- \`<workspace>/.forge/commands/*.md\` and \`~/.forge/commands/*.md\`: slash commands; \`$ARGUMENTS\` is replaced by what the user types after the name.
+- \`<workspace>/.forge/skills/\`, \`<workspace>/skills/\`, \`~/.forge/skills/\`: skills.
+- \`AGENTS.md\` (or \`CLAUDE.md\`) in the workspace or a folder: instructions for the model.
+- In VS Code the same choices also exist as \`forge.*\` settings, edited on the Forge Settings page or in settings.json.
+
+## Keys of config.json
+
+${keys}
+
+## How to change them
+
+0. Your file tools only reach the workspace, so you cannot edit \`~/.forge/config.json\`. For a key the project file may set (see above), edit \`<workspace>/.forge/config.json\` and say plainly that the change is workspace-scoped (only for this workspace, and only when it is trusted). For a user-only key, or when the person wants it everywhere, show the exact JSON to add and tell them to paste it into \`~/.forge/config.json\` or use the Forge Settings page; do not write it into the project file.
+1. Read the file first. If it does not exist, create it with only the keys you are setting.
+2. Change only what was asked. Keep every other key and keep the file valid JSON (double quotes, no trailing commas, no comments).
+3. A secret never goes in a project file. Name an environment variable (\`apiKeyEnv\`) instead of pasting a key.
+4. Do not widen permissions (\`autoApproveTools\`, \`permission\` allow rules, \`autoApproveCommands\`) unless the user asked for exactly that, and say what the change allows.
+5. After saving, say what changed and where. Most changes apply on the next message; \`caCertificates\` and the language need a window reload, MCP servers and skills need \`/reload\`.
+6. Do not run Forge commands that write to the real \`~/.forge\` to test a change. Edit the file and let the user check it.
+`;
+}
+export function builtinSkills() {
+    return [
+        {
+            name: 'forge-config',
+            description: "Change Forge's own settings: models, providers, permissions, MCP servers, agents, commands, skills and instructions. Use when the user asks to configure or set up Forge itself.",
+            body: configBody(),
+            source: { kind: 'builtin', path: '(built into Forge)' },
+        },
+    ];
+}

package/dist/skills/index.d.ts

@@ -6,6 +6,8 @@
  * internal directory layout.
  */
 export type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';
@@ -13,4 +15,3 @@ export { fetchSkillsCatalog, installSkillFromCatalog, searchSkills, } from './ma
 export type { CatalogFetcher } from './marketplace.js';
 export type { SkillCatalog, SkillCatalogEntry, SkillSearchResult, } from './marketplace-types.js';
 export { DEFAULT_SKILL_CATALOG_URL, SKILL_CATALOG_VERSION } from './marketplace-types.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -5,10 +5,11 @@
  * callers can use skills + the community catalog without knowing the
  * internal directory layout.
  */
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';
 // Skills marketplace
 export { fetchSkillsCatalog, installSkillFromCatalog, searchSkills, } from './marketplace.js';
 export { DEFAULT_SKILL_CATALOG_URL, SKILL_CATALOG_VERSION } from './marketplace-types.js';
-//# sourceMappingURL=index.js.map

package/dist/skills/loader.d.ts

@@ -6,6 +6,7 @@
  * root wins (local > project > global). The result is an immutable
  * snapshot: call {@link reload} to re-read disk.
  */
+import { type RemoteSkillOptions } from './remote.js';
 import type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export declare const LOCAL_SKILLS_DIR = "skills";
@@ -31,7 +32,9 @@ export declare function parseSkillsDir(dir: string, kind: SkillSource['kind']):
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export declare function discoverSkills(cwd: string): Promise<Skill[]>;
+export declare function discoverSkills(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<Skill[]>;
 /**
  * Build an immutable registry from a pre-loaded skill list. Use this when
  * tests want to inject a known set without touching the filesystem. Use
@@ -42,10 +45,13 @@ export declare function skillsRegistryFromList(skills: Skill[], roots: SkillRoot
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export declare function loadSkillsRegistry(cwd: string): SkillRegistry;
+export declare function loadSkillsRegistry(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): SkillRegistry;
 /**
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export declare function loadSkillsRegistryAsync(cwd: string): Promise<SkillRegistry>;
-//# sourceMappingURL=loader.d.ts.map
+export declare function loadSkillsRegistryAsync(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<SkillRegistry>;

package/dist/skills/loader.js

@@ -11,6 +11,8 @@ import { readdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { discoverPlugins } from '../plugins/loader.js';
+import { builtinSkills } from './builtin.js';
+import { isHttpUrl, loadRemoteSkills } from './remote.js';
 import { parseSkill } from './parser.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export const LOCAL_SKILLS_DIR = 'skills';
@@ -61,19 +63,30 @@ export async function parseSkillsDir(dir, kind) {
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export async function discoverSkills(cwd) {
+export async function discoverSkills(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     const [localSkills, projectSkills, globalSkills] = await Promise.all([
         parseSkillsDir(roots.local, 'local'),
         parseSkillsDir(roots.project, 'project'),
         parseSkillsDir(roots.global, 'global'),
     ]);
+    // Folders named in the `skillPaths` setting rank after the user's own folders and before plugins.
+    // An entry that is an http(s) URL is fetched (one skill file, or an index of them); the rest are folders.
+    const extraSkills = (await Promise.all(extraDirs.map(async (d) => {
+        if (isHttpUrl(d)) {
+            const got = await loadRemoteSkills(d, remote);
+            for (const w of got.warnings)
+                remote.onWarning?.(w);
+            return got.skills;
+        }
+        return parseSkillsDir(path.resolve(cwd, d.startsWith('~') ? path.join(homedir(), d.slice(1)) : d), 'global');
+    }))).flat();
     // Plugin skills rank below the user's own: they never shadow a skill written locally.
     const pluginSkills = (await Promise.all((await discoverPlugins(cwd)).map((p) => (p.skillsDir ? parseSkillsDir(p.skillsDir, p.scope) : Promise.resolve([]))))).flat();
-    // Order matters: first to claim a name wins. local > project > global > plugins.
+    // Order matters: first to claim a name wins. local > project > global > plugins > built in.
     const seen = new Set();
     const merged = [];
-    for (const list of [localSkills, projectSkills, globalSkills, pluginSkills]) {
+    for (const list of [localSkills, projectSkills, globalSkills, extraSkills, pluginSkills, builtinSkills()]) {
         for (const skill of list) {
             if (seen.has(skill.name))
                 continue;
@@ -105,11 +118,11 @@ export function skillsRegistryFromList(skills, roots) {
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export function loadSkillsRegistry(cwd) {
+export function loadSkillsRegistry(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     let cache = null;
     const refresh = async () => {
-        cache = await discoverSkills(cwd);
+        cache = await discoverSkills(cwd, extraDirs, remote);
         return cache;
     };
     return {
@@ -123,9 +136,8 @@ export function loadSkillsRegistry(cwd) {
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export async function loadSkillsRegistryAsync(cwd) {
-    const registry = loadSkillsRegistry(cwd);
+export async function loadSkillsRegistryAsync(cwd, extraDirs = [], remote = {}) {
+    const registry = loadSkillsRegistry(cwd, extraDirs, remote);
     await registry.reload();
     return registry;
 }
-//# sourceMappingURL=loader.js.map

package/dist/skills/marketplace-types.d.ts

@@ -52,4 +52,3 @@ export interface SkillSearchResult {
     /** Total entries scanned (before filtering). */
     totalScanned: number;
 }
-//# sourceMappingURL=marketplace-types.d.ts.map

package/dist/skills/marketplace-types.js

@@ -13,4 +13,3 @@
 export const SKILL_CATALOG_VERSION = 1;
 /** Default catalog URL: fetched via {@link fetchSkillsCatalog} when none is supplied. */
 export const DEFAULT_SKILL_CATALOG_URL = 'https://raw.githubusercontent.com/ikarmicai/forge-skills/main/skills-catalog.json';
-//# sourceMappingURL=marketplace-types.js.map

package/dist/skills/marketplace.d.ts

@@ -60,4 +60,3 @@ export declare function installSkillFromCatalog(params: {
     path: string;
     skill: Skill;
 } | null>;
-//# sourceMappingURL=marketplace.d.ts.map

package/dist/skills/marketplace.js

@@ -11,6 +11,7 @@
 import { normalizeGithubSource } from '../mcp/marketplace.js';
 import { parseSkill } from './parser.js';
 import { DEFAULT_SKILL_CATALOG_URL, SKILL_CATALOG_VERSION, } from './marketplace-types.js';
+import { isOutsideRel } from '../tools/shared.js';
 /**
  * Sanitize a catalog-provided name to a safe filename charset before it is
  * used to build a path on disk. Mirrors `installDirNameFor`'s sanitization
@@ -168,7 +169,7 @@ export async function installSkillFromCatalog(params) {
     const filePath = path.join(dest, `${safeName}.md`);
     const resolvedDest = path.resolve(dest);
     const rel = path.relative(resolvedDest, path.resolve(filePath));
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    if (isOutsideRel(rel)) {
         return null;
     }
     await fs.writeFile(filePath, rawContent, 'utf8');
@@ -182,4 +183,3 @@ function defaultDestination() {
     const path = require('node:path');
     return path.join(homedir(), '.forge', 'skills');
 }
-//# sourceMappingURL=marketplace.js.map

package/dist/skills/parser.d.ts

@@ -28,4 +28,3 @@ export declare function parseFrontmatter(text: string): {
  * originating file path.
  */
 export declare function parseSkill(content: string, source: SkillSource, fallbackName?: string): Skill;
-//# sourceMappingURL=parser.d.ts.map

package/dist/skills/parser.js

@@ -96,4 +96,3 @@ export function parseSkill(content, source, fallbackName) {
         source,
     };
 }
-//# sourceMappingURL=parser.js.map

package/dist/skills/remote.d.ts

@@ -0,0 +1,14 @@
+import type { Skill } from './types.js';
+export interface RemoteSkillOptions {
+    fetch?: typeof fetch;
+    /** Defaults to `~/.forge/skill-cache`. */
+    cacheDir?: string;
+    ttlMs?: number;
+    now?: () => number;
+}
+export interface RemoteSkills {
+    skills: Skill[];
+    warnings: string[];
+}
+export declare const isHttpUrl: (s: string) => boolean;
+export declare function loadRemoteSkills(url: string, options?: RemoteSkillOptions): Promise<RemoteSkills>;

package/dist/skills/remote.js

@@ -0,0 +1,131 @@
+/**
+ * Skills from a URL: either one skill file (Markdown with front matter) or an index,
+ * `{ "skills": [{ "url": "a.md" }, ...] }`, whose links may be relative to the index.
+ * Responses are cached on disk so a skill still works offline and a slow host is not asked on every run:
+ * a copy younger than the TTL is used as is; an older one is refreshed, and kept if the refresh fails.
+ * Anything that times out or is not a skill is skipped with one warning. Only http and https are fetched.
+ * The `skillPaths` setting that lists URLs is read from the user's config only.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { parseSkill } from './parser.js';
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_CHARS = 200_000;
+const MAX_INDEX_ENTRIES = 20;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/** A host that failed is not asked again for this long, so a dead URL does not add its timeout to every message. */
+const RETRY_AFTER_FAILURE_MS = 5 * 60 * 1000;
+const failures = new Map();
+export const isHttpUrl = (s) => /^https?:\/\//i.test(s);
+function cacheFile(dir, url) {
+    return path.join(dir, `${createHash('sha256').update(url).digest('hex').slice(0, 32)}.json`);
+}
+async function readCache(dir, url) {
+    try {
+        const entry = JSON.parse(await readFile(cacheFile(dir, url), 'utf8'));
+        return typeof entry.text === 'string' && typeof entry.fetchedAt === 'number' ? entry : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text at `url`: a fresh cached copy, else the network, else a stale cached copy; throws if there is none. */
+async function fetchText(url, opts) {
+    const cached = await readCache(opts.cacheDir, url);
+    if (cached && opts.now() - cached.fetchedAt < opts.ttlMs)
+        return cached.text;
+    const failKey = `${opts.cacheDir}|${url}`;
+    const failed = failures.get(failKey);
+    const since = failed ? opts.now() - failed.at : 0;
+    if (failed && since >= 0 && since < RETRY_AFTER_FAILURE_MS) {
+        if (cached)
+            return cached.text;
+        throw new Error(failed.message);
+    }
+    try {
+        const res = await opts.fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const text = (await res.text()).slice(0, MAX_CHARS);
+        try {
+            await mkdir(opts.cacheDir, { recursive: true });
+            await writeFile(cacheFile(opts.cacheDir, url), JSON.stringify({ url, fetchedAt: opts.now(), text }), 'utf8');
+        }
+        catch {
+            // a cache that cannot be written only costs a fetch next time
+        }
+        failures.delete(failKey);
+        return text;
+    }
+    catch (err) {
+        failures.set(failKey, { at: opts.now(), message: err.message });
+        if (cached)
+            return cached.text;
+        throw err;
+    }
+}
+function fallbackName(url) {
+    const last = new URL(url).pathname.split('/').filter(Boolean).pop() ?? 'remote-skill';
+    return last.replace(/\.md$/i, '') || 'remote-skill';
+}
+function asSkill(url, text) {
+    const head = text.trimStart();
+    if (head.startsWith('<') || !head.startsWith('---'))
+        return undefined;
+    const skill = parseSkill(text, { kind: 'remote', path: url }, fallbackName(url));
+    return skill.description.trim() && skill.body ? skill : undefined;
+}
+export async function loadRemoteSkills(url, options = {}) {
+    const warnings = [];
+    if (!isHttpUrl(url))
+        return { skills: [], warnings: [`${url}: only http and https skill URLs are read; skipped`] };
+    const opts = {
+        fetch: options.fetch ?? fetch,
+        cacheDir: options.cacheDir ?? path.join(homedir(), '.forge', 'skill-cache'),
+        ttlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+        now: options.now ?? Date.now,
+    };
+    const loadOne = async (target) => {
+        try {
+            const skill = asSkill(target, await fetchText(target, opts));
+            if (!skill)
+                warnings.push(`${target}: not a skill (needs front matter with a description); skipped`);
+            return skill;
+        }
+        catch (err) {
+            warnings.push(`${target}: ${err.message}; skipped`);
+            return undefined;
+        }
+    };
+    let text;
+    try {
+        text = await fetchText(url, opts);
+    }
+    catch (err) {
+        return { skills: [], warnings: [`${url}: ${err.message}; skipped`] };
+    }
+    const trimmed = text.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        let index;
+        try {
+            index = JSON.parse(text);
+        }
+        catch {
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        }
+        const list = Array.isArray(index) ? index : index?.skills;
+        if (!Array.isArray(list))
+            return { skills: [], warnings: [`${url}: not a skill or a skill index; skipped`] };
+        const targets = list
+            .map((e) => (typeof e === 'string' ? e : e?.url))
+            .filter((u) => typeof u === 'string' && u.length > 0)
+            .slice(0, MAX_INDEX_ENTRIES)
+            .map((u) => new URL(u, url).href);
+        const skills = (await Promise.all(targets.map(loadOne))).filter((s) => s !== undefined);
+        return { skills, warnings };
+    }
+    const skill = asSkill(url, text);
+    return skill ? { skills: [skill], warnings } : { skills: [], warnings: [`${url}: not a skill (needs front matter with a description); skipped`] };
+}

package/dist/skills/types.d.ts

@@ -38,6 +38,16 @@ export type SkillSource = {
 } | {
     kind: 'global';
     path: string;
+}
+/** Ships inside Forge; there is no file, `path` is a label. */
+ | {
+    kind: 'builtin';
+    path: string;
+}
+/** Fetched from a URL listed in `skillPaths`; `path` is the URL. */
+ | {
+    kind: 'remote';
+    path: string;
 };
 /** A parsed skill, ready for activation. */
 export interface Skill {
@@ -71,4 +81,3 @@ export interface SkillRegistry {
     /** Where skills were discovered (for diagnostics). */
     roots(): SkillRoots;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/skills/types.js

@@ -29,4 +29,3 @@
  * can override a global skill by name).
  */
 export {};
-//# sourceMappingURL=types.js.map

package/dist/specs/generate.d.ts

@@ -24,4 +24,3 @@ export declare const SPEC_READONLY_TOOLS: readonly string[];
  * or malformed files.
  */
 export declare function splitSpecSections(raw: string): SpecSections;
-//# sourceMappingURL=generate.d.ts.map

package/dist/specs/generate.js

@@ -86,4 +86,3 @@ function splitInlineSubtasks(tasks) {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-//# sourceMappingURL=generate.js.map

package/dist/specs/index.d.ts

@@ -12,4 +12,3 @@ export { convertToCheckboxes, parseTasks, setTaskDone } from './tasks-parser.js'
 export type { SpecTask } from './tasks-parser.js';
 export { changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './sync.js';
 export type { SpecDrift } from './sync.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/specs/index.js

@@ -9,4 +9,3 @@ export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId } from './store.j
 export { SPEC_READONLY_TOOLS, splitSpecSections } from './generate.js';
 export { convertToCheckboxes, parseTasks, setTaskDone } from './tasks-parser.js';
 export { changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './sync.js';
-//# sourceMappingURL=index.js.map

package/dist/specs/store.d.ts

@@ -51,4 +51,3 @@ export declare class SpecStore {
  * all (e.g. `"!!!"`).
  */
 export declare function slugifyTaskForSpecId(task: string): string;
-//# sourceMappingURL=store.d.ts.map

package/dist/specs/store.js

@@ -255,4 +255,3 @@ export function slugifyTaskForSpecId(task) {
     const suffix = Math.random().toString(36).slice(2, 8);
     return `${slug}-${suffix}`;
 }
-//# sourceMappingURL=store.js.map

package/dist/specs/sync.d.ts

@@ -27,4 +27,3 @@ export declare function changeSize(before: string, after: string): {
     added: number;
     removed: number;
 };
-//# sourceMappingURL=sync.d.ts.map

package/dist/specs/sync.js

@@ -153,4 +153,3 @@ export function changeSize(before, after) {
         removed += Math.max(0, n - (b.get(line) ?? 0));
     return { added, removed };
 }
-//# sourceMappingURL=sync.js.map

package/dist/specs/tasks-parser.d.ts

@@ -25,4 +25,3 @@ export declare function setTaskDone(md: string, task: {
     reason: string;
 };
 export declare function convertToCheckboxes(md: string): string;
-//# sourceMappingURL=tasks-parser.d.ts.map

package/dist/specs/tasks-parser.js

@@ -75,4 +75,3 @@ export function convertToCheckboxes(md) {
     });
     return changed ? out.join(eolOf(md)) : md;
 }
-//# sourceMappingURL=tasks-parser.js.map

package/dist/specs/types.d.ts

@@ -41,4 +41,3 @@ export interface SpecSummary {
     /** Absolute path to `.forge/specs/<id>/`. */
     dir: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/specs/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/steering/extra-instructions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export declare function buildExtraInstructionsBlock(cwd: string, entries: readonly string[], deps?: {
+    fetch?: typeof fetch;
+}): Promise<string>;

package/dist/steering/extra-instructions.js

@@ -0,0 +1,104 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { pathMatchesGlob } from './glob.js';
+const PER_SOURCE_BYTES = 12_000;
+const TOTAL_BYTES = 48_000;
+const MAX_WALK_FILES = 5_000;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'out', 'build', '.next', 'target']);
+const URL_TIMEOUT_MS = 10_000;
+const isGlob = (s) => /[*?[]/.test(s);
+const isUrl = (s) => /^[a-z][a-z0-9+.-]*:\/\//i.test(s);
+async function walk(root) {
+    const out = [];
+    async function visit(dir, rel, depth) {
+        if (depth > 8 || out.length >= MAX_WALK_FILES)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const e of entries) {
+            if (out.length >= MAX_WALK_FILES)
+                return;
+            const r = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    await visit(path.join(dir, e.name), r, depth + 1);
+            }
+            else if (e.isFile())
+                out.push(r);
+        }
+    }
+    await visit(root, '', 0);
+    return out;
+}
+const clip = (text) => (text.length > PER_SOURCE_BYTES ? `${text.slice(0, PER_SOURCE_BYTES)}\n…(truncated)` : text);
+/**
+ * The `instructions` setting: extra files, globs (relative to the workspace) and http(s) URLs whose text is added to
+ * the system prompt. Anything unreadable is skipped. Only the user's own config supplies these (a project file
+ * could otherwise point the model at text from anywhere), and the caller enforces that.
+ */
+export async function buildExtraInstructionsBlock(cwd, entries, deps = {}) {
+    const sources = [];
+    const seen = new Set();
+    const addFile = (label, abs) => {
+        const key = path.resolve(abs);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        sources.push({ label, read: () => readFile(abs, 'utf8') });
+    };
+    let walked;
+    for (const raw of entries) {
+        const entry = raw.trim();
+        if (!entry)
+            continue;
+        if (isUrl(entry)) {
+            if (!/^https?:\/\//i.test(entry) || seen.has(entry))
+                continue;
+            seen.add(entry);
+            sources.push({
+                label: entry,
+                read: async () => {
+                    const res = await (deps.fetch ?? fetch)(entry, { signal: AbortSignal.timeout(URL_TIMEOUT_MS) });
+                    if (!res.ok)
+                        throw new Error(`HTTP ${res.status}`);
+                    return (await res.text()).slice(0, PER_SOURCE_BYTES * 2);
+                },
+            });
+        }
+        else if (isGlob(entry) && !path.isAbsolute(entry) && !entry.startsWith('~')) {
+            walked ??= await walk(cwd);
+            for (const rel of walked.filter((f) => pathMatchesGlob(entry, f)))
+                addFile(rel, path.join(cwd, rel));
+        }
+        else {
+            const abs = entry.startsWith('~') ? path.join(homedir(), entry.slice(1)) : path.resolve(cwd, entry);
+            addFile(entry, abs);
+        }
+    }
+    const blocks = [];
+    let total = 0;
+    for (const s of sources) {
+        if (total >= TOTAL_BYTES)
+            break;
+        let text;
+        try {
+            text = (await s.read()).trim();
+        }
+        catch {
+            continue;
+        }
+        if (!text)
+            continue;
+        const body = clip(text);
+        total += body.length;
+        blocks.push(`<instructions source="${s.label.replace(/"/g, '')}">\n${body}\n</instructions>`);
+    }
+    return blocks.join('\n\n');
+}