steerdown 0.0.0-stage → 0.1.0

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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alper Halil
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,25 @@
1
- # Temporary Holding Version
1
+ # steerdown
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Typed reading paths for built HTML judged at build time
4
+
5
+ steerdown reads the built HTML of a site, whatever built it. It splits the pages into sections and suggests what to read next from each one, labelled by what the link is to the reader: read before this, read next, reference detail, or another way to the same goal. The judgments are made once at build time and committed as a file. The site build needs no API key, and readers send nothing anywhere.
6
+
7
+ **Status: Experimental.** Commands and file formats will change.
8
+
9
+ ## Install
10
+
11
+ steerdown needs Node 22 or later.
12
+
13
+ ```sh
14
+ npm install --save-dev steerdown
15
+ ```
16
+
17
+ ## Try it
18
+
19
+ ```sh
20
+ npx steerdown --help
21
+ ```
22
+
23
+ ## License
24
+
25
+ MIT
@@ -0,0 +1,9 @@
1
+ /** The values of every `id` attribute in an HTML page */
2
+ export function getHtmlIdAttrs(html) {
3
+ const ids = new Set();
4
+ for (const match of html.matchAll(/\sid\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
5
+ const value = match[1] ?? match[2] ?? "";
6
+ ids.add(value.replace(/&/g, "&"));
7
+ }
8
+ return ids;
9
+ }
package/dist/build.js ADDED
@@ -0,0 +1,266 @@
1
+ import { conceptFilePath, readConceptFile } from "./concepts.js";
2
+ import { ReportedError } from "./errors.js";
3
+ import { graphVersion, readGraph, relations, writeGraph } from "./graph.js";
4
+ import { inBatches, runPooled } from "./http.js";
5
+ import { askJev, officialEndpoint } from "./jev.js";
6
+ import { hash, judgedState, model, requestsInFlight, round } from "./judge.js";
7
+ import { findOrigins } from "./origins.js";
8
+ import { rankLinks } from "./rank.js";
9
+ import { planScores, scoreConcepts } from "./scores.js";
10
+ import { findHtmlPages, readSections } from "./sections.js";
11
+ import { cosine, tfidfVectors } from "./similarity.js";
12
+ export class BuildError extends ReportedError {
13
+ }
14
+ export const defaultMaxPairs = 100_000;
15
+ const candidatesPerRequest = 16;
16
+ const relationCriteria = {
17
+ prerequisite: "Explains something the reader needs to understand before `reading` makes sense.",
18
+ next_step: "A natural thing to read right after `reading`, continuing the same task or using what it explains.",
19
+ detail: "Reference detail for something `reading` mentions (flags, fields, formats, settings).",
20
+ alternative: "A different way to reach the same goal as `reading`.",
21
+ unrelated: "Shares words, but a reader of `reading` would gain nothing from it.",
22
+ };
23
+ function relationInstructions(candidateNumber) {
24
+ return `A reader has just finished the documentation section in \`reading\`. What is the section in \`candidates\` with n = ${candidateNumber} to that reader?`;
25
+ }
26
+ const questionSetHash = hash([model, relationInstructions(0), relationCriteria]);
27
+ /** The key a judgment is stored under: the hashes of the section read and the candidate. */
28
+ function pairKey(fromHash, toHash) {
29
+ return `${fromHash}>${toHash}`;
30
+ }
31
+ /** Candidates are numbered from 1 in a request, and each has its own question. */
32
+ function questionKey(candidateNumber) {
33
+ return `relation_${candidateNumber}`;
34
+ }
35
+ /** Judgments from an earlier graph, keyed by the hashes of both sections, when its questions match. */
36
+ function reusableJudgments(previous) {
37
+ const judgments = new Map();
38
+ if (previous === undefined || previous.questions !== questionSetHash) {
39
+ return judgments;
40
+ }
41
+ for (const [from, to, relation, probabilities, confidence] of previous.edges) {
42
+ const fromSection = previous.sections[from];
43
+ const toSection = previous.sections[to];
44
+ if (fromSection !== undefined && toSection !== undefined) {
45
+ judgments.set(pairKey(fromSection.hash, toSection.hash), {
46
+ relation,
47
+ probabilities,
48
+ confidence,
49
+ });
50
+ }
51
+ }
52
+ return judgments;
53
+ }
54
+ /** The indexes of the sections a section is judged against: every section on another page. */
55
+ function candidatesOf(sections, from) {
56
+ const candidates = [];
57
+ sections.forEach((candidate, to) => {
58
+ if (candidate.page !== sections[from].page) {
59
+ candidates.push(to);
60
+ }
61
+ });
62
+ return candidates;
63
+ }
64
+ /** Counts the ordered pairs of sections on different pages. */
65
+ function countPairs(sections) {
66
+ let pairs = 0;
67
+ sections.forEach((_, from) => {
68
+ pairs += candidatesOf(sections, from).length;
69
+ });
70
+ return pairs;
71
+ }
72
+ /**
73
+ * Plans the requests for every pair without a judgment. Each section's candidates are batched in
74
+ * order of word similarity to it, so each request compares a section with its nearest neighbours
75
+ * first. The judge's labels depend on which candidates share a request.
76
+ */
77
+ function planRequests(sections, isJudged) {
78
+ const vectors = tfidfVectors(sections.map((section) => section.text));
79
+ const jobs = [];
80
+ sections.forEach((_, from) => {
81
+ const missing = candidatesOf(sections, from)
82
+ .filter((to) => !isJudged(from, to))
83
+ .map((to) => ({ to, similarity: cosine(vectors[from], vectors[to]) }));
84
+ missing.sort((first, second) => second.similarity - first.similarity || first.to - second.to);
85
+ const targets = missing.map(({ to }) => to);
86
+ for (const batch of inBatches(targets, candidatesPerRequest)) {
87
+ jobs.push({ from, targets: batch });
88
+ }
89
+ });
90
+ return jobs;
91
+ }
92
+ /** Stops the build before judging when there are too many pairs or no API key to ask Jev. */
93
+ function checkJudgingAllowed(toJudge, toScore, options) {
94
+ if (toJudge > options.maxPairs) {
95
+ throw new BuildError(`${toJudge} section pairs need judging, more than the limit of ${options.maxPairs}. Raise it with --max-pairs.`);
96
+ }
97
+ const keyNeeded = toJudge + toScore > 0 &&
98
+ options.client.endpoint === officialEndpoint &&
99
+ options.client.apiKey === undefined;
100
+ if (keyNeeded) {
101
+ throw new BuildError(`${toJudge} section pairs need judging and ${toScore} concept scores need scoring. Set TYPESAFE_API_KEY to ask Jev.`);
102
+ }
103
+ }
104
+ /** The System One request body that asks how each target relates to the section being read. */
105
+ function relationRequest(job, sections) {
106
+ const questions = {};
107
+ job.targets.forEach((_, index) => {
108
+ const candidateNumber = index + 1;
109
+ questions[questionKey(candidateNumber)] = {
110
+ type: "choice",
111
+ instructions: relationInstructions(candidateNumber),
112
+ criteria: relationCriteria,
113
+ };
114
+ });
115
+ const state = {
116
+ reading: judgedState(sections[job.from]),
117
+ candidates: job.targets.map((to, index) => ({ n: index + 1, ...judgedState(sections[to]) })),
118
+ };
119
+ return { model, state, questions };
120
+ }
121
+ /** Stores the judgment for each target the response answered and returns how many it answered. */
122
+ function recordAnswers({ job, response, hashes, judgments, }) {
123
+ let answered = 0;
124
+ job.targets.forEach((to, index) => {
125
+ const answer = response.answers[questionKey(index + 1)];
126
+ if (answer === undefined) {
127
+ return;
128
+ }
129
+ judgments.set(pairKey(hashes[job.from], hashes[to]), {
130
+ relation: answer.choice,
131
+ probabilities: relations.map((relation) => round(answer.probabilities[relation] ?? 0)),
132
+ confidence: round(answer.confidence),
133
+ });
134
+ answered++;
135
+ });
136
+ return answered;
137
+ }
138
+ /** Sends the planned requests and stores their judgments, stopping at the first failed request. */
139
+ async function judgePairs({ jobs, sections, hashes, judgments, client, previousModel, }) {
140
+ const progress = {
141
+ model: previousModel,
142
+ requests: 0,
143
+ inputTokens: 0,
144
+ judged: 0,
145
+ failure: undefined,
146
+ };
147
+ try {
148
+ await runPooled(jobs, requestsInFlight, async (job) => {
149
+ const response = await askJev(client, relationRequest(job, sections));
150
+ progress.requests++;
151
+ progress.inputTokens += response.usage.input_tokens;
152
+ progress.model = response.model;
153
+ progress.judged += recordAnswers({ job, response, hashes, judgments });
154
+ });
155
+ }
156
+ catch (error) {
157
+ progress.failure = error;
158
+ }
159
+ return progress;
160
+ }
161
+ /** The judged pairs as graph edges, in order of the section read and then the candidate. */
162
+ function collectEdges(sections, hashes, judgments) {
163
+ const edges = [];
164
+ sections.forEach((_, from) => {
165
+ for (const to of candidatesOf(sections, from)) {
166
+ const judgment = judgments.get(pairKey(hashes[from], hashes[to]));
167
+ if (judgment !== undefined) {
168
+ edges.push([from, to, judgment.relation, judgment.probabilities, judgment.confidence]);
169
+ }
170
+ }
171
+ });
172
+ return edges;
173
+ }
174
+ /** Throws the error that stopped judging or scoring, saying how much was written before it. */
175
+ function throwFailure({ failure, edges, pairs, scores, outPath, }) {
176
+ const message = failure instanceof Error ? failure.message : String(failure);
177
+ const { fields, report } = scores;
178
+ const scoresWritten = report === undefined ? "" : ` and ${fields.scores?.length} of ${report.total} scores`;
179
+ throw new BuildError(`${message}\nWrote the ${edges.length} of ${pairs} pairs${scoresWritten} done so far to ${outPath}. Run the build again to do the rest.`);
180
+ }
181
+ /**
182
+ * Splits the pages of a built site into sections, judges every pair of sections on different
183
+ * pages with Jev, scores every section against the concept file's concepts when present, finds
184
+ * each showable link's origin sentence when there is an embedding endpoint,
185
+ * and writes the graph file.
186
+ *
187
+ * Pairs and scores whose text is unchanged since the last graph file are reused,
188
+ * not asked again. When a request fails, the results so far are written
189
+ * before the error is thrown, so the next run continues from there.
190
+ */
191
+ export async function build(options) {
192
+ const concepts = readConceptFile(conceptFilePath(options.outPath));
193
+ const pages = findHtmlPages(options.directory, options.excluded);
194
+ const { sections, skipped, idlessHeadings } = readSections(options.directory, pages);
195
+ const hashes = sections.map((section) => hash(judgedState(section)));
196
+ const previous = readGraph(options.outPath);
197
+ const judgments = reusableJudgments(previous);
198
+ const pairs = countPairs(sections);
199
+ const jobs = planRequests(sections, (from, to) => judgments.has(pairKey(hashes[from], hashes[to])));
200
+ const toJudge = jobs.reduce((count, job) => count + job.targets.length, 0);
201
+ const scorePlan = concepts && planScores(concepts, hashes, previous);
202
+ checkJudgingAllowed(toJudge, scorePlan?.toScore ?? 0, options);
203
+ const progress = await judgePairs({
204
+ jobs,
205
+ sections,
206
+ hashes,
207
+ judgments,
208
+ client: options.client,
209
+ previousModel: previous?.model ?? model,
210
+ });
211
+ const scores = await scoreConcepts({
212
+ plan: scorePlan,
213
+ judgingFailed: progress.failure !== undefined,
214
+ sections,
215
+ hashes,
216
+ client: options.client,
217
+ });
218
+ const graphSections = sections.map((section, index) => ({
219
+ id: section.id,
220
+ page: section.page,
221
+ pageTitle: section.pageTitle,
222
+ heading: section.heading,
223
+ hash: hashes[index],
224
+ }));
225
+ const edges = collectEdges(sections, hashes, judgments);
226
+ const judgingFailure = progress.failure ?? scores.progress.failure;
227
+ const origins = await findOrigins({
228
+ client: judgingFailure === undefined ? options.embedding : undefined,
229
+ sections,
230
+ graphSections,
231
+ edges,
232
+ scopes: options.scopes,
233
+ graphPath: options.outPath,
234
+ minSimilarity: options.minSimilarity,
235
+ });
236
+ writeGraph(options.outPath, {
237
+ version: graphVersion,
238
+ model: progress.model,
239
+ questions: questionSetHash,
240
+ relations,
241
+ scopes: options.scopes,
242
+ sections: graphSections,
243
+ skipped,
244
+ edges,
245
+ links: rankLinks(graphSections, edges, options.scopes),
246
+ ...scores.fields,
247
+ ...origins.fields,
248
+ });
249
+ const failure = judgingFailure ?? origins.failure;
250
+ if (failure !== undefined) {
251
+ throwFailure({ failure, edges, pairs, scores, outPath: options.outPath });
252
+ }
253
+ return {
254
+ pages: pages.length,
255
+ sections: sections.length,
256
+ skipped,
257
+ idlessHeadings,
258
+ pairs,
259
+ reused: pairs - toJudge,
260
+ judged: progress.judged,
261
+ requests: progress.requests + scores.progress.requests,
262
+ inputTokens: progress.inputTokens + scores.progress.inputTokens,
263
+ scores: scores.report,
264
+ origins: origins.report,
265
+ };
266
+ }
package/dist/cli.js ADDED
@@ -0,0 +1,319 @@
1
+ #!/usr/bin/env node
2
+ import { existsSync, statSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { parseArgs } from "node:util";
5
+ import { build, BuildError, defaultMaxPairs } from "./build.js";
6
+ import { conceptInput, proposeConcepts } from "./concepts.js";
7
+ import { emit } from "./emit.js";
8
+ import { emitFolder } from "./urls.js";
9
+ import { ReportedError } from "./errors.js";
10
+ import { officialEndpoint } from "./jev.js";
11
+ import { installSkill } from "./skill.js";
12
+ const defaultOutPath = "steerdown.graph.json";
13
+ const helpText = `steerdown: typed reading paths for built HTML judged at build time
14
+
15
+ Usage: steerdown <command> [options]
16
+
17
+ Commands:
18
+ build <dir> Split the HTML pages of the built site at <dir> into
19
+ sections, judge how sections on different pages relate,
20
+ and write the graph file. With a steerdown.concepts.json
21
+ next to the graph file, also score every section against
22
+ its concepts.
23
+ With an embedding endpoint, also find the sentence
24
+ each suggested link grows out of.
25
+ concepts input Print what an agent needs to propose concepts, as JSON.
26
+ concepts propose <file> Check the concepts proposed in <file>, a JSON array, and
27
+ add them to steerdown.proposals.json next to the graph
28
+ file. Nothing is written when one has a problem.
29
+ emit --html <dir> Write one file per page into the built site at <dir>,
30
+ under ${emitFolder}/, holding the suggested links a
31
+ page's browser script shows. Reads the graph file and
32
+ makes no requests.
33
+ skill install Install the steerdown-concepts agent skill into this
34
+ project with the skills CLI (npx --yes skills add).
35
+
36
+ Build options:
37
+ --out <file> Graph file to write. Pairs and scores whose text is unchanged
38
+ since it was last written are reused.
39
+ Default: ${defaultOutPath}
40
+ --exclude <path> Leave out an HTML file or folder, relative to <dir>.
41
+ Repeat for more.
42
+ --scope <path> Mark an HTML file or folder, relative to <dir>, as
43
+ covering its own product. Sections in two different scopes
44
+ are suggested to each other only as alternatives.
45
+ Repeat for more.
46
+ --max-pairs <n> Stop before judging more than <n> new pairs.
47
+ Default: ${defaultMaxPairs}
48
+ --min-similarity <n>
49
+ Give a link no origin sentence when its nearest sentence
50
+ has a cosine similarity below <n>, from -1 to 1. Scales
51
+ differ between embedding models. Default: no minimum.
52
+
53
+ Concepts and emit options:
54
+ --graph <file> Graph file to read. Default: ${defaultOutPath}
55
+
56
+ Environment:
57
+ TYPESAFE_API_KEY Jev API key, needed when pairs need judging or sections
58
+ need scoring.
59
+ JEV_URL System One endpoint. Default: ${officialEndpoint}
60
+ STEERDOWN_EMBEDDING_URL
61
+ Base URL of an OpenAI-compatible embeddings endpoint, such
62
+ as https://api.openai.com/v1. Vectors are cached in
63
+ steerdown.embeddings.json next to the graph file. Leave
64
+ the cache out of version control.
65
+ STEERDOWN_EMBEDDING_MODEL
66
+ Embedding model to ask. Needed with the URL.
67
+ STEERDOWN_EMBEDDING_KEY
68
+ API key for the embeddings endpoint, if it needs one.
69
+
70
+ Options:
71
+ -h, --help Show this help.
72
+ `;
73
+ /** The command line itself is wrong. Printed with a pointer to the help. */
74
+ class UsageError extends ReportedError {
75
+ }
76
+ /** The options each command takes, besides --help. */
77
+ const commandOptions = {
78
+ build: ["out", "exclude", "scope", "max-pairs", "min-similarity"],
79
+ concepts: ["graph"],
80
+ emit: ["html", "graph"],
81
+ skill: [],
82
+ };
83
+ function formatCount(value) {
84
+ return value.toLocaleString("en-US");
85
+ }
86
+ function isDirectory(path) {
87
+ return existsSync(path) && statSync(path).isDirectory();
88
+ }
89
+ /** Reads `--max-pairs`, a whole number that defaults to the build's own limit. */
90
+ function parseMaxPairs(value) {
91
+ const maxPairs = value === undefined ? defaultMaxPairs : Number(value);
92
+ if (!Number.isSafeInteger(maxPairs) || maxPairs < 0) {
93
+ throw new UsageError(`--max-pairs must be a whole number, got '${value}'`);
94
+ }
95
+ return maxPairs;
96
+ }
97
+ /** Reads `--min-similarity`, a cosine similarity from -1 to 1, or undefined when not given. */
98
+ function parseMinSimilarity(value) {
99
+ if (value === undefined) {
100
+ return undefined;
101
+ }
102
+ const minSimilarity = Number(value);
103
+ const isCosine = value.trim() !== "" && Math.abs(minSimilarity) <= 1;
104
+ if (!isCosine) {
105
+ throw new UsageError(`--min-similarity must be a number from -1 to 1, got '${value}'`);
106
+ }
107
+ return minSimilarity;
108
+ }
109
+ /** Checks the build command's arguments and turns them and the environment into build options. */
110
+ function buildOptions(positionals, values) {
111
+ const [directory, ...extra] = positionals;
112
+ if (directory === undefined) {
113
+ throw new UsageError("build needs the directory of a built site");
114
+ }
115
+ if (extra.length > 0) {
116
+ throw new UsageError(`unexpected argument '${extra[0]}'`);
117
+ }
118
+ if (!isDirectory(directory)) {
119
+ throw new BuildError(`'${directory}' is not a directory`);
120
+ }
121
+ const maxPairs = parseMaxPairs(values["max-pairs"]);
122
+ const minSimilarity = parseMinSimilarity(values["min-similarity"]);
123
+ return {
124
+ directory,
125
+ outPath: values.out ?? defaultOutPath,
126
+ excluded: values.exclude ?? [],
127
+ scopes: values.scope ?? [],
128
+ maxPairs,
129
+ client: clientFromEnvironment(),
130
+ embedding: embeddingFromEnvironment(),
131
+ minSimilarity,
132
+ };
133
+ }
134
+ /** The Jev endpoint and key from the environment. An empty variable counts as unset. */
135
+ function clientFromEnvironment() {
136
+ return {
137
+ endpoint: process.env.JEV_URL || officialEndpoint,
138
+ apiKey: process.env.TYPESAFE_API_KEY || undefined,
139
+ };
140
+ }
141
+ /** The embeddings endpoint from the environment, or undefined when neither URL nor model is set. */
142
+ function embeddingFromEnvironment() {
143
+ const url = process.env.STEERDOWN_EMBEDDING_URL || undefined;
144
+ const model = process.env.STEERDOWN_EMBEDDING_MODEL || undefined;
145
+ if (url === undefined && model === undefined) {
146
+ return undefined;
147
+ }
148
+ if (url === undefined || model === undefined) {
149
+ const missing = url === undefined ? "STEERDOWN_EMBEDDING_URL" : "STEERDOWN_EMBEDDING_MODEL";
150
+ throw new BuildError(`${missing} is not set. Set both the embedding URL and model, or neither.`);
151
+ }
152
+ return { url, model, apiKey: process.env.STEERDOWN_EMBEDDING_KEY || undefined };
153
+ }
154
+ /** The origin sentence line of a build's summary. */
155
+ function formatOrigins(report) {
156
+ const { origins } = report;
157
+ if (origins === undefined) {
158
+ return "Origin sentences: none. Set STEERDOWN_EMBEDDING_URL and STEERDOWN_EMBEDDING_MODEL to find them.";
159
+ }
160
+ const below = origins.belowMinimum > 0 ? `, ${formatCount(origins.belowMinimum)} below --min-similarity` : "";
161
+ return `Origin sentences: ${formatCount(origins.links)} links${below} (${formatCount(origins.embedded)} texts embedded in ${formatCount(origins.requests)} requests)`;
162
+ }
163
+ /** The score lines of a build's summary, empty when it read no concept file. */
164
+ function formatScores(report) {
165
+ const { scores } = report;
166
+ if (scores === undefined) {
167
+ return [];
168
+ }
169
+ return [
170
+ `Scores: ${formatCount(scores.total)} (${formatCount(scores.reused)} reused, ${formatCount(scores.scored)} scored)`,
171
+ `Over-broad concepts: ${formatCount(scores.overBroad.length)}`,
172
+ ...scores.overBroad.map((concept) => ` ${concept.id}: covers ${formatCount(concept.sections)} of ${formatCount(report.sections)} sections`),
173
+ ];
174
+ }
175
+ /** The summary a finished build prints. */
176
+ function formatReport(report, outPath) {
177
+ const lines = [
178
+ `Pages: ${formatCount(report.pages)}`,
179
+ `Sections: ${formatCount(report.sections)}`,
180
+ `Skipped sections: ${formatCount(report.skipped.length)}`,
181
+ ...report.skipped.map((section) => ` ${section.id}: ${section.reason}`),
182
+ `Headings without an id, kept in the section before: ${formatCount(report.idlessHeadings.length)}`,
183
+ ...report.idlessHeadings.map(({ page, heading }) => ` ${page}: ${heading}`),
184
+ `Pairs: ${formatCount(report.pairs)} (${formatCount(report.reused)} reused, ${formatCount(report.judged)} judged)`,
185
+ ...formatScores(report),
186
+ formatOrigins(report),
187
+ `Requests: ${formatCount(report.requests)}, input tokens: ${formatCount(report.inputTokens)}`,
188
+ `Wrote ${outPath}`,
189
+ ];
190
+ return `${lines.join("\n")}\n`;
191
+ }
192
+ async function runBuild(positionals, values) {
193
+ const options = buildOptions(positionals, values);
194
+ const report = await build(options);
195
+ process.stdout.write(formatReport(report, options.outPath));
196
+ }
197
+ /** The summary a finished emit prints. */
198
+ function formatEmitReport(report, htmlDirectory) {
199
+ const lines = [
200
+ `Pages written: ${formatCount(report.written)}`,
201
+ `Pages left out: ${formatCount(report.leftOut.length)}`,
202
+ ...report.leftOut.map((page) => ` ${page.page}: ${page.reason}`),
203
+ `Links dropped: ${formatCount(report.linksWithoutPage)} to a page with no built HTML, ${formatCount(report.linksWithoutId)} to a heading with no matching id`,
204
+ `Wrote ${formatCount(report.bytes)} bytes to ${join(htmlDirectory, emitFolder)}`,
205
+ ];
206
+ return `${lines.join("\n")}\n`;
207
+ }
208
+ function runEmit(positionals, values) {
209
+ rejectExtraArguments(positionals);
210
+ const htmlDirectory = values.html;
211
+ if (htmlDirectory === undefined) {
212
+ throw new UsageError("emit needs --html, the built site");
213
+ }
214
+ if (!isDirectory(htmlDirectory)) {
215
+ throw new BuildError(`'${htmlDirectory}' is not a directory`);
216
+ }
217
+ const report = emit({ graphPath: values.graph ?? defaultOutPath, htmlDirectory });
218
+ process.stdout.write(formatEmitReport(report, htmlDirectory));
219
+ }
220
+ function rejectExtraArguments(extra) {
221
+ if (extra.length > 0) {
222
+ throw new UsageError(`unexpected argument '${extra[0]}'`);
223
+ }
224
+ }
225
+ function runConcepts(positionals, graph) {
226
+ const [action, ...args] = positionals;
227
+ const graphPath = graph ?? defaultOutPath;
228
+ if (action === "input") {
229
+ rejectExtraArguments(args);
230
+ process.stdout.write(`${JSON.stringify(conceptInput(graphPath), null, 2)}\n`);
231
+ return;
232
+ }
233
+ if (action === "propose") {
234
+ const [file, ...extra] = args;
235
+ if (file === undefined) {
236
+ throw new UsageError("concepts propose needs a file of proposed concepts");
237
+ }
238
+ rejectExtraArguments(extra);
239
+ const { added, proposalPath } = proposeConcepts(graphPath, file);
240
+ process.stdout.write(`Added ${formatCount(added)} proposed concepts to ${proposalPath}\n`);
241
+ return;
242
+ }
243
+ throw new UsageError(action === undefined
244
+ ? "concepts needs input or propose"
245
+ : `unknown command 'concepts ${action}'`);
246
+ }
247
+ async function runSkill(positionals) {
248
+ const [action, ...extra] = positionals;
249
+ if (action !== "install") {
250
+ throw new UsageError(action === undefined ? "skill needs install" : `unknown command 'skill ${action}'`);
251
+ }
252
+ rejectExtraArguments(extra);
253
+ await installSkill();
254
+ }
255
+ /** Rejects options the command does not take. */
256
+ function checkOptions(command, values) {
257
+ const allowed = commandOptions[command];
258
+ for (const name of Object.keys(values)) {
259
+ if (name !== "help" && !allowed.includes(name)) {
260
+ throw new UsageError(`${command} does not take --${name}`);
261
+ }
262
+ }
263
+ }
264
+ function parse(args) {
265
+ try {
266
+ return parseArgs({
267
+ args,
268
+ options: {
269
+ help: { type: "boolean", short: "h" },
270
+ out: { type: "string" },
271
+ html: { type: "string" },
272
+ exclude: { type: "string", multiple: true },
273
+ scope: { type: "string", multiple: true },
274
+ "max-pairs": { type: "string" },
275
+ "min-similarity": { type: "string" },
276
+ graph: { type: "string" },
277
+ },
278
+ allowPositionals: true,
279
+ });
280
+ }
281
+ catch (error) {
282
+ throw new UsageError(error.message);
283
+ }
284
+ }
285
+ async function run(args) {
286
+ const { values, positionals } = parse(args);
287
+ const [command, ...rest] = positionals;
288
+ if (values.help || command === undefined) {
289
+ process.stdout.write(helpText);
290
+ return;
291
+ }
292
+ if (commandOptions[command] === undefined) {
293
+ throw new UsageError(`unknown command '${command}'`);
294
+ }
295
+ checkOptions(command, values);
296
+ if (command === "build") {
297
+ await runBuild(rest, values);
298
+ }
299
+ else if (command === "concepts") {
300
+ runConcepts(rest, values.graph);
301
+ }
302
+ else if (command === "emit") {
303
+ runEmit(rest, values);
304
+ }
305
+ else {
306
+ await runSkill(rest);
307
+ }
308
+ }
309
+ try {
310
+ await run(process.argv.slice(2));
311
+ }
312
+ catch (error) {
313
+ if (!(error instanceof ReportedError)) {
314
+ throw error;
315
+ }
316
+ const helpPointer = error instanceof UsageError ? "\nRun 'steerdown --help' for usage." : "";
317
+ process.stderr.write(`steerdown: ${error.message}${helpPointer}\n`);
318
+ process.exitCode = error.exitCode;
319
+ }