factoryhub 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/NOTICE +16 -0
- package/README.md +195 -2
- package/factories/README.md +17 -0
- package/factories/client-file-readiness/README.md +3 -0
- package/factories/client-file-readiness/agents/analyst/agent.md +10 -0
- package/factories/client-file-readiness/agents/reviewer/agent.md +10 -0
- package/factories/client-file-readiness/agents/writer/agent.md +11 -0
- package/factories/client-file-readiness/factory.yaml +12 -0
- package/factories/client-file-readiness/flow.yaml +56 -0
- package/factories/competitor-teardown/README.md +3 -0
- package/factories/competitor-teardown/agents/analyst/agent.md +10 -0
- package/factories/competitor-teardown/agents/researcher/agent.md +11 -0
- package/factories/competitor-teardown/agents/reviewer/agent.md +10 -0
- package/factories/competitor-teardown/agents/writer/agent.md +11 -0
- package/factories/competitor-teardown/factory.yaml +11 -0
- package/factories/competitor-teardown/flow.yaml +75 -0
- package/factories/homepage-audit/README.md +3 -0
- package/factories/homepage-audit/agents/analyst/agent.md +10 -0
- package/factories/homepage-audit/agents/researcher/agent.md +11 -0
- package/factories/homepage-audit/agents/reviewer/agent.md +10 -0
- package/factories/homepage-audit/agents/writer/agent.md +11 -0
- package/factories/homepage-audit/factory.yaml +11 -0
- package/factories/homepage-audit/flow.yaml +77 -0
- package/factories/inbox-triage/README.md +3 -0
- package/factories/inbox-triage/agents/analyst/agent.md +10 -0
- package/factories/inbox-triage/agents/reviewer/agent.md +10 -0
- package/factories/inbox-triage/agents/writer/agent.md +11 -0
- package/factories/inbox-triage/factory.yaml +11 -0
- package/factories/inbox-triage/flow.yaml +57 -0
- package/factories/index.json +587 -0
- package/factories/launch-kit/README.md +3 -0
- package/factories/launch-kit/agents/reviewer/agent.md +10 -0
- package/factories/launch-kit/agents/strategist/agent.md +10 -0
- package/factories/launch-kit/agents/writer/agent.md +11 -0
- package/factories/launch-kit/factory.yaml +12 -0
- package/factories/launch-kit/flow.yaml +75 -0
- package/factories/meeting-to-actions/CHANGELOG.md +7 -0
- package/factories/meeting-to-actions/README.md +15 -0
- package/factories/meeting-to-actions/agents/analyst/agent.md +10 -0
- package/factories/meeting-to-actions/agents/reviewer/agent.md +10 -0
- package/factories/meeting-to-actions/agents/writer/agent.md +11 -0
- package/factories/meeting-to-actions/factory.yaml +11 -0
- package/factories/meeting-to-actions/flow.yaml +53 -0
- package/factories/meeting-to-actions/mindburn.requirements.yaml +8 -0
- package/factories/meeting-to-actions/mindburn.tests.yaml +16 -0
- package/factories/newsletter-note/README.md +11 -0
- package/factories/newsletter-note/agents/reviewer/agent.md +10 -0
- package/factories/newsletter-note/agents/writer/agent.md +11 -0
- package/factories/newsletter-note/factory.yaml +12 -0
- package/factories/newsletter-note/flow.yaml +45 -0
- package/factories/newsletter-note/mindburn.tests.yaml +80 -0
- package/factories/outreach-pack/README.md +3 -0
- package/factories/outreach-pack/agents/reviewer/agent.md +5 -0
- package/factories/outreach-pack/agents/writer/agent.md +5 -0
- package/factories/outreach-pack/factory.yaml +9 -0
- package/factories/outreach-pack/flow.yaml +42 -0
- package/factories/prospect-brief/README.md +3 -0
- package/factories/prospect-brief/agents/researcher/agent.md +11 -0
- package/factories/prospect-brief/agents/reviewer/agent.md +10 -0
- package/factories/prospect-brief/agents/strategist/agent.md +10 -0
- package/factories/prospect-brief/agents/writer/agent.md +11 -0
- package/factories/prospect-brief/factory.yaml +11 -0
- package/factories/prospect-brief/flow.yaml +79 -0
- package/factories/release-desk/README.md +13 -0
- package/factories/release-desk/agents/editor/agent.md +10 -0
- package/factories/release-desk/agents/reviewer/agent.md +10 -0
- package/factories/release-desk/factory.yaml +13 -0
- package/factories/release-desk/flow.yaml +67 -0
- package/factories/release-desk/mindburn.tests.yaml +163 -0
- package/factories/short-video-cut/README.md +11 -0
- package/factories/short-video-cut/agents/reviewer/agent.md +10 -0
- package/factories/short-video-cut/agents/writer/agent.md +11 -0
- package/factories/short-video-cut/factory.yaml +13 -0
- package/factories/short-video-cut/flow.yaml +46 -0
- package/factories/short-video-cut/mindburn.tests.yaml +80 -0
- package/factories/video-facts/README.md +11 -0
- package/factories/video-facts/agents/analyst/agent.md +10 -0
- package/factories/video-facts/agents/reviewer/agent.md +10 -0
- package/factories/video-facts/factory.yaml +13 -0
- package/factories/video-facts/flow.yaml +39 -0
- package/factories/video-facts/mindburn.tests.yaml +34 -0
- package/factories/video-to-posts/README.md +35 -0
- package/factories/video-to-posts/agents/analyst/agent.md +10 -0
- package/factories/video-to-posts/agents/reviewer/agent.md +10 -0
- package/factories/video-to-posts/agents/writer/agent.md +11 -0
- package/factories/video-to-posts/factory.yaml +12 -0
- package/factories/video-to-posts/flow.yaml +62 -0
- package/factories/video-to-posts/mindburn.tests.yaml +34 -0
- package/factories/week-of-posts/README.md +11 -0
- package/factories/week-of-posts/agents/reviewer/agent.md +10 -0
- package/factories/week-of-posts/agents/writer/agent.md +11 -0
- package/factories/week-of-posts/factory.yaml +12 -0
- package/factories/week-of-posts/flow.yaml +46 -0
- package/factories/week-of-posts/mindburn.tests.yaml +80 -0
- package/package.json +92 -4
- package/packages/cli/bin/factoryhub.mjs +8 -0
- package/packages/cli/package.json +29 -0
- package/packages/cli/src/args.mjs +47 -0
- package/packages/cli/src/commands/export.mjs +54 -0
- package/packages/cli/src/commands/get.mjs +37 -0
- package/packages/cli/src/commands/inspect.mjs +65 -0
- package/packages/cli/src/commands/list.mjs +24 -0
- package/packages/cli/src/commands/login.mjs +161 -0
- package/packages/cli/src/commands/logout.mjs +43 -0
- package/packages/cli/src/commands/mcp.mjs +25 -0
- package/packages/cli/src/commands/new.mjs +147 -0
- package/packages/cli/src/commands/pack.mjs +96 -0
- package/packages/cli/src/commands/publish.mjs +62 -0
- package/packages/cli/src/commands/pull.mjs +59 -0
- package/packages/cli/src/commands/push.mjs +115 -0
- package/packages/cli/src/commands/resume.mjs +66 -0
- package/packages/cli/src/commands/run.mjs +352 -0
- package/packages/cli/src/commands/runs.mjs +52 -0
- package/packages/cli/src/commands/search.mjs +30 -0
- package/packages/cli/src/commands/validate.mjs +79 -0
- package/packages/cli/src/commands/whoami.mjs +34 -0
- package/packages/cli/src/hosted.mjs +159 -0
- package/packages/cli/src/main.mjs +134 -0
- package/packages/cli/src/tool-sources.mjs +272 -0
- package/packages/cli/src/util.mjs +58 -0
- package/packages/engine/lib/catalog.mjs +50 -0
- package/packages/engine/lib/credentials.mjs +121 -0
- package/packages/engine/lib/hosted.mjs +119 -0
- package/packages/engine/lib/hub.mjs +423 -0
- package/packages/engine/lib/nango.mjs +157 -0
- package/packages/engine/lib/node.mjs +242 -0
- package/packages/engine/lib/providers.mjs +57 -0
- package/packages/engine/lib/run.mjs +192 -0
- package/packages/engine/lib/skill.mjs +229 -0
- package/packages/engine/lib/text.mjs +5 -0
- package/packages/engine/package.json +45 -0
- package/packages/engine/src/author-tests.mjs +78 -0
- package/packages/engine/src/compose.mjs +150 -0
- package/packages/engine/src/cost.mjs +41 -0
- package/packages/engine/src/diagnostics.mjs +21 -0
- package/packages/engine/src/factory-engine.mjs +2109 -0
- package/packages/engine/src/flow-sources.mjs +135 -0
- package/packages/engine/src/index.mjs +9 -0
- package/packages/engine/src/markdown.mjs +97 -0
- package/packages/engine/src/mcp-client.mjs +429 -0
- package/packages/engine/src/package.mjs +116 -0
- package/packages/engine/src/run.mjs +308 -0
- package/packages/engine/src/tool-sources.mjs +566 -0
- package/packages/mcp/bin/factoryhub-mcp.mjs +6 -0
- package/packages/mcp/package.json +36 -0
- package/packages/mcp/src/server.mjs +310 -0
- package/packages/sdk/package.json +28 -0
- package/packages/sdk/src/index.d.ts +163 -0
- package/packages/sdk/src/index.mjs +266 -0
- package/spec/README.md +42 -0
- package/spec/factory-format.md +866 -0
- package/spec/schema/factory.schema.json +43 -0
- package/spec/schema/factory.yaml.json +815 -0
- package/spec/schema/flow.schema.json +191 -0
- package/spec/skill-export.md +129 -0
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
// Node.js helpers around the engine: read a factory from a folder, a bundle
|
|
2
|
+
// file or an address, and write one back to disk. The engine itself stays
|
|
3
|
+
// free of file system access so the same code runs in a browser.
|
|
4
|
+
import * as fsp from 'node:fs/promises';
|
|
5
|
+
import { readFile, mkdir, lstat, open, unlink } from 'node:fs/promises';
|
|
6
|
+
import { existsSync, constants } from 'node:fs';
|
|
7
|
+
import { join, relative, resolve, dirname, sep } from 'node:path';
|
|
8
|
+
import { fileURLToPath } from 'node:url';
|
|
9
|
+
import { ALLOWED_PATH, fromEnvelope, normalizeFiles } from '../src/factory-engine.mjs';
|
|
10
|
+
|
|
11
|
+
// The folders a factory's companion files may live in. Only these are walked,
|
|
12
|
+
// so a factory kept inside a project never pulls in node_modules or the like.
|
|
13
|
+
export const SOURCE_FOLDERS = new Set(['agents', 'automations', 'scorers', 'runners', 'routers', 'webhooks', 'benchmarks', 'skills', 'self-improvement',
|
|
14
|
+
'profiles', 'flows', 'schemas', 'prompts', 'assets', 'examples', 'checks', 'fixtures', 'capabilities', 'policies', 'adapters', 'ui']);
|
|
15
|
+
|
|
16
|
+
// Files the runner and packer put next to a factory. They are never source.
|
|
17
|
+
const GENERATED = new Set(['RUNNING.md', 'run.mjs', 'factory-engine.mjs', 'author-tests.mjs', 'INPUTS.schema.json', 'FACTORY-HUB.json']);
|
|
18
|
+
|
|
19
|
+
/** The house factories that ship in this repository. */
|
|
20
|
+
export const HOUSE_FACTORIES = resolve(dirname(fileURLToPath(import.meta.url)), '../../../factories');
|
|
21
|
+
|
|
22
|
+
// At most `size` tasks given to the returned function run at once; a task
|
|
23
|
+
// that ends hands its place to the next one waiting.
|
|
24
|
+
function limiter(size) {
|
|
25
|
+
let active = 0;
|
|
26
|
+
const waiting = [];
|
|
27
|
+
return async (task) => {
|
|
28
|
+
if (active < size) active += 1;
|
|
29
|
+
else await new Promise((resolve) => waiting.push(resolve));
|
|
30
|
+
try { return await task(); } finally {
|
|
31
|
+
const next = waiting.shift();
|
|
32
|
+
if (next) next();
|
|
33
|
+
else active -= 1;
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// File system calls of every folder being read share this limit, so reading
|
|
39
|
+
// many factories at once never opens more files than this.
|
|
40
|
+
const io = limiter(64);
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Reads the files of a factory folder, as the engine admits them.
|
|
44
|
+
* `skipped` lists files that look meant for the factory but are not part of it.
|
|
45
|
+
* Every directory and file is read at the same time; the results are then
|
|
46
|
+
* taken in the order a depth-first walk meets them, so `skipped` and the
|
|
47
|
+
* first error are the same as when they were read one by one. `fs` is for
|
|
48
|
+
* tests.
|
|
49
|
+
*/
|
|
50
|
+
export async function readFolder(root, { fs = fsp } = {}) {
|
|
51
|
+
const walk = async (dir) => {
|
|
52
|
+
const entries = await io(() => fs.readdir(dir, { withFileTypes: true }));
|
|
53
|
+
entries.sort((a, b) => a.name.localeCompare(b.name));
|
|
54
|
+
return Promise.all(entries.map(async (entry) => {
|
|
55
|
+
const { name } = entry;
|
|
56
|
+
if (name.startsWith('.')) return null;
|
|
57
|
+
const path = join(dir, name);
|
|
58
|
+
const rel = relative(root, path).split(sep).join('/');
|
|
59
|
+
try {
|
|
60
|
+
if (entry.isSymbolicLink()) {
|
|
61
|
+
if (dir !== root || SOURCE_FOLDERS.has(name) || ALLOWED_PATH.test(rel)) throw new Error(`Factory source cannot contain a symbolic link: ${rel}`);
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
if (entry.isDirectory()) return SOURCE_FOLDERS.has(name) || dir !== root ? { items: await walk(path) } : null;
|
|
65
|
+
if (dir === root && GENERATED.has(name)) return null;
|
|
66
|
+
if (ALLOWED_PATH.test(rel)) return { rel, content: await io(() => fs.readFile(path, 'utf8')) };
|
|
67
|
+
return dir !== root || /\.(md|ya?ml)$/i.test(name) ? { skipped: rel } : null;
|
|
68
|
+
} catch (error) {
|
|
69
|
+
return { error };
|
|
70
|
+
}
|
|
71
|
+
}));
|
|
72
|
+
};
|
|
73
|
+
const files = {};
|
|
74
|
+
const skipped = [];
|
|
75
|
+
const take = (items) => {
|
|
76
|
+
for (const item of items) {
|
|
77
|
+
if (!item) continue;
|
|
78
|
+
if (item.error) throw item.error;
|
|
79
|
+
if (item.items) take(item.items);
|
|
80
|
+
else if (item.skipped) skipped.push(item.skipped);
|
|
81
|
+
else files[item.rel] = item.content;
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
take(await walk(root));
|
|
85
|
+
return { files: normalizeFiles(files), skipped };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const isUrl = (value) => /^https?:\/\//i.test(String(value));
|
|
89
|
+
|
|
90
|
+
/** How long reading a bundle from an address may take, as for the hub client. */
|
|
91
|
+
export const BUNDLE_TIMEOUT_MS = 30000;
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Resolves what a person typed to a factory: a folder, a bundle `.json` file,
|
|
95
|
+
* an http(s) address of a bundle, or the id of a house factory.
|
|
96
|
+
* Returns { files, leftOut, source: { kind, location, id } }. An address that
|
|
97
|
+
* does not answer, or does not finish its answer, within `timeoutMs` fails.
|
|
98
|
+
*/
|
|
99
|
+
export async function readFactory(target, { cwd = process.cwd(), fetchImpl = fetch, headers = {}, houseDir = HOUSE_FACTORIES, timeoutMs = BUNDLE_TIMEOUT_MS } = {}) {
|
|
100
|
+
if (!target) throw usage('Name a factory: a folder, a bundle .json file, an address, or a house factory id.');
|
|
101
|
+
if (isUrl(target)) {
|
|
102
|
+
const timedOut = (error) => (error?.name === 'TimeoutError' ? new Error(`${target} did not answer within ${timeoutMs / 1000} seconds.`) : error);
|
|
103
|
+
// The signal also ends a body that stops arriving.
|
|
104
|
+
const response = await fetchImpl(target, { headers: { accept: 'application/json', ...headers }, signal: AbortSignal.timeout(timeoutMs) }).catch((error) => { throw timedOut(error); });
|
|
105
|
+
if (!response.ok) throw new Error(`${target} answered with status ${response.status}.`);
|
|
106
|
+
const read = await fromEnvelope(await response.json().catch((error) => { throw timedOut(error); }));
|
|
107
|
+
if (read.problems.length) throw new Error(`That bundle could not be read:\n${read.problems.map((problem) => ` - ${problem}`).join('\n')}`);
|
|
108
|
+
return { files: read.files, leftOut: read.leftOut, source: { kind: 'url', location: target } };
|
|
109
|
+
}
|
|
110
|
+
const path = resolve(cwd, target);
|
|
111
|
+
if (existsSync(path) && (await lstat(path)).isFile()) {
|
|
112
|
+
if (!path.endsWith('.json')) throw usage(`${target} is a file. Point at a factory folder or a bundle .json file.`);
|
|
113
|
+
const read = await fromEnvelope(JSON.parse(await fsp.readFile(path, 'utf8')));
|
|
114
|
+
if (read.problems.length) throw new Error(`That bundle could not be read:\n${read.problems.map((problem) => ` - ${problem}`).join('\n')}`);
|
|
115
|
+
return { files: read.files, leftOut: read.leftOut, source: { kind: 'bundle', location: path } };
|
|
116
|
+
}
|
|
117
|
+
if (existsSync(path)) {
|
|
118
|
+
if (!existsSync(join(path, 'factory.yaml'))) throw usage(`No factory.yaml in ${target}.`);
|
|
119
|
+
const { files, skipped } = await readFolder(path);
|
|
120
|
+
return { files, leftOut: skipped, source: { kind: 'folder', location: path } };
|
|
121
|
+
}
|
|
122
|
+
if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(target) && existsSync(join(houseDir, target, 'factory.yaml'))) {
|
|
123
|
+
const location = join(houseDir, target);
|
|
124
|
+
const { files, skipped } = await readFolder(location);
|
|
125
|
+
return { files, leftOut: skipped, source: { kind: 'house', location, id: target } };
|
|
126
|
+
}
|
|
127
|
+
throw usage(`No factory at ${target}. Use a folder with a factory.yaml, a bundle .json file, an address, or one of: ${(await listFactoryDirs(houseDir)).join(', ')}.`);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** The ids of the factory folders directly inside `dir`, sorted. */
|
|
131
|
+
export async function listFactoryDirs(dir = HOUSE_FACTORIES) {
|
|
132
|
+
if (!existsSync(dir)) return [];
|
|
133
|
+
const entries = await fsp.readdir(dir, { withFileTypes: true });
|
|
134
|
+
return entries.filter((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, 'factory.yaml'))).map((entry) => entry.name).sort();
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const lstatOrNull = async (path) => {
|
|
138
|
+
try { return await lstat(path); } catch (error) {
|
|
139
|
+
if (error.code === 'ENOENT') return null;
|
|
140
|
+
throw error;
|
|
141
|
+
}
|
|
142
|
+
};
|
|
143
|
+
// Opens a file for writing without following a symbolic link where the
|
|
144
|
+
// platform can refuse one (O_NOFOLLOW); every folder above it is checked first.
|
|
145
|
+
const WRITE_FLAGS = constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW || 0);
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The folder files are written into, made if it is missing. A folder that is
|
|
149
|
+
* itself a symbolic link is refused: writing through it would land elsewhere.
|
|
150
|
+
*/
|
|
151
|
+
async function writableRoot(dir) {
|
|
152
|
+
const root = resolve(dir);
|
|
153
|
+
const info = await lstatOrNull(root);
|
|
154
|
+
if (info?.isSymbolicLink()) throw new Error(`Refusing to write into ${root}: it is a symbolic link.`);
|
|
155
|
+
if (info && !info.isDirectory()) throw new Error(`Refusing to write into ${root}: it is not a folder.`);
|
|
156
|
+
if (!info) await mkdir(root, { recursive: true });
|
|
157
|
+
return root;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* The absolute path for one relative file under `root`, with every folder on
|
|
162
|
+
* the way made or checked: none may be a symbolic link, and the file itself,
|
|
163
|
+
* if it exists, must be a plain file.
|
|
164
|
+
*/
|
|
165
|
+
async function safeTarget(root, path) {
|
|
166
|
+
const target = resolve(root, path);
|
|
167
|
+
if (!target.startsWith(root + sep)) throw new Error(`Refusing to write outside ${root}: ${path}`);
|
|
168
|
+
const parts = relative(root, target).split(sep);
|
|
169
|
+
let current = root;
|
|
170
|
+
for (const part of parts.slice(0, -1)) {
|
|
171
|
+
current = join(current, part);
|
|
172
|
+
const info = await lstatOrNull(current);
|
|
173
|
+
if (!info) { await mkdir(current); continue; }
|
|
174
|
+
if (info.isSymbolicLink()) throw new Error(`Refusing to write "${path}": ${relative(root, current).split(sep).join('/')} is a symbolic link.`);
|
|
175
|
+
if (!info.isDirectory()) throw new Error(`Refusing to write "${path}": ${relative(root, current).split(sep).join('/')} is not a folder.`);
|
|
176
|
+
}
|
|
177
|
+
const info = await lstatOrNull(target);
|
|
178
|
+
if (info?.isSymbolicLink()) throw new Error(`Refusing to write "${path}": it is a symbolic link.`);
|
|
179
|
+
if (info && !info.isFile()) throw new Error(`Refusing to write "${path}": it is not a plain file.`);
|
|
180
|
+
return target;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
async function writeOne(target, content) {
|
|
184
|
+
const handle = await open(target, WRITE_FLAGS, 0o644);
|
|
185
|
+
try { await handle.writeFile(content); } finally { await handle.close(); }
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Writes bundle files under `dir`. Every path must be one the engine admits,
|
|
190
|
+
* so a bundle from elsewhere cannot write outside its folder, and no file is
|
|
191
|
+
* written through a symbolic link.
|
|
192
|
+
*/
|
|
193
|
+
export async function writeFiles(dir, files, { allow = (path) => ALLOWED_PATH.test(path) } = {}) {
|
|
194
|
+
for (const path of Object.keys(files)) if (!allow(path)) throw new Error(`Refusing to write "${path}": it is not a factory file.`);
|
|
195
|
+
const root = await writableRoot(dir);
|
|
196
|
+
for (const [path, content] of Object.entries(files)) await writeOne(await safeTarget(root, path), content);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** The record `pull` keeps of the files it wrote, so a later pull removes only those. */
|
|
200
|
+
export const PULL_MANIFEST = '.factoryhub-pull.json';
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Writes a pulled factory into `dir` and records what it wrote in
|
|
204
|
+
* PULL_MANIFEST. With `replace`, files a previous pull wrote (as its
|
|
205
|
+
* manifest lists them) that the new version no longer has are removed; no
|
|
206
|
+
* other file is ever deleted. Returns { removed }.
|
|
207
|
+
*/
|
|
208
|
+
export async function writePulled(dir, files, { replace = false, record = {} } = {}) {
|
|
209
|
+
const root = await writableRoot(dir);
|
|
210
|
+
const removed = [];
|
|
211
|
+
if (replace) {
|
|
212
|
+
const listed = await readPullManifest(root);
|
|
213
|
+
for (const path of listed) {
|
|
214
|
+
if (files[path] !== undefined || !ALLOWED_PATH.test(path)) continue;
|
|
215
|
+
const target = await safeTarget(root, path).catch(() => null);
|
|
216
|
+
if (!target) continue;
|
|
217
|
+
const info = await lstatOrNull(target);
|
|
218
|
+
if (!info?.isFile()) continue;
|
|
219
|
+
await unlink(target);
|
|
220
|
+
removed.push(path);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
await writeFiles(root, files);
|
|
224
|
+
const manifest = await safeTarget(root, PULL_MANIFEST);
|
|
225
|
+
await writeOne(manifest, `${JSON.stringify({ format: 'factoryhub.pull/v1', ...record, files: Object.keys(files) }, null, 2)}\n`);
|
|
226
|
+
return { removed };
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
async function readPullManifest(root) {
|
|
230
|
+
const path = join(root, PULL_MANIFEST);
|
|
231
|
+
const info = await lstatOrNull(path);
|
|
232
|
+
if (!info?.isFile()) return [];
|
|
233
|
+
try {
|
|
234
|
+
const parsed = JSON.parse(await readFile(path, 'utf8'));
|
|
235
|
+
return Array.isArray(parsed?.files) ? parsed.files.filter((file) => typeof file === 'string') : [];
|
|
236
|
+
} catch { return []; }
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** An error that means the person asked for something unclear: exit code 2. */
|
|
240
|
+
export function usage(message) {
|
|
241
|
+
return Object.assign(new Error(message), { usage: true });
|
|
242
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
// Chooses the model a run uses, from the person's own key or a local server.
|
|
2
|
+
// Nothing here has a key of its own: every call is billed to whoever runs it.
|
|
3
|
+
import { anthropicProvider, openaiProvider } from '../src/factory-engine.mjs';
|
|
4
|
+
|
|
5
|
+
export const PROVIDERS = ['anthropic', 'openai', 'openrouter', 'ollama', 'openai-compatible'];
|
|
6
|
+
export const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
|
|
7
|
+
export const OLLAMA_BASE_URL = 'http://localhost:11434/v1';
|
|
8
|
+
/** Where each hosted provider's key may go. Any other address is a custom server. */
|
|
9
|
+
export const OFFICIAL = { anthropic: 'https://api.anthropic.com', openai: 'https://api.openai.com/v1', openrouter: OPENROUTER_BASE_URL };
|
|
10
|
+
const KEY_OF = { anthropic: 'ANTHROPIC_API_KEY', openai: 'OPENAI_API_KEY', openrouter: 'OPENROUTER_API_KEY' };
|
|
11
|
+
const DEFAULT_MODELS = { anthropic: 'claude-sonnet-5-5', openai: 'gpt-5', openrouter: 'openrouter/auto' };
|
|
12
|
+
|
|
13
|
+
const problem = (message) => Object.assign(new Error(message), { usage: true });
|
|
14
|
+
const trim = (url) => String(url).replace(/\/+$/, '');
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Picks a provider.
|
|
18
|
+
*
|
|
19
|
+
* - `provider` names one of PROVIDERS. Without it: a `baseUrl` means an
|
|
20
|
+
* OpenAI-compatible server, otherwise the first key found among
|
|
21
|
+
* ANTHROPIC_API_KEY, OPENAI_API_KEY and OPENROUTER_API_KEY decides.
|
|
22
|
+
* - A key from the environment goes only to its provider's own address. Any
|
|
23
|
+
* other `baseUrl` receives a key only from the variable named in
|
|
24
|
+
* `apiKeyEnv`, whichever provider is named, so a changed address can never
|
|
25
|
+
* carry a provider key away.
|
|
26
|
+
* - `model` falls back to FACTORYHUB_MODEL, then to a default for hosted
|
|
27
|
+
* providers. Local servers need a model name.
|
|
28
|
+
* - `effort` (anthropic only) sets output_config.effort; `maxOutput` the
|
|
29
|
+
* room each call leaves for thinking and the answer; `timeoutMs` how long
|
|
30
|
+
* one call may take.
|
|
31
|
+
*/
|
|
32
|
+
export function chooseProvider({ provider, model, baseUrl, apiKeyEnv, effort, maxOutput, timeoutMs, env = process.env, fetchImpl = fetch } = {}) {
|
|
33
|
+
let kind = provider ? String(provider).toLowerCase() : null;
|
|
34
|
+
if (kind && !PROVIDERS.includes(kind)) throw problem(`Unknown provider "${provider}". Use one of: ${PROVIDERS.join(', ')}.`);
|
|
35
|
+
if (!kind) {
|
|
36
|
+
if (baseUrl) kind = 'openai-compatible';
|
|
37
|
+
else if (env.ANTHROPIC_API_KEY) kind = 'anthropic';
|
|
38
|
+
else if (env.OPENAI_API_KEY) kind = 'openai';
|
|
39
|
+
else if (env.OPENROUTER_API_KEY) kind = 'openrouter';
|
|
40
|
+
}
|
|
41
|
+
if (!kind) throw problem('No model configured. Set ANTHROPIC_API_KEY, OPENAI_API_KEY or OPENROUTER_API_KEY, or use a server on your machine: provider "ollama" with a model name, or an OpenAI-compatible base URL with a model name.');
|
|
42
|
+
const chosen = model || env.FACTORYHUB_MODEL || DEFAULT_MODELS[kind];
|
|
43
|
+
if (!chosen) throw problem(`Name the model to use with ${kind}.`);
|
|
44
|
+
const keyFrom = (name) => {
|
|
45
|
+
const value = env[name];
|
|
46
|
+
if (!value) throw problem(`${name} is not set.`);
|
|
47
|
+
return value;
|
|
48
|
+
};
|
|
49
|
+
const address = baseUrl ? trim(baseUrl) : OFFICIAL[kind] || (kind === 'ollama' ? OLLAMA_BASE_URL : null);
|
|
50
|
+
if (!address) throw problem('An OpenAI-compatible server needs a base URL.');
|
|
51
|
+
// The provider's own key for its own address; otherwise only a key the person named.
|
|
52
|
+
const apiKey = apiKeyEnv ? keyFrom(apiKeyEnv) : KEY_OF[kind] && address === OFFICIAL[kind] ? keyFrom(KEY_OF[kind]) : '';
|
|
53
|
+
if (effort && kind !== 'anthropic') throw problem('Effort is set only for the anthropic provider.');
|
|
54
|
+
const extra = { ...(timeoutMs ? { timeoutMs } : {}) };
|
|
55
|
+
if (kind === 'anthropic') return anthropicProvider({ apiKey, model: chosen, fetchImpl, baseUrl: address, effort: effort || null, ...(maxOutput ? { maxOutput } : {}), ...extra });
|
|
56
|
+
return openaiProvider({ apiKey, model: chosen, fetchImpl, baseUrl: address, ...extra });
|
|
57
|
+
}
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
// Runs a factory on this machine: the host the engine needs (model, web
|
|
2
|
+
// reading, events) and the start, decide and resume steps that the CLI and
|
|
3
|
+
// the MCP server share. The engine decides nothing for the person: a run
|
|
4
|
+
// that reaches an approval step waits until someone answers.
|
|
5
|
+
import { lookup } from 'node:dns/promises';
|
|
6
|
+
import { isIP } from 'node:net';
|
|
7
|
+
import { parseBundle, checkInputs, newRun, runToEnd, resume, decisionProblem, ensureApprovalIdentity, isPublicAddress, htmlToText, DEFAULT_LIMITS, sha256 } from '../src/factory-engine.mjs';
|
|
8
|
+
import { canonicalFiles } from './catalog.mjs';
|
|
9
|
+
|
|
10
|
+
export const USER_AGENT = 'Mozilla/5.0 (compatible; FactoryRunner/1.0)';
|
|
11
|
+
|
|
12
|
+
/** How much of a page is read, as on the factoryhub site: the rest is never downloaded. */
|
|
13
|
+
export const PAGE_BYTES = 1500000;
|
|
14
|
+
const CUT_NOTE = `[Page cut here: only the first ${PAGE_BYTES.toLocaleString('en-US')} bytes of the page were read]`;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Reads a response body up to `max` bytes, then stops the download.
|
|
18
|
+
* Returns { text, cut }; the text is decoded as UTF-8, as response.text() does.
|
|
19
|
+
*/
|
|
20
|
+
export async function readCapped(response, max = PAGE_BYTES) {
|
|
21
|
+
const reader = response.body?.getReader();
|
|
22
|
+
const chunks = [];
|
|
23
|
+
let total = 0;
|
|
24
|
+
let cut = false;
|
|
25
|
+
while (reader) {
|
|
26
|
+
const { done, value } = await reader.read();
|
|
27
|
+
if (done) break;
|
|
28
|
+
chunks.push(value);
|
|
29
|
+
total += value.byteLength;
|
|
30
|
+
if (total >= max) {
|
|
31
|
+
// A page that ends exactly at the limit was not cut.
|
|
32
|
+
cut = total > max || !(await reader.read()).done;
|
|
33
|
+
await reader.cancel().catch(() => {});
|
|
34
|
+
break;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
const bytes = new Uint8Array(Math.min(total, max));
|
|
38
|
+
let offset = 0;
|
|
39
|
+
for (const chunk of chunks) {
|
|
40
|
+
const part = chunk.subarray(0, bytes.length - offset);
|
|
41
|
+
bytes.set(part, offset);
|
|
42
|
+
offset += part.byteLength;
|
|
43
|
+
}
|
|
44
|
+
return { text: new TextDecoder('utf-8').decode(bytes), cut };
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The text an agent gets from a page response: only text, HTML, XML and JSON
|
|
49
|
+
* are read, and at most PAGE_BYTES of them. A cut page says it was cut, so
|
|
50
|
+
* the run records that only part of it was read.
|
|
51
|
+
*/
|
|
52
|
+
export async function pageText(response, url) {
|
|
53
|
+
const type = (response.headers.get('content-type') || '').toLowerCase();
|
|
54
|
+
if (type && !/text\/|json|xml/.test(type)) {
|
|
55
|
+
await response.body?.cancel().catch(() => {});
|
|
56
|
+
throw new Error(`the address is a ${type.split(';')[0].trim()} file, not a page`);
|
|
57
|
+
}
|
|
58
|
+
const { text, cut } = await readCapped(response);
|
|
59
|
+
const page = htmlToText(text, url);
|
|
60
|
+
const note = cut && !/\[Page cut here: [^\]]*\]$/.test(page) ? CUT_NOTE : '';
|
|
61
|
+
return `Address: ${url}\n\n${[page, note].filter(Boolean).join('\n\n')}`;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const v4 = (ip) => ip.split('.').map(Number);
|
|
65
|
+
/** True for loopback, private, link-local, shared, reserved and multicast addresses. */
|
|
66
|
+
export function isPrivateIp(ip) {
|
|
67
|
+
if (isIP(ip) === 4) {
|
|
68
|
+
const [a, b] = v4(ip);
|
|
69
|
+
return a === 0 || a === 10 || a === 127 || a >= 224 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254)
|
|
70
|
+
|| (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 192 && b === 0) || (a === 198 && (b === 18 || b === 19));
|
|
71
|
+
}
|
|
72
|
+
const low = ip.toLowerCase();
|
|
73
|
+
const mapped = low.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
|
|
74
|
+
if (mapped) return isPrivateIp(mapped[1]);
|
|
75
|
+
return low === '::' || low === '::1' || /^f[cd]/.test(low) || /^fe[89ab]/.test(low) || /^ff/.test(low) || low.startsWith('64:ff9b:');
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* The host object the engine runs against. `fetchImpl` reads web pages.
|
|
80
|
+
* Only public http(s) addresses are read: the engine's check on the address
|
|
81
|
+
* text, and here also every address the host name resolves to, so a public
|
|
82
|
+
* looking name that points at this machine or its network is refused. Every
|
|
83
|
+
* redirect is checked again. The check happens before the request; a name
|
|
84
|
+
* whose answer changes in between is not caught.
|
|
85
|
+
*/
|
|
86
|
+
export function nodeHost({ provider, emit = () => {}, fetchImpl = fetch, resolve = (host) => lookup(host, { all: true, verbatim: true }), limits = DEFAULT_LIMITS, now = () => Date.now() }) {
|
|
87
|
+
return {
|
|
88
|
+
provider,
|
|
89
|
+
limits,
|
|
90
|
+
now,
|
|
91
|
+
async fetchPage(address) {
|
|
92
|
+
let url = address;
|
|
93
|
+
for (let hop = 0; hop < 6; hop += 1) {
|
|
94
|
+
if (!isPublicAddress(url)) throw new Error('that is not a public web address');
|
|
95
|
+
let answers;
|
|
96
|
+
try { answers = await resolve(new URL(url).hostname); } catch { throw new Error('the address could not be found'); }
|
|
97
|
+
if (!answers.length || answers.some((answer) => isPrivateIp(answer.address))) throw new Error('that address points at a private network');
|
|
98
|
+
const response = await fetchImpl(url, { redirect: 'manual', headers: { 'user-agent': USER_AGENT, accept: 'text/html,*/*;q=0.5' }, signal: AbortSignal.timeout(20000) });
|
|
99
|
+
if (response.status >= 300 && response.status < 400) { url = new URL(response.headers.get('location') || '', url).href; continue; }
|
|
100
|
+
if (!response.ok) throw new Error(`the site answered with status ${response.status}`);
|
|
101
|
+
return pageText(response, url);
|
|
102
|
+
}
|
|
103
|
+
throw new Error('the page redirects too many times');
|
|
104
|
+
},
|
|
105
|
+
emit,
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Prepares a run: parses the factory, refuses one that cannot run here, and
|
|
111
|
+
* checks the inputs before any model is called.
|
|
112
|
+
*/
|
|
113
|
+
export function prepareRun({ files, inputs = {}, id, runner = { mode: 'local' }, toolSources = null, features = [] }) {
|
|
114
|
+
// `features`: experimental execution features the caller opts in to (tool sources a flow declares).
|
|
115
|
+
const parsed = parseBundle(canonicalFiles(files), features.length ? { features } : undefined);
|
|
116
|
+
if (!parsed.ok) return { ok: false, problems: parsed.errors };
|
|
117
|
+
// Experimental, opt-in: tool sources (createToolSources) may supply tools
|
|
118
|
+
// that steps name. Without them nothing here changes.
|
|
119
|
+
const admitted = toolSources ? toolSources.admit(parsed.factory, { exact: features.includes('tool-sources') }) : { factory: parsed.factory, problems: [] };
|
|
120
|
+
const { factory } = admitted;
|
|
121
|
+
if (!factory.runnable) {
|
|
122
|
+
return { ok: false, problems: factory.blockers.length ? factory.blockers : ['This factory has no flow.yaml, so there are no steps to run. Follow agents/foreman/agent.md in an agent instead.'] };
|
|
123
|
+
}
|
|
124
|
+
const checked = checkInputs(factory, inputs);
|
|
125
|
+
if (!checked.ok) return { ok: false, problems: checked.problems, factory };
|
|
126
|
+
const state = newRun({ id: id || `local-${Date.now().toString(36)}`, factory, inputs: checked.inputs, runner });
|
|
127
|
+
if (toolSources) {
|
|
128
|
+
state.experimental = [toolSources.feature];
|
|
129
|
+
if (toolSources.records) state.toolSourceRecords = toolSources.records();
|
|
130
|
+
}
|
|
131
|
+
return { ok: true, state, factory };
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Runs until the factory is done, fails, is stopped by the person, or waits
|
|
136
|
+
* at an approval step. `onApproval` may answer decisions; without it the run
|
|
137
|
+
* is returned waiting.
|
|
138
|
+
*/
|
|
139
|
+
export async function continueRun(state, host, onApproval) {
|
|
140
|
+
await runToEnd(state, host, onApproval);
|
|
141
|
+
await ensureApprovalIdentity(state);
|
|
142
|
+
return state;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** What a person must see to decide, and the values a decision must name. */
|
|
146
|
+
export async function pendingDecision(state) {
|
|
147
|
+
if (state.status !== 'waiting' || !state.approval) return null;
|
|
148
|
+
await ensureApprovalIdentity(state);
|
|
149
|
+
const text = state.artifacts[state.approval.artifact] || '';
|
|
150
|
+
return {
|
|
151
|
+
step: state.approval.step,
|
|
152
|
+
title: state.approval.title,
|
|
153
|
+
ask: state.approval.ask,
|
|
154
|
+
shows: state.approval.artifact,
|
|
155
|
+
text,
|
|
156
|
+
seen_sha256: await sha256(text),
|
|
157
|
+
approval_id: state.approval.id,
|
|
158
|
+
revisions_left: state.approval.revisionsLeft,
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* Records a person's decision on a waiting run. Returns '' when accepted, or
|
|
164
|
+
* the engine's reason when not: not_waiting, bad_action, unseen, stale or
|
|
165
|
+
* no_revisions.
|
|
166
|
+
*/
|
|
167
|
+
export function decide(state, { action, note = '', seen, approvalId }) {
|
|
168
|
+
const decision = { action, note, seen, approvalId };
|
|
169
|
+
const why = decisionProblem(state, decision);
|
|
170
|
+
if (why) return why;
|
|
171
|
+
resume(state, decision);
|
|
172
|
+
return '';
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* A run restored from JSON is read again from its own files, so its steps
|
|
177
|
+
* always match the source it carries.
|
|
178
|
+
*/
|
|
179
|
+
export function restoreRun(saved) {
|
|
180
|
+
if (!saved || typeof saved !== 'object' || !saved.factory?.files || typeof saved.factory.files !== 'object') throw new Error('This is not a saved factory run.');
|
|
181
|
+
const parsed = parseBundle(saved.factory.files);
|
|
182
|
+
if (!parsed.ok || !parsed.factory.runnable) throw new Error('The saved run carries a factory that cannot run here.');
|
|
183
|
+
return { ...saved, factory: parsed.factory };
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** A short account of how a run ended, for people and for tool results. */
|
|
187
|
+
export function outcome(state) {
|
|
188
|
+
if (state.status === 'done') return { status: 'done', deliverable: state.deliverable, review: state.receipt?.deliverable_review?.status, flags: state.receipt?.flags || [] };
|
|
189
|
+
if (state.status === 'waiting') return { status: 'waiting', step: state.approval?.step };
|
|
190
|
+
if (state.status === 'stopped') return { status: 'stopped', step: state.stopped?.step, note: state.stopped?.note || '' };
|
|
191
|
+
return { status: state.status, error: state.error, failure: state.failure };
|
|
192
|
+
}
|