@orkestrel/scaffold 0.0.139 → 0.0.140

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/dist/bin/main.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
3
- import { attempt, isArray, isDefined, isError, isInstance, isRecord, isString, parseJSON } from "@orkestrel/contract";
4
- import { ARTIFACT_GROUPS, AXES, BIN_ENTRY_PATH, BIN_OUTPUT_PATH, CATALOG_AGENT_PATH, CENTRAL_FILE_NAMES, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, FRAMEWORKS, GLOBAL_SETUP_PATH, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, RESERVED_SHEET_NAMES, SERVICE_SETUP_PATH, SHEET_ENTRY_NAME, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SHOWCASE_PAGES_PATH, SKILLS_CONFIG_PATH, STYLES_ENTRY_PATH, ScaffoldError, THEMES_BARREL_PATH, THEMES_ENTRY_PATH, TREE_TEST_PATH, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToEntries, blueprintToFaces, blueprintToManifest, blueprintToManifestOverrides, blueprintToProjects, blueprintToScripts, blueprintToSheets, blueprintToTestArtifacts, blueprintToToolchainHolds, blueprintToWritableScripts, collectSurfaceAdvisories, collectSurfaceCollisions, compareSurfaceCollisions, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, isSheetName, isSubpathMap, iterateAnswers, manifestToDependencies, manifestToEntries, manifestToName, matchesBarrel, matchesGuideRefusal, nameToGuide, parseExtension, replaceManifestOverrides, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
3
+ import { attempt, isArray, isDefined, isError, isInstance, isRecord, isString, parseJSON, settle } from "@orkestrel/contract";
4
+ import { ARTIFACT_GROUPS, AXES, BIN_ENTRY_PATH, BIN_OUTPUT_PATH, CATALOG_AGENT_PATH, CENTRAL_FILE_NAMES, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, FRAMEWORKS, GLOBAL_SETUP_PATH, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, RESERVED_SHEET_NAMES, SERVICE_SETUP_PATH, SHEET_ENTRY_NAME, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SHOWCASE_PAGES_PATH, SKILLS_CONFIG_PATH, STYLES_ENTRY_PATH, ScaffoldError, THEMES_BARREL_PATH, THEMES_ENTRY_PATH, TREE_TEST_PATH, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToEntries, blueprintToFaces, blueprintToManifest, blueprintToManifestOverrides, blueprintToProjects, blueprintToScripts, blueprintToSheets, blueprintToTestArtifacts, blueprintToToolchainHolds, blueprintToWritableScripts, collectSurfaceAdvisories, collectSurfaceCollisions, compareSurfaceCollisions, compareVersions, contentToHex, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, isSheetName, isSubpathMap, iterateAnswers, manifestToDependencies, manifestToEntries, manifestToName, matchesBarrel, matchesGuideRefusal, nameToGuide, parseExtension, replaceManifestOverrides, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
5
5
  import { MAX_INVENTORY_PATHS, Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readHostManifest, readSnapshot, readSurfaceCandidate, readSurfaceFile, readSurfaceGuide, readSurfaceRecord, resolveContainedPath, resolveSurfaceLoader } from "../src/server/index.js";
6
6
  import { join, normalize, resolve } from "node:path";
7
7
  import { createDuplex } from "@orkestrel/process/server";
@@ -10,7 +10,7 @@ import { readdirSync } from "node:fs";
10
10
  import { parseArgs } from "node:util";
11
11
  var package_default = {
12
12
  name: "@orkestrel/scaffold",
13
- version: "0.0.139",
13
+ version: "0.0.140",
14
14
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
15
15
  keywords: [
16
16
  "audit",
@@ -102,20 +102,20 @@ var package_default = {
102
102
  "prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:templates && npm run test:distribution -- --mode release"
103
103
  },
104
104
  dependencies: {
105
- "@orkestrel/console": "^0.0.21",
105
+ "@orkestrel/console": "^0.0.22",
106
106
  "@orkestrel/contract": "^0.0.26",
107
- "@orkestrel/emitter": "^0.0.17",
108
- "@orkestrel/markdown": "^0.0.22",
109
- "@orkestrel/process": "^0.0.21",
110
- "@orkestrel/template": "^0.0.15"
107
+ "@orkestrel/emitter": "^0.0.18",
108
+ "@orkestrel/markdown": "^0.0.23",
109
+ "@orkestrel/process": "^0.0.22",
110
+ "@orkestrel/template": "^0.0.16"
111
111
  },
112
112
  devDependencies: {
113
113
  "@microsoft/api-extractor": "^7.60.1",
114
- "@orkestrel/browser": "^0.0.34",
115
- "@orkestrel/guide": "^0.0.32",
116
- "@orkestrel/html": "^0.0.17",
117
- "@orkestrel/probe": "^0.0.31",
118
- "@orkestrel/test": "^0.0.43",
114
+ "@orkestrel/browser": "^0.0.35",
115
+ "@orkestrel/guide": "^0.0.33",
116
+ "@orkestrel/html": "^0.0.18",
117
+ "@orkestrel/probe": "^0.0.32",
118
+ "@orkestrel/test": "^0.0.44",
119
119
  "@types/node": "^24.19.2",
120
120
  "@vitest/browser-playwright": "^5.1.0",
121
121
  "oxfmt": "^0.79.0",
@@ -1040,6 +1040,40 @@ function releasesToQuestions(releases, served = releases, holds = {}) {
1040
1040
  }).toArray();
1041
1041
  }
1042
1042
  /**
1043
+ * Projects fetched guide mirrors into audit questions.
1044
+ *
1045
+ * @param mirrors - The mirror verdicts that `Upstream.fetch` returned for the present guide mirrors.
1046
+ * @param declared - The package names the target's manifest declares.
1047
+ * @returns One non-blocking `guides` question for each mirror that differs from its repository's
1048
+ * main branch or that no read could compare; a mirror that matches raises none.
1049
+ *
1050
+ * @remarks
1051
+ * A differing mirror of an undeclared package advises `catalog --all`, because `catalog` alone
1052
+ * refreshes only the declared packages.
1053
+ *
1054
+ * @example
1055
+ * ```ts
1056
+ * import { mirrorsToQuestions } from './helpers.js'
1057
+ *
1058
+ * mirrorsToQuestions([], ['@orkestrel/router']) // []
1059
+ * ```
1060
+ */
1061
+ function mirrorsToQuestions(mirrors, declared) {
1062
+ return mirrors.flatMap((mirror) => {
1063
+ if (mirror.lookup !== "found") return [{
1064
+ field: "guides",
1065
+ message: `The guide for ${mirror.name} could not be read from its repository (${mirror.note}); the mirror at ${mirror.path} was not compared.`,
1066
+ blocking: false
1067
+ }];
1068
+ if (mirror.observed === void 0 || contentToHex(mirror.content) === mirror.observed) return [];
1069
+ return [{
1070
+ field: "guides",
1071
+ message: `The mirror at ${mirror.path} differs from the guide on ${mirror.name}'s main branch. Run ${declared.includes(mirror.name) ? "catalog" : "catalog --all"} to refresh it.`,
1072
+ blocking: false
1073
+ }];
1074
+ });
1075
+ }
1076
+ /**
1043
1077
  * Projects an audit into the human summary of its outcome.
1044
1078
  *
1045
1079
  * @param audit - The comparison to summarize.
@@ -2039,11 +2073,8 @@ var CLI = class {
2039
2073
  const read = attempt(() => argvToCommand(argv));
2040
2074
  if (!read.success) return this.#refuse(read.error, false);
2041
2075
  const command = read.value;
2042
- try {
2043
- return await this.#dispatch(command);
2044
- } catch (error) {
2045
- return this.#refuse(error, command.json === true);
2046
- }
2076
+ const dispatched = await settle(() => this.#dispatch(command));
2077
+ return dispatched.success ? dispatched.value : this.#refuse(dispatched.error, command.json === true);
2047
2078
  }
2048
2079
  async #dispatch(command) {
2049
2080
  switch (command.verb) {
@@ -2227,7 +2258,13 @@ var CLI = class {
2227
2258
  const groups = selectionToGroups(command.groups);
2228
2259
  const declared = manifestToWritableDependencies(manifest, blueprint);
2229
2260
  const versions = await this.#versions(declared, command.offline === true, blueprint);
2230
- const questions = [...this.#targetQuestions(target, blueprint, groups), ...releasesToQuestions(versions.releases, void 0, blueprintToToolchainHolds(blueprint))];
2261
+ const guides = await this.#guides(command, target, blueprint, manifest, groups);
2262
+ const questions = [
2263
+ ...this.#targetQuestions(target, blueprint, groups),
2264
+ ...releasesToQuestions(versions.releases, void 0, blueprintToToolchainHolds(blueprint)),
2265
+ ...guides.questions
2266
+ ];
2267
+ const forced = versions.forced || guides.baseline === "floor";
2231
2268
  const host = await this.#host(command.from, target, command.offline === true);
2232
2269
  try {
2233
2270
  const [measured] = this.#survey(host.materializer, blueprint, target, groups);
@@ -2240,6 +2277,7 @@ var CLI = class {
2240
2277
  releases: versions.releases,
2241
2278
  provenance: {
2242
2279
  ...versions.baseline === void 0 ? {} : { versions: versions.baseline },
2280
+ ...guides.baseline === void 0 ? {} : { guides: guides.baseline },
2243
2281
  ...host.baseline === void 0 ? {} : { host: host.baseline }
2244
2282
  }
2245
2283
  };
@@ -2248,13 +2286,36 @@ var CLI = class {
2248
2286
  this.#present(audit);
2249
2287
  if (command.offline !== true) this.#reportReleases(versions.releases);
2250
2288
  }
2251
- if (versions.forced || host.forced) this.#reportBaselines(outcome.provenance);
2289
+ if (forced || host.forced) this.#reportBaselines(outcome.provenance);
2252
2290
  if (command.offline === true) return auditToExit(audit);
2253
- return Math.max(auditToExit(audit), releasesToExit(versions.releases), versions.forced || host.forced ? 1 : 0);
2291
+ return Math.max(auditToExit(audit), releasesToExit(versions.releases), forced || host.forced ? 1 : 0);
2254
2292
  } finally {
2255
2293
  host.materializer.destroy();
2256
2294
  }
2257
2295
  }
2296
+ async #guides(command, target, blueprint, manifest, groups) {
2297
+ if (command.offline === true || groups !== void 0 && !groups.includes("guides")) return { questions: [] };
2298
+ const directory = resolveContainedPath(target, "guides");
2299
+ const listed = new Set(catalogToNames(resolveFloor(command.from)));
2300
+ const names = (directory === void 0 ? [] : listFiles(directory)).filter((file) => !file.includes("/") && file.endsWith(".md") && file !== "README.md" && `guides/${file}` !== nameToGuide(blueprint.name)).map((file) => `@orkestrel/${file.slice(0, -3)}`).filter((name) => listed.has(name));
2301
+ if (names.length === 0) return { questions: [] };
2302
+ const dependencies = manifestToDependencies(manifest);
2303
+ const declared = [
2304
+ ...dependencies.runtime,
2305
+ ...dependencies.development,
2306
+ ...dependencies.peer
2307
+ ].map((dependency) => dependency.name);
2308
+ const upstream = new Upstream(this.#upstream);
2309
+ try {
2310
+ const mirrors = await upstream.fetch(names, readSnapshot(target, names.map(nameToGuide)));
2311
+ return {
2312
+ questions: mirrorsToQuestions(mirrors, declared),
2313
+ baseline: mirrors.some((mirror) => mirror.lookup !== "found") ? "floor" : "live"
2314
+ };
2315
+ } finally {
2316
+ upstream.destroy();
2317
+ }
2318
+ }
2258
2319
  async #restore(command) {
2259
2320
  const target = command.target ?? ".";
2260
2321
  const groups = selectionToGroups(command.groups);
@@ -2462,15 +2523,14 @@ var CLI = class {
2462
2523
  }
2463
2524
  async #reconcile(materializer, target, declared, host, hostForced, blueprint) {
2464
2525
  const previous = catalogToNames(target);
2465
- try {
2526
+ const confirmed = await settle(async () => {
2466
2527
  const versions = await this.#versions(declared.pins, false, blueprint);
2467
- return await this.#confirm(materializer, target, declared, {
2528
+ return this.#confirm(materializer, target, declared, {
2468
2529
  baseline: host,
2469
2530
  forced: hostForced
2470
2531
  }, versions, previous);
2471
- } catch (error) {
2472
- return this.#unfinished(target, [], { ...host === void 0 ? {} : { host } }, error);
2473
- }
2532
+ });
2533
+ return confirmed.success ? confirmed.value : this.#unfinished(target, [], { ...host === void 0 ? {} : { host } }, confirmed.error);
2474
2534
  }
2475
2535
  async #confirm(materializer, target, declared, host, versions, previous) {
2476
2536
  try {