@orkestrel/scaffold 0.0.134 → 0.0.135

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.
Files changed (40) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
  3. package/dist/bin/main.js +253 -35
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
  8. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  10. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
  11. package/dist/host/claude/agents/orkestrel.md +14 -14
  12. package/dist/host/claude/rules/architecture.md +1 -1
  13. package/dist/host/claude/rules/patterns.md +2 -0
  14. package/dist/host/claude/rules/workspace.md +64 -63
  15. package/dist/host/configs/helpers.ts +88 -67
  16. package/dist/host/dotfiles/oxlintrc.json +1 -57
  17. package/dist/host/guides/agent.md +989 -395
  18. package/dist/host/guides/database.md +357 -342
  19. package/dist/host/guides/middleware.md +5 -5
  20. package/dist/host/guides/ollama.md +41 -42
  21. package/dist/host/guides/scaffold.md +177 -105
  22. package/dist/host/guides/study.md +12 -12
  23. package/dist/host/guides/test.md +158 -46
  24. package/dist/host/guides/toolbox.md +127 -81
  25. package/dist/host/guides/workspace.md +21 -14
  26. package/dist/host/manifest.json +23 -23
  27. package/dist/host/tests/config.test.ts +166 -112
  28. package/dist/src/core/index.cjs +491 -195
  29. package/dist/src/core/index.cjs.map +1 -1
  30. package/dist/src/core/index.d.cts +217 -24
  31. package/dist/src/core/index.d.ts +217 -24
  32. package/dist/src/core/index.js +482 -193
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +18 -8
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +4 -3
  37. package/dist/src/server/index.d.ts +4 -3
  38. package/dist/src/server/index.js +19 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +2 -2
@@ -1108,6 +1108,234 @@ export function runFormat(runner) {
1108
1108
  version,
1109
1109
  };
1110
1110
  }
