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,266 @@
|
|
|
1
|
+
// The factoryhub SDK for JavaScript: `import { login, push, run } from 'factoryhub'`.
|
|
2
|
+
//
|
|
3
|
+
// Every function takes the same connection options:
|
|
4
|
+
// baseUrl the hub address (default FACTORYHUB_BASE_URL or https://factory.mindburn.org)
|
|
5
|
+
// token a personal access token (default FACTORYHUB_TOKEN, then the login
|
|
6
|
+
// `factoryhub login` or login() saved for that hub)
|
|
7
|
+
// accessKey the preview key (default FACTORYHUB_ACCESS_KEY)
|
|
8
|
+
// fetch a fetch implementation (default the global one)
|
|
9
|
+
// env the environment to read those defaults from (default process.env)
|
|
10
|
+
//
|
|
11
|
+
// The SDK shares its token store with the CLI, so a login in either works for
|
|
12
|
+
// both. A token is sent only in the Authorization header, only over https or
|
|
13
|
+
// to this machine, and is never returned or logged; FACTORYHUB_TOKEN goes only
|
|
14
|
+
// to the production hub or the one FACTORYHUB_BASE_URL names. Redirects are
|
|
15
|
+
// followed only within the hub. Nothing here decides a step of a run for the
|
|
16
|
+
// person: run() asks the caller's onDecision, and refuses an approval of a
|
|
17
|
+
// step whose text was not sent whole.
|
|
18
|
+
//
|
|
19
|
+
// Receipts from https://factory.mindburn.org verify against the production
|
|
20
|
+
// keys pinned in this package; from any other hub, against the keys that hub
|
|
21
|
+
// publishes. The receipt's issuer must be the hub either way.
|
|
22
|
+
import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
|
|
23
|
+
import { existsSync } from 'node:fs';
|
|
24
|
+
import { hostname } from 'node:os';
|
|
25
|
+
import { resolve, dirname } from 'node:path';
|
|
26
|
+
import { hubClient, deviceLogin, checkedBase, HubError, DEFAULT_HUB, SCOPES, OPT_IN_SCOPES, TOKEN_PATTERN } from '../../engine/lib/hub.mjs';
|
|
27
|
+
import { resolveToken, saveCredential, storedCredential, deleteCredential, credentialsPath } from '../../engine/lib/credentials.mjs';
|
|
28
|
+
import { followRun, runResult, newIdempotencyKey, checkHostedReceipt, FINISHED } from '../../engine/lib/hosted.mjs';
|
|
29
|
+
import { readFolder, writePulled } from '../../engine/lib/node.mjs';
|
|
30
|
+
import { parseBundle, withForeman, verifyReceipt as verifyWithKeys } from '../../engine/src/factory-engine.mjs';
|
|
31
|
+
|
|
32
|
+
export { HubError, DEFAULT_HUB, SCOPES, OPT_IN_SCOPES };
|
|
33
|
+
|
|
34
|
+
// https, or http to this machine only: no token or key is sent in the clear.
|
|
35
|
+
function baseOf(options) {
|
|
36
|
+
const env = options.env || process.env;
|
|
37
|
+
return checkedBase(options.baseUrl || env.FACTORYHUB_BASE_URL || DEFAULT_HUB);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* A connection to one factoryhub site. The module functions below make one
|
|
42
|
+
* for each call; keep one with `new Hub(options)` to reuse it.
|
|
43
|
+
*/
|
|
44
|
+
export class Hub {
|
|
45
|
+
constructor(options = {}) {
|
|
46
|
+
this.options = { ...options };
|
|
47
|
+
this.env = options.env || process.env;
|
|
48
|
+
this.baseUrl = baseOf(options);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
async #client({ needToken = false } = {}) {
|
|
52
|
+
let token = this.options.token || null;
|
|
53
|
+
let source = token ? 'option' : null;
|
|
54
|
+
let scopes = null;
|
|
55
|
+
if (!token) {
|
|
56
|
+
const found = await resolveToken(this.baseUrl, this.env);
|
|
57
|
+
if (found.expired && needToken) throw new HubError(`The saved login for ${this.baseUrl} expired on ${String(found.record.expires).slice(0, 10)}. Log in again with login().`, { code: 'unauthorized', status: 401 });
|
|
58
|
+
token = found.token;
|
|
59
|
+
source = found.source;
|
|
60
|
+
scopes = found.record?.scopes || null;
|
|
61
|
+
if (found.warning && token) process.emitWarning(found.warning, { code: 'FACTORYHUB_TOKEN_NOT_SENT' });
|
|
62
|
+
if (found.warning && needToken && !token) throw new HubError(`Not logged in to ${this.baseUrl}. ${found.warning}`, { code: 'unauthorized', status: 401 });
|
|
63
|
+
}
|
|
64
|
+
if (needToken && !token) throw new HubError(`Not logged in to ${this.baseUrl}: pass { token }, set FACTORYHUB_TOKEN, or call login() first.`, { code: 'unauthorized', status: 401 });
|
|
65
|
+
return hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token, tokenSource: source === 'option' ? null : source, tokenScopes: scopes });
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Logs in and stores the token where the CLI finds it too.
|
|
70
|
+
* With `token`, checks that token and stores it. Without, runs a device
|
|
71
|
+
* login: `onCode({ userCode, verificationUri, verificationUriComplete, expiresIn })`
|
|
72
|
+
* must show the person the code and the page; the promise resolves once
|
|
73
|
+
* they approve. Returns { account, token, saved, replaced } without the
|
|
74
|
+
* secret. A token an earlier device login saved is revoked when this one
|
|
75
|
+
* replaces it; a token that was passed in is never revoked.
|
|
76
|
+
*/
|
|
77
|
+
async login({ token, scopes, name, days, onCode, save = true, sleep } = {}) {
|
|
78
|
+
let secret = token;
|
|
79
|
+
const origin = secret === undefined ? 'device' : 'pasted';
|
|
80
|
+
if (secret === undefined) {
|
|
81
|
+
if (typeof onCode !== 'function') throw new HubError('A device login needs onCode, to show the person the code and the page.', { code: 'usage' });
|
|
82
|
+
const unknown = (scopes || []).filter((scope) => !SCOPES.includes(scope));
|
|
83
|
+
if (unknown.length) throw new HubError(`Unknown scope ${unknown.join(', ')}. Choose from: ${SCOPES.join(', ')}.`, { code: 'usage' });
|
|
84
|
+
const anonymous = hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch });
|
|
85
|
+
const answer = await deviceLogin(anonymous, { name: name || `factoryhub SDK on ${hostname() || 'this computer'}`.slice(0, 60), scopes, days, onCode, sleep });
|
|
86
|
+
secret = answer.access_token;
|
|
87
|
+
} else if (!TOKEN_PATTERN.test(String(secret))) {
|
|
88
|
+
throw new HubError('That is not a factoryhub personal access token: they start with fhpat_ and are 49 characters long.', { code: 'usage' });
|
|
89
|
+
}
|
|
90
|
+
const me = await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: secret }).me();
|
|
91
|
+
let saved = null;
|
|
92
|
+
let replaced = null;
|
|
93
|
+
if (save) {
|
|
94
|
+
const previous = await storedCredential(this.baseUrl, this.env);
|
|
95
|
+
saved = await saveCredential(this.baseUrl, { token: secret, origin, id: me.token.id, name: me.token.name, prefix: me.token.prefix, scopes: me.token.scopes, expires: me.token.expires, account: me.account.handle }, this.env);
|
|
96
|
+
if (previous?.token && previous.token !== secret) {
|
|
97
|
+
if (previous.origin !== 'device') replaced = 'kept';
|
|
98
|
+
else {
|
|
99
|
+
replaced = await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: previous.token }).revoke().then(() => 'revoked', () => 'not_revoked');
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
this.options.token = secret;
|
|
104
|
+
return { account: me.account, token: me.token, saved, replaced };
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/** Revokes the stored token on the hub, then forgets it. True when there was one. */
|
|
108
|
+
async logout() {
|
|
109
|
+
const stored = await storedCredential(this.baseUrl, this.env);
|
|
110
|
+
if (!stored) return false;
|
|
111
|
+
try {
|
|
112
|
+
await hubClient({ baseUrl: this.baseUrl, accessKey: this.options.accessKey, env: this.env, fetchImpl: this.options.fetch || fetch, token: stored.token, tokenSource: 'file' }).revoke();
|
|
113
|
+
} catch (error) {
|
|
114
|
+
if (error.status !== 401) throw error;
|
|
115
|
+
}
|
|
116
|
+
await deleteCredential(this.baseUrl, this.env);
|
|
117
|
+
return true;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** The account and token the token acts for: { account, token }. */
|
|
121
|
+
async whoami() {
|
|
122
|
+
return (await this.#client({ needToken: true })).me();
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Saves a factory to the account, privately. `source` is a folder path or a
|
|
127
|
+
* { path: content } map. The factory is checked here first, as the site
|
|
128
|
+
* checks it. Returns { factory: { id, url, title, visibility, sha256 }, parent, unchanged }.
|
|
129
|
+
*/
|
|
130
|
+
async push(source, { parent } = {}) {
|
|
131
|
+
const files = typeof source === 'string' ? (await readFolder(resolve(source))).files : source;
|
|
132
|
+
if (!files || typeof files !== 'object') throw new HubError('push takes a folder path or a { path: content } map of factory files.', { code: 'usage' });
|
|
133
|
+
const parsed = parseBundle(withForeman(files));
|
|
134
|
+
if (!parsed.ok) throw new HubError(`This is not a valid factory yet:\n${parsed.errors.map((error) => ` - ${error}`).join('\n')}`, { code: 'invalid_factory' });
|
|
135
|
+
return (await this.#client({ needToken: true })).push(files, { parent });
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Downloads a factory the caller can open, checking every file's SHA-256
|
|
140
|
+
* and the files together against the bundle hash in the hub's answer:
|
|
141
|
+
* integrity against that answer, not a signature. A bundle that cannot be
|
|
142
|
+
* checked whole is refused unless `partial`. With `dir`, also writes the
|
|
143
|
+
* files into that folder, never through a symbolic link (refusing a
|
|
144
|
+
* non-empty one unless `force`; `force` removes only files an earlier pull
|
|
145
|
+
* wrote there). Returns { id, files, sha256, source, leftOut, partial, unchecked, dir, removed }.
|
|
146
|
+
*/
|
|
147
|
+
async pull(id, { dir, force = false, partial = false } = {}) {
|
|
148
|
+
const target = dir ? resolve(dir) : null;
|
|
149
|
+
if (target && !force && existsSync(target) && (await readdir(target)).length) throw new HubError(`${target} is not empty. Pass { force: true } to write into it.`, { code: 'usage' });
|
|
150
|
+
const factory = await (await this.#client()).pull(id, { partial });
|
|
151
|
+
const { removed } = target ? await writePulled(target, factory.files, { replace: force, record: { id: factory.id, sha256: factory.sha256, source: factory.source, partial: factory.partial } }) : { removed: [] };
|
|
152
|
+
return { ...factory, dir: target, removed };
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Publishes one of the account's factories: it is public at once. Returns { factory, already, message }. */
|
|
156
|
+
async publish(id, { note = '' } = {}) {
|
|
157
|
+
return (await this.#client({ needToken: true })).publish(id, { note });
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** The account's recent hosted runs. */
|
|
161
|
+
async runs({ limit } = {}) {
|
|
162
|
+
return (await this.#client({ needToken: true })).runs({ limit });
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* Runs a factory on the hub and follows it.
|
|
167
|
+
* inputs { key: value }
|
|
168
|
+
* onEvent (event) => void, for progress
|
|
169
|
+
* onDecision async (waiting) => { decision: 'approve' | 'revise' | 'reject', note? } | null
|
|
170
|
+
* Called where the run waits for the person, with the exact
|
|
171
|
+
* text. Return the person's own decision, or null to leave
|
|
172
|
+
* the run waiting. Needs a token with the opt-in runs:decide.
|
|
173
|
+
* When the hub sent only part of the text (`complete: false`),
|
|
174
|
+
* an approval is refused: decide on the run page.
|
|
175
|
+
* Resolves to { status, run, url, result?, waiting? }: status 'done' with
|
|
176
|
+
* result { text, receipt, verification, review }, 'waiting' with the step,
|
|
177
|
+
* or 'failed' / 'stopped'.
|
|
178
|
+
*/
|
|
179
|
+
async run(id, { inputs = {}, onEvent, onDecision, idempotencyKey = newIdempotencyKey(), every = 2000, sleep } = {}) {
|
|
180
|
+
const hub = await this.#client({ needToken: true });
|
|
181
|
+
const started = await hub.startRun(id, inputs, { idempotencyKey });
|
|
182
|
+
const decided = new Set();
|
|
183
|
+
for (;;) {
|
|
184
|
+
const view = await followRun(hub, started.id, { onEvent: onEvent ? (event) => onEvent(event) : undefined, every, sleep });
|
|
185
|
+
const waiting = view.waiting;
|
|
186
|
+
const key = waiting ? `${waiting.approval_id}:${waiting.artifact_sha256}` : null;
|
|
187
|
+
if (key && decided.has(key)) { await (sleep || ((ms) => new Promise((done) => setTimeout(done, ms))))(every); continue; }
|
|
188
|
+
if (waiting) {
|
|
189
|
+
const choice = onDecision ? await onDecision(waiting) : null;
|
|
190
|
+
if (!choice) return { status: 'waiting', run: started.id, url: view.url, waiting };
|
|
191
|
+
if (choice.decision === 'approve' && waiting.complete !== true) {
|
|
192
|
+
throw new HubError(`Not approved: the hub sent only part of "${waiting.title}" (${waiting.totalChars} characters in all), so it cannot be approved from here. Read and decide on the run page: ${view.url}`, { code: 'incomplete' });
|
|
193
|
+
}
|
|
194
|
+
await hub.decide(view.id, { approvalId: waiting.approval_id, seenSha256: waiting.artifact_sha256, decision: choice.decision, note: choice.note || '' });
|
|
195
|
+
decided.add(key);
|
|
196
|
+
continue;
|
|
197
|
+
}
|
|
198
|
+
if (view.status === 'done') return { status: 'done', run: started.id, url: view.url, result: await runResult(hub, started.id) };
|
|
199
|
+
return { status: FINISHED.has(view.status) ? view.status : 'unknown', run: started.id, url: view.url, error: view.error || null, stopped: view.stopped || null };
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/** The hub's published receipt keys. */
|
|
204
|
+
async keys() {
|
|
205
|
+
return (await this.#client()).keys();
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* Checks a run receipt's Ed25519 signature over its canonical JSON and, with
|
|
211
|
+
* `deliverable`, that the text matches the hash it records. With `keys`, it
|
|
212
|
+
* runs offline against exactly those keys (trust "given"). Without, it checks
|
|
213
|
+
* the receipt as a receipt from the hub at `baseUrl`: on
|
|
214
|
+
* https://factory.mindburn.org against the production keys pinned in this
|
|
215
|
+
* package (trust "pinned"), elsewhere against the keys that hub publishes
|
|
216
|
+
* (trust "published"), and its issuer against the hub's host. `receipt` is an
|
|
217
|
+
* object, a JSON string or a path to a .receipt.json file.
|
|
218
|
+
* Returns { valid, signed, signatureValid, deliverableMatches, keyId, problems, trust, host?, issuerMatches? }.
|
|
219
|
+
*/
|
|
220
|
+
export async function verifyReceipt(receipt, { keys, deliverable, ...options } = {}) {
|
|
221
|
+
let value = receipt;
|
|
222
|
+
if (typeof value === 'string') value = value.trimStart().startsWith('{') ? JSON.parse(value) : JSON.parse(await readFile(value, 'utf8'));
|
|
223
|
+
if (keys) {
|
|
224
|
+
const result = await verifyWithKeys(value, keys, deliverable);
|
|
225
|
+
return { valid: result.signatureValid && result.deliverableMatches !== false, ...result, trust: 'given' };
|
|
226
|
+
}
|
|
227
|
+
const hub = new Hub(options);
|
|
228
|
+
const result = await checkHostedReceipt(value, { base: hub.baseUrl, keys: await hub.keys(), text: deliverable });
|
|
229
|
+
return { valid: result.verified, ...result };
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** Writes a finished run's result and receipt next to each other. */
|
|
233
|
+
export async function saveResult(result, file) {
|
|
234
|
+
const path = resolve(file);
|
|
235
|
+
await mkdir(dirname(path), { recursive: true });
|
|
236
|
+
await writeFile(path, result.text);
|
|
237
|
+
const receipt = `${path.replace(/\.md$/, '')}.receipt.json`;
|
|
238
|
+
if (result.receipt) await writeFile(receipt, `${JSON.stringify(result.receipt, null, 2)}\n`);
|
|
239
|
+
return { file: path, receipt: result.receipt ? receipt : null };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
const one = (method) => (first, second) => {
|
|
243
|
+
const takesTarget = ['push', 'pull', 'publish', 'run'].includes(method);
|
|
244
|
+
const options = (takesTarget ? second : first) || {};
|
|
245
|
+
const hub = new Hub(options);
|
|
246
|
+
return takesTarget ? hub[method](first, options) : hub[method](options);
|
|
247
|
+
};
|
|
248
|
+
|
|
249
|
+
/** Logs in; see Hub#login. */
|
|
250
|
+
export const login = one('login');
|
|
251
|
+
/** Revokes and forgets the stored token; see Hub#logout. */
|
|
252
|
+
export const logout = one('logout');
|
|
253
|
+
/** Who the token acts for; see Hub#whoami. */
|
|
254
|
+
export const whoami = one('whoami');
|
|
255
|
+
/** Saves a folder or files privately; see Hub#push. */
|
|
256
|
+
export const push = one('push');
|
|
257
|
+
/** Downloads and checks a factory; see Hub#pull. */
|
|
258
|
+
export const pull = one('pull');
|
|
259
|
+
/** Publishes a factory; see Hub#publish. */
|
|
260
|
+
export const publish = one('publish');
|
|
261
|
+
/** Runs a factory on the hub; see Hub#run. */
|
|
262
|
+
export const run = one('run');
|
|
263
|
+
/** The account's runs; see Hub#runs. */
|
|
264
|
+
export const runs = one('runs');
|
|
265
|
+
|
|
266
|
+
export { credentialsPath };
|
package/spec/README.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# The factory format
|
|
2
|
+
|
|
3
|
+
| File | What it is |
|
|
4
|
+
|---|---|
|
|
5
|
+
| [`factory-format.md`](factory-format.md) | the specification, v1alpha1 |
|
|
6
|
+
| [`schema/factory.schema.json`](schema/factory.schema.json) | JSON Schema (2020-12) for `factory.yaml` |
|
|
7
|
+
| [`schema/flow.schema.json`](schema/flow.schema.json) | JSON Schema (2020-12) for `flow.yaml` |
|
|
8
|
+
| [`schema/factory.yaml.json`](schema/factory.yaml.json) | JSON Schema (draft-07) for a whole factory in one file, the [single-file form](factory-format.md#13-the-single-file-form) |
|
|
9
|
+
| [`skill-export.md`](skill-export.md) | how a factory becomes an Agent Skill folder |
|
|
10
|
+
| [`skill-export/`](skill-export) | the expected `SKILL.md` of every house factory |
|
|
11
|
+
| [`fixtures/`](fixtures) | good, bad, semantic, unimplemented and lenient factories that test the schemas against the engine |
|
|
12
|
+
| [`conformance/`](conformance) | what the reference engine gives for every fixture, house factory and edge case, for other implementations to match |
|
|
13
|
+
| [`test/`](test) | those tests |
|
|
14
|
+
| [`rfcs/`](rfcs) | proposals to change the format |
|
|
15
|
+
|
|
16
|
+
The reference implementation is the engine in
|
|
17
|
+
[`packages/engine`](../packages/engine). `npm test` checks the schemas, the
|
|
18
|
+
fixtures, the house factories and the skill export against it.
|
|
19
|
+
|
|
20
|
+
## Using the schemas in an editor
|
|
21
|
+
|
|
22
|
+
Editors that read the `yaml-language-server` comment validate a file as you
|
|
23
|
+
type:
|
|
24
|
+
|
|
25
|
+
```yaml
|
|
26
|
+
# yaml-language-server: $schema=https://raw.githubusercontent.com/Mindburn-Labs/factoryhub/main/spec/schema/flow.schema.json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
A single-file factory names `schema/factory.yaml.json` the same way. Setup
|
|
30
|
+
for VS Code, Neovim, Helix, Zed and JetBrains IDEs is in
|
|
31
|
+
[docs/editor-setup.md](../docs/editor-setup.md).
|
|
32
|
+
|
|
33
|
+
The schemas check one file at a time. Rules that span steps and files, such as
|
|
34
|
+
an agent file existing for every step, are in
|
|
35
|
+
[section 6 of the spec](factory-format.md#6-validity-and-runnability);
|
|
36
|
+
`factoryhub validate` checks those too.
|
|
37
|
+
|
|
38
|
+
## Changing the format
|
|
39
|
+
|
|
40
|
+
Read [`rfcs/README.md`](rfcs/README.md). Small fixes to wording go straight to
|
|
41
|
+
a pull request. A change to what a valid factory is, or to how a run behaves,
|
|
42
|
+
starts as an RFC.
|