1111
+ /**
1112
+ * Parses a whole text as one JSON object or a list of JSON objects.
1113
+ *
1114
+ * @param text - A JSON document, such as `npm view NAME@RANGE FIELD --json` output, which prints one
1115
+ * record for one match and a list for several.
1116
+ * @returns Each object the document carries, or none when the text is not JSON.
1117
+ */
1118
+ export function parseJsonRecords(text) {
1119
+ try {
1120
+ const parsed = JSON.parse(text);
1121
+ return (Array.isArray(parsed) ? parsed : [parsed])
1122
+ .filter(isRecord)
1123
+ .map((entry) => Object.fromEntries(Object.entries(entry)));
1124
+ }
1125
+ catch {
1126
+ return [];
1127
+ }
1128
+ }
1129
+ /**
1130
+ * Parses the major, minor, and patch numbers of a plain `major.minor.patch` version.
1131
+ *
1132
+ * @param text - The version text.
1133
+ * @returns The three numbers, or undefined when the text carries a prefix, a prerelease, or any
1134
+ * other form.
1135
+ * @example
1136
+ * ```ts
1137
+ * parseVersion('8.3.8') // [8, 3, 8]
1138
+ * parseVersion('8.3.8-beta.1') // undefined
1139
+ * ```
1140
+ */
1141
+ export function parseVersion(text) {
1142
+ const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(text);
1143
+ if (match === null)
1144
+ return undefined;
1145
+ return [Number(match[1]), Number(match[2]), Number(match[3])];
1146
+ }
1147
+ /**
1148
+ * Compares two plain versions by their major, minor, and patch numbers.
1149
+ *
1150
+ * @param left - The version ordered first when it compares lower.
1151
+ * @param right - The version it is compared with.
1152
+ * @returns A negative number when `left` is lower, zero when equal, and a positive number when higher.
1153
+ * @example
1154
+ * ```ts
1155
+ * compareVersions([0, 0, 23], [0, 0, 24]) // -1
1156
+ * ```
1157
+ */
1158
+ export function compareVersions(left, right) {
1159
+ return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
1160
+ }
1161
+ /**
1162
+ * Parses a declared range as the half-open version intervals its `||` arms admit.
1163
+ *
1164
+ * @remarks
1165
+ * An arm is an exact `major.minor.patch` version, a caret, or a tilde over one. A caret admits up to
1166
+ * the next major, the next minor under major 0, and the next patch under `0.0`; a tilde admits up to
1167
+ * the next minor. Any other form, an empty arm included, makes the whole range unreadable.
1168
+ *
1169
+ * @param range - The declared range.
1170
+ * @returns One interval per arm, with an inclusive `floor` and an exclusive `ceiling`, or undefined
1171
+ * when an arm is outside those forms.
1172
+ * @example
1173
+ * ```ts
1174
+ * parseRange('^0.0.23') // [{ floor: [0, 0, 23], ceiling: [0, 0, 24] }]
1175
+ * parseRange('>=8') // undefined
1176
+ * ```
1177
+ */
1178
+ export function parseRange(range) {
1179
+ const arms = range.trim().split(/\s*\|\|\s*/u);
1180
+ const parsed = arms.flatMap((arm) => {
1181
+ const match = /^([\^~]?)(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u.exec(arm);
1182
+ if (match === null)
1183
+ return [];
1184
+ const major = Number(match[2]);
1185
+ const minor = Number(match[3]);
1186
+ const patch = Number(match[4]);
1187
+ const ceiling = match[1] === '~'
1188
+ ? [major, minor + 1, 0]
1189
+ : match[1] === ''
1190
+ ? [major, minor, patch + 1]
1191
+ : major > 0
1192
+ ? [major + 1, 0, 0]
1193
+ : minor > 0
1194
+ ? [0, minor + 1, 0]
1195
+ : [0, 0, patch + 1];
1196
+ return [{ floor: [major, minor, patch], ceiling }];
1197
+ });
1198
+ return parsed.length === arms.length ? parsed : undefined;
1199
+ }
1200
+ /**
1201
+ * Computes whether a declared range admits a plain version.
1202
+ *
1203
+ * @param range - The declared range, in a form {@link parseRange} reads.
1204
+ * @param version - The plain version.
1205
+ * @returns True if an arm admits the version, false if none does, and undefined when the range or
1206
+ * the version is unreadable.
1207
+ * @example
1208
+ * ```ts
1209
+ * computeSatisfaction('^8.3.7', '8.3.8') // true
1210
+ * computeSatisfaction('^0.0.23', '0.0.24') // false
1211
+ * computeSatisfaction('*', '1.0.0') // undefined
1212
+ * ```
1213
+ */
1214
+ export function computeSatisfaction(range, version) {
1215
+ const arms = parseRange(range);
1216
+ const parsed = parseVersion(version);
1217
+ if (arms === undefined || parsed === undefined)
1218
+ return undefined;
1219
+ return arms.some((arm) => compareVersions(arm.floor, parsed) <= 0 && compareVersions(parsed, arm.ceiling) < 0);
1220
+ }
1221
+ /**
1222
+ * Raises one declared peer range whose floor fails the served release, and words the decision.
1223
+ *
1224
+ * @remarks
1225
+ * A range the served version satisfies stays as declared. A failing range moves per
1226
+ * {@link moveRange}: the one arm in the release's major becomes the caret of the release. A range
1227
+ * that is unreadable, carries no arm or several arms in that major, or whose arm in that major opens
1228
+ * above the release stays as declared, and the message names why. A reading that names the peer and
1229
+ * carries no release keeps it as `no eligible release`; no reading keeps it as `no release reading`.
1230
+ *
1231
+ * @param name - The peer's package name.
1232
+ * @param range - The declared peer range.
1233
+ * @param reading - The release reading that names the peer, or undefined when none does.
1234
+ * @returns The range after the decision and the rewrite row message: `peer NAME OLD -> NEW` when it
1235
+ * rose, `peer NAME OLD kept, REASON` otherwise.
1236
+ * @example
1237
+ * ```ts
1238
+ * raisePeer('@orkestrel/database', '^0.0.23', { name: '@orkestrel/database', range: '*', latest: '0.0.24' })
1239
+ * // { range: '^0.0.24', message: 'peer @orkestrel/database ^0.0.23 -> ^0.0.24', raised: true }
1240
+ * ```
1241
+ */
1242
+ export function raisePeer(name, range, reading) {
1243
+ const arms = parseRange(range);
1244
+ const latest = reading?.latest;
1245
+ const version = latest === undefined ? undefined : parseVersion(latest);
1246
+ const matched = version === undefined ? [] : (arms ?? []).filter((entry) => entry.floor[0] === version[0]);
1247
+ const reason = arms === undefined
1248
+ ? 'unreadable range'
1249
+ : reading === undefined
1250
+ ? 'no release reading'
1251
+ : latest === undefined
1252
+ ? 'no eligible release'
1253
+ : version === undefined
1254
+ ? `unreadable release ${latest}`
1255
+ : computeSatisfaction(range, latest) === true
1256
+ ? `admits ${latest}`
1257
+ : matched.length === 0
1258
+ ? `no arm in the major of ${latest}`
1259
+ : matched.length > 1
1260
+ ? `several arms in the major of ${latest}`
1261
+ : matched.some((arm) => compareVersions(arm.floor, version) > 0)
1262
+ ? `its floor is above ${latest}`
1263
+ : undefined;
1264
+ if (reason !== undefined || latest === undefined)
1265
+ return { range, message: `peer ${name} ${range} kept, ${String(reason)}`, raised: false };
1266
+ const next = String(moveRange(range, latest));
1267
+ return { range: next, message: `peer ${name} ${range} -> ${next}`, raised: true };
1268
+ }
1269
+ /**
1270
+ * Collects the registry lookup each peer-only dependency needs for its release reading.
1271
+ *
1272
+ * @remarks
1273
+ * A peer a release reading already names, such as one also declared under `devDependencies`, takes
1274
+ * that reading. A peer whose range {@link parseRange} cannot read needs no reading. A fleet package
1275
+ * is looked up with `*`, and a foreign tool with a caret over its declared major, or with the
1276
+ * declared range when its arms span several majors, as the audit bounds a dependency. A range bound
1277
+ * by itself admits every release its lookup serves, so such a peer never rises.
1278
+ *
1279
+ * @param manifest - The manifest record.
1280
+ * @param releases - The audit's release readings.
1281
+ * @returns One lookup per peer-only dependency, in declaration order.
1282
+ * @example
1283
+ * ```ts
1284
+ * collectPeerLookups({ peerDependencies: { vite: '^8.3.7' } }, [])
1285
+ * // [{ name: 'vite', bound: '^8' }]
1286
+ * ```
1287
+ */
1288
+ export function collectPeerLookups(manifest, releases) {
1289
+ const named = new Set(releases.map((release) => release.name));
1290
+ const block = manifest.peerDependencies;
1291
+ if (typeof block !== 'object' || block === null)
1292
+ return [];
1293
+ return Object.entries(block).flatMap(([name, range]) => {
1294
+ if (typeof range !== 'string' || named.has(name))
1295
+ return [];
1296
+ const majors = [...new Set(parseRange(range)?.map((arm) => arm.floor[0]))];
1297
+ if (majors.length === 0)
1298
+ return [];
1299
+ const bound = name.startsWith('@orkestrel/')
1300
+ ? '*'
1301
+ : majors.length === 1
1302
+ ? `^${String(majors[0])}`
1303
+ : range;
1304
+ return [{ name, bound }];
1305
+ });
1306
+ }
1307
+ /**
1308
+ * Reads the release a registry lookup serves out of the output of
1309
+ * `npm view NAME@BOUND version deprecated dist-tags.latest --json`.
1310
+ *
1311
+ * @remarks
1312
+ * The reading skips a deprecated version, a version outside the plain `major.minor.patch` form, and
1313
+ * a version above `latest` when the bound is `*` or the caret of `latest`'s major, then takes the
1314
+ * highest, as the audit's lookup does.
1315
+ *
1316
+ * @param text - The command's standard output.
1317
+ * @param bound - The lookup bound.
1318
+ * @returns The served version, or undefined when no version is eligible or the output is unreadable.
1319
+ * @example
1320
+ * ```ts
1321
+ * readServedVersion('{"version":"0.0.24","dist-tags.latest":"0.0.24"}', '*') // '0.0.24'
1322
+ * ```
1323
+ */
1324
+ export function readServedVersion(text, bound) {
1325
+ const eligible = parseJsonRecords(text).flatMap((entry) => {
1326
+ const version = readString(entry, 'version') ?? '';
1327
+ const plain = parseVersion(version);
1328
+ const deprecated = readString(entry, 'deprecated') ?? '';
1329
+ const latest = parseVersion(readString(entry, 'dist-tags.latest') ?? '');
1330
+ if (plain === undefined || deprecated.length > 0)
1331
+ return [];
1332
+ const capped = latest !== undefined && (bound === '*' || bound === `^${String(latest[0])}`)
1333
+ ? compareVersions(plain, latest) <= 0
1334
+ : true;
1335
+ return capped ? [{ version, plain }] : [];
1336
+ });
1337
+ return eligible.toSorted((left, right) => compareVersions(right.plain, left.plain))[0]?.version;
1338
+ }
1111
1339
  /**
1112
1340
  * Moves one declared range to the registry caret of a release, keeping every other major a
1113
1341
  * disjunctive range admits.
@@ -1164,24 +1392,28 @@ export function computeRanges(ranges, releases) {
1164
1392
  }, { ranges, moved: [] });
1165
1393
  }
1166
1394
  /**
1167
- * Writes the re-pinned ranges into the target's manifest, keeping every peer range at its floor.
1395
+ * Writes the re-pinned ranges into the target's manifest, raising each peer range whose floor fails
1396
+ * its release.
1168
1397
  *
1169
1398
  * @remarks
1170
- * A `peerDependencies` range moves only when its floor fails the release, and no reading the visit
1171
- * takes names a floor the release needs, so every peer the registry moved past stays as declared and
1172
- * is reported as kept.
1399
+ * A `dependencies` or `devDependencies` range moves per {@link computeRanges} over the audit's
1400
+ * readings alone. A `peerDependencies` range takes the last audit reading that names it with a
1401
+ * release, else its peer-only reading, and moves per {@link raisePeer}: it rises to the caret of the
1402
+ * served version only when the declared range excludes that version, and otherwise stays as
1403
+ * declared. Every raised peer joins the moved list and every other peer is reported as kept.
1173
1404
  *
1174
1405
  * @param target - The target directory.
1175
1406
  * @param releases - The audit's release readings.
1407
+ * @param peers - The peer-only readings, which move `peerDependencies` ranges alone. Default: none.
1176
1408
  * @returns One message per range moved and one per peer range kept; the manifest is rewritten only
1177
1409
  * when a range moved.
1178
1410
  * @example
1179
1411
  * ```ts
1180
1412
  * writeRanges('.', [{ name: 'vite', range: '^8', latest: '8.3.8' }])
1181
- * // { moved: ['vite ^8.3.7 -> ^8.3.8'], kept: ['peer vite ^8.3.7 left alone, not ^8.3.8'] }
1413
+ * // { moved: ['vite ^8.3.7 -> ^8.3.8'], kept: ['peer vite ^8.3.7 kept, admits 8.3.8'] }
1182
1414
  * ```
1183
1415
  */
1184
- export function writeRanges(target, releases) {
1416
+ export function writeRanges(target, releases, peers = []) {
1185
1417
  const manifest = readManifest(target);
1186
1418
  if (manifest === undefined)
1187
1419
  return { moved: [], kept: [] };
@@ -1190,26 +1422,66 @@ export function writeRanges(target, releases) {
1190
1422
  if (typeof block !== 'object' || block === null)
1191
1423
  return [];
1192
1424
  const ranges = Object.fromEntries(Object.entries(block));
1193
- return [{ field, ranges, moves: computeRanges(ranges, releases) }];
1425
+ if (field !== 'peerDependencies')
1426
+ return [{ field, moves: computeRanges(ranges, releases), kept: [] }];
1427
+ const decisions = Object.entries(ranges).flatMap(([name, range]) => typeof range === 'string'
1428
+ ? [
1429
+ [
1430
+ name,
1431
+ raisePeer(name, range, releases.findLast((release) => release.name === name && release.latest !== undefined) ?? peers.findLast((release) => release.name === name)),
1432
+ ],
1433
+ ]
1434
+ : []);
1435
+ return [
1436
+ {
1437
+ field,
1438
+ moves: {
1439
+ ranges: {
1440
+ ...ranges,
1441
+ ...Object.fromEntries(decisions.map(([name, peer]) => [name, peer.range])),
1442
+ },
1443
+ moved: decisions.flatMap(([, peer]) => (peer.raised ? [peer.message] : [])),
1444
+ },
1445
+ kept: decisions.flatMap(([, peer]) => (peer.raised ? [] : [peer.message])),
1446
+ },
1447
+ ];
1194
1448
  });
1195
- const peers = fields.filter((entry) => entry.field === 'peerDependencies');
1196
- const kept = peers.flatMap((entry) => Object.entries(entry.ranges)
1197
- .filter(([name, range]) => entry.moves.ranges[name] !== range)
1198
- .map(([name, range]) => `peer ${name} ${String(range)} left alone, not ${String(entry.moves.ranges[name])}`));
1199
- const pinned = fields.filter((entry) => entry.field !== 'peerDependencies');
1200
- const moved = pinned.flatMap((entry) => entry.moves.moved);
1449
+ const moved = fields.flatMap((entry) => entry.moves.moved);
1201
1450
  if (moved.length > 0) {
1202
1451
  const written = {
1203
1452
  ...manifest,
1204
- ...Object.fromEntries(pinned.map((entry) => [entry.field, entry.moves.ranges])),
1453
+ ...Object.fromEntries(fields.map((entry) => [entry.field, entry.moves.ranges])),
1205
1454
  };
1206
1455
  writeFileSync(join(target, 'package.json'), `${JSON.stringify(written, null, '\t')}\n`);
1207
1456
  }
1208
- return { moved, kept };
1457
+ return { moved, kept: fields.flatMap((entry) => entry.kept) };
1458
+ }
1459
+ /**
1460
+ * Judges one peer-only release lookup.
1461
+ *
1462
+ * @param result - The `npm view NAME@BOUND version deprecated dist-tags.latest --json` command.
1463
+ * @param bound - The lookup bound.
1464
+ * @returns Exit 0 naming the served version, or naming that no release within the bound is
1465
+ * eligible, when the lookup exited 0; else the lookup's failing exit and its reason.
1466
+ */
1467
+ export function judgeLookup(result, bound) {
1468
+ if (result.status !== 0)
1469
+ return readVerdict(result);
1470
+ const served = readServedVersion(result.stdout, bound);
1471
+ return {
1472
+ exit: 0,
1473
+ note: served === undefined ? `no eligible release within ${bound}` : `serves ${served}`,
1474
+ };
1209
1475
  }
1210
1476
  /**
1211
1477
  * Runs the pin step.
1212
1478
  *
1479
+ * @remarks
1480
+ * A peer-only dependency produces no audit release reading, so the step looks each one up with
1481
+ * `npm view`, per {@link collectPeerLookups}, before the rewrite, and stops before the rewrite and
1482
+ * the install when a lookup exits non-zero. A lookup that exits 0 with no eligible release keeps
1483
+ * its peer. Offline, it looks up none and the rewrite keeps those peers as declared.
1484
+ *
1213
1485
  * @param runner - The visit's state.
1214
1486
  * @param scaffoldFile - The scaffold executable.
1215
1487
  * @param scaffoldPrefix - The arguments that precede scaffold's own.
@@ -1222,7 +1494,26 @@ export function runPin(runner, scaffoldFile, scaffoldPrefix, offline) {
1222
1494
  const releases = readReleases(audit.stdout);
1223
1495
  if (releases === undefined || (audit.status !== 0 && audit.status !== 1))
1224
1496
  return;
1225
- const { moved, kept } = writeRanges(runner.target, releases);
1497
+ const lookups = collectPeerLookups(readManifest(runner.target) ?? {}, releases);
1498
+ if (runner.offline && lookups.length > 0)
1499
+ appendStep(runner, 'pin', 'npm view', `offline: no peer-only lookup for ${lookups.map((lookup) => lookup.name).join(', ')}`);
1500
+ const readings = (runner.offline ? [] : lookups).map((lookup) => {
1501
+ const view = runNpmStep(runner, 'pin', [
1502
+ 'view',
1503
+ `${lookup.name}@${lookup.bound}`,
1504
+ 'version',
1505
+ 'deprecated',
1506
+ 'dist-tags.latest',
1507
+ '--json',
1508
+ ], (result) => judgeLookup(result, lookup.bound));
1509
+ if (view?.status !== 0)
1510
+ return undefined;
1511
+ const latest = readServedVersion(view.stdout, lookup.bound);
1512
+ return { name: lookup.name, range: lookup.bound, latest };
1513
+ });
1514
+ if (readings.includes(undefined))
1515
+ return;
1516
+ const { moved, kept } = writeRanges(runner.target, releases, readings.filter((reading) => reading !== undefined));
1226
1517
  appendStep(runner, 'pin', 'rewrite audit release ranges to the registry caret', [moved.length === 0 ? 'no range moved' : moved.join(', '), ...kept].join('; '));
1227
1518
  }
1228
1519
  else {