@orkestrel/scaffold 0.0.116 → 0.0.118
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 +43 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -0
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/guides/guide.md +19 -12
- package/dist/host/guides/scaffold.md +69 -27
- package/dist/host/manifest.json +5 -5
- package/dist/src/core/index.cjs +125 -2
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +123 -2
- package/dist/src/core/index.d.ts +123 -2
- package/dist/src/core/index.js +121 -3
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +16 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -6
- package/dist/src/server/index.d.ts +12 -6
- package/dist/src/server/index.js +16 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +2 -2
|
@@ -168,6 +168,7 @@ registry copy over any staged tip, so every consumer stays red until that tip is
|
|
|
168
168
|
## Prepare a layer
|
|
169
169
|
|
|
170
170
|
- After the re-pin and before `prepublishOnly`, run `scaffold surface` live over every candidate checkout of the layer, never with `--offline`. Stop the upload on any exit but `0`, and resolve every name it reports under `.claude/rules/names.md` § Fleet name ownership. In scaffold's own layer, run `scaffold catalog` and then `scaffold surface --from .`.
|
|
171
|
+
- When `scaffold surface` prints an advisory, rule it under `.claude/rules/names.md` § Fleet name ownership before the upload; an advisory never stops the upload.
|
|
171
172
|
- Begin each release chain plan with the clean reinstall and the clean, whether it runs in a clone or the checkout.
|
|
172
173
|
- When a writer owns a script the preparation needs, run its installed built twin and record the executable's identity.
|
|
173
174
|
- Derive each release row's ruling from the measured distribution comparison and final runtime-range result under § Rule on the bump.
|
|
@@ -56,7 +56,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
56
56
|
| `@orkestrel/database` | `0.0.19` | L2 | `@orkestrel/sqlite` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/indexeddb` `^0.0.15` | |
|
|
57
57
|
| `@orkestrel/emitter` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
|
|
58
58
|
| `@orkestrel/form` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
|
|
59
|
-
| `@orkestrel/guide` | `0.0.
|
|
59
|
+
| `@orkestrel/guide` | `0.0.28` | L3 | `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18` | |
|
|
60
60
|
| `@orkestrel/html` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
|
|
61
61
|
| `@orkestrel/indexeddb` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
|
|
62
62
|
| `@orkestrel/interpret` | `0.0.18` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/template` `^0.0.11` | |
|
|
@@ -77,7 +77,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
|
|
|
77
77
|
| `@orkestrel/reason` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
|
|
78
78
|
| `@orkestrel/relation` | `0.0.17` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
|
|
79
79
|
| `@orkestrel/router` | `0.0.18` | L2 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
|
|
80
|
-
| `@orkestrel/scaffold` | `0.0.
|
|
80
|
+
| `@orkestrel/scaffold` | `0.0.116` | L3 | `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18`, `@orkestrel/template` `^0.0.11` | |
|
|
81
81
|
| `@orkestrel/sea` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
|
|
82
82
|
| `@orkestrel/server` | `0.0.24` | L3 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/codec` `^0.0.7`, `@orkestrel/router` `^0.0.18`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | |
|
|
83
83
|
| `@orkestrel/sqlite` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
|
|
@@ -235,13 +235,14 @@ directly.
|
|
|
235
235
|
|
|
236
236
|
The server command leaves come from [`helpers.ts`](../src/server/helpers.ts).
|
|
237
237
|
|
|
238
|
-
| Name
|
|
239
|
-
|
|
|
240
|
-
| `formatGuideFinding`
|
|
241
|
-
| `matchesGuideResult`
|
|
242
|
-
| `resolveGuideRoot`
|
|
243
|
-
| `selectGuidePitch`
|
|
244
|
-
| `computeGuideProject`
|
|
238
|
+
| Name | Kind | Signature | Summary |
|
|
239
|
+
| ------------------------- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
240
|
+
| `formatGuideFinding` | function | `(finding: ParityFinding) => string` | Formats one finding with its guide prefix when needed. |
|
|
241
|
+
| `matchesGuideResult` | function | `(result: unknown) => boolean` | Reads an owned foreign result view and accepts passed modules without unhandled errors. |
|
|
242
|
+
| `resolveGuideRoot` | function | `(root: URL \| string) => string` | Resolves a command root to a native absolute path. |
|
|
243
|
+
| `selectGuidePitch` | function | `(entries: readonly ManifestEntry[], name: string \| undefined) => string \| undefined` | Selects the indexed guide matching a package's bare name. |
|
|
244
|
+
| `computeGuideProject` | function | `(module: string) => string \| undefined` | Computes the scoped project a guide module's declarations are emitted through. |
|
|
245
|
+
| `computeGuideEnvironment` | function | `(source: string) => string \| undefined` | Computes the environment directory whose project compiles a guide source. |
|
|
245
246
|
|
|
246
247
|
### Parsers
|
|
247
248
|
|
|
@@ -357,9 +358,15 @@ no-write and rewrite failures preserve a higher existing process exit code.
|
|
|
357
358
|
|
|
358
359
|
Every inventory read first constructs `Parity` without declarations, so every manifest guide
|
|
359
360
|
parses, and every name two modules of one entry declare refuses, before any module compiles. It
|
|
360
|
-
then compiles each distinct
|
|
361
|
-
|
|
362
|
-
|
|
361
|
+
then compiles, through `GuideCompiler`, each distinct `src/<env>` or `app/<env>` directory that a
|
|
362
|
+
parsed row's source equals or sits beneath, and passes every emitted declaration to `Parity` as
|
|
363
|
+
`declarations`. A row over `src/core/panels` reads its signatures from the `src/core` compile. A
|
|
364
|
+
source under no `src/<env>` or `app/<env>` directory refuses with code `compile`, naming the
|
|
365
|
+
module, and a source whose environment's emit holds no declaration under it refuses with code
|
|
366
|
+
`empty`, naming each such module and its project in `context.missing`. An environment compiles
|
|
367
|
+
once per `execute` call: a manifest that lists `src/core` and
|
|
368
|
+
`src/core/panels` compiles `src/core` once, and a `--to` run's second inventory read reuses the
|
|
369
|
+
first read's declarations, which a
|
|
363
370
|
`--to source` rewrite cannot change, because it rewrites doc blocks and the emit removes comments.
|
|
364
371
|
A refusal names the guide or the module; a compile refusal carries the compiler's output in its
|
|
365
372
|
message and in `context.output`. The native command writes the message to stderr and raises the
|
|
@@ -1219,9 +1226,9 @@ source with `npm run test:guides -- --to source`; never weaken the case.
|
|
|
1219
1226
|
- [`tests/src/core/Parity.test.ts`](../tests/src/core/Parity.test.ts) — parity findings, rewrite boundaries, and propagation of parse refusals with the guide path and cause. The `Signature` cell rewrite under guide authority and its report under source authority; the README named in a refused pitch parse; a name two modules of one entry export, refused with the guide, the name, and both modules, beside a distinct-name control.
|
|
1220
1227
|
- [`tests/src/core/sources/Source.test.ts`](../tests/src/core/sources/Source.test.ts) — direct/barrel projections, lexical and JSDoc regressions, canonical-key populations, root and nested indexes, exact row grammar, graph invariants, and correlated population controls; signatures carried from supplied emitted declarations
|
|
1221
1228
|
- [`tests/src/core/sources/SourceManager.test.ts`](../tests/src/core/sources/SourceManager.test.ts) — `computeModuleKey` boundary collision, specifier resolution, the `undefined` skip for an unmapped specifier, array-valued module scopes, `sources()` enumeration, and per-module entity sharing with a differently-scoped identity control.
|
|
1222
|
-
- [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — malformed guide rejection with its path, code, and required header; direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation; compile refusal naming the module; native `--to guide` signature rewrite and `--to source` report with exit codes; a malformed guide refused before any compile; one compile per
|
|
1229
|
+
- [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — malformed guide rejection with its path, code, and required header; direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation; compile refusal naming the module; native `--to guide` signature rewrite and `--to source` report with exit codes; a malformed guide refused before any compile; one compile per environment across a `--to guide` run and across an environment's own and nested module rows, counted through a recording compiler; a nested module row read from its environment's compile, with a drifted cell reported for that row alone; a nested module its environment's project emits nothing under, refused with code `empty`; a source outside every `src/<env>` and `app/<env>` directory, refused with code `compile`; native exit 1 for a header refusal and for a compile refusal; a name `src/core` and `src/server` both export, refused, beside a distinct-name control that resolves
|
|
1223
1230
|
- [`tests/src/server/GuideCompiler.test.ts`](../tests/src/server/GuideCompiler.test.ts) — every signature form computed from a fixture workspace compiler; byte-equal repeated compiles; refusal of a failing compile, a missing project, a module outside `src/<env>` and `app/<env>`, and a workspace with no compiler; coded `compile` refusals with the compiler output in `context`; `empty` refusals for a `declarationDir` and for an `include` that misses the module; `timeout` and `overflow` refusals; the scratch directory gone after a success and after a failure; sorted keys.
|
|
1224
|
-
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — finding formatting, native and file-URL root resolution, pitch selection, and owned foreign-result reading with live receivers. Module-to-project mapping.
|
|
1231
|
+
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — finding formatting, native and file-URL root resolution, pitch selection, and owned foreign-result reading with live receivers. Module-to-project mapping, and the environment directory a source equals or sits beneath, matched by whole segments.
|
|
1225
1232
|
- [`tests/src/server/parsers.test.ts`](../tests/src/server/parsers.test.ts) — native direction arguments and package-name parsing. `rootDir` reading from `--showConfig` output.
|
|
1226
1233
|
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the native carrier and `readGuideBuild`, which returns the built server entry the native-command cases load and refuses a missing build or one older than a source.
|
|
1227
1234
|
- [`tests/distribution.test.ts`](../tests/distribution.test.ts) — the packed package through the `tests/setupDistribution.ts` harness, and `isGuideError` across the packed `import` and `require` entries and a copy at a second path: pairwise-distinct constructors, a hidden brand, subclass recognition, and refusal of a look-alike, a proxy, and a brand-only object.
|
|
@@ -116,13 +116,16 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
116
116
|
| `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
|
|
117
117
|
| `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
|
|
118
118
|
|
|
119
|
-
| Name
|
|
120
|
-
|
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
119
|
+
| Name | Kind | Signature | Summary |
|
|
120
|
+
| ------------------- | --------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
121
|
+
| `SurfaceAdvisory` | interface | `{ name, owner, peer, similarity }` | Reports a name a candidate adds beside a near name or an equal contract another owner claims. |
|
|
122
|
+
| `SurfaceCandidate` | interface | `{ conflicts }` | Represents a candidate checkout's contract with each name two or more of its environments export. |
|
|
123
|
+
| `SurfaceClaim` | interface | `{ owner, names }` | Represents one owner's bare exported names, including an empty candidate surface. |
|
|
124
|
+
| `SurfaceCollision` | interface | `{ name, owners }` | Represents a bare name claimed by distinct package owners. |
|
|
125
|
+
| `SurfaceConflict` | interface | `{ name, owner, environments }` | Represents a bare name one owner's barrels export from two or more of its environments. |
|
|
126
|
+
| `SurfaceContract` | interface | `{ signatures }` | Represents one owner's claim with the guide `Signature` cell of each name a Surface row documents. |
|
|
127
|
+
| `SurfaceFinding` | interface | `{ standing }` | Reports a collision's standing against the recorded owner set. |
|
|
128
|
+
| `SurfaceSimilarity` | type | `'case' \| 'plural' \| 'edit' \| 'signature'` | Names how an added name resembles a name another owner claims. |
|
|
126
129
|
|
|
127
130
|
#### Constants
|
|
128
131
|
|
|
@@ -212,6 +215,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
212
215
|
| `STYLES_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies the styles surface adds, frozen. |
|
|
213
216
|
| `STYLES_ENTRY_PATH` | const | `"src/styles/index.scss"` | Names the base stylesheet marker. |
|
|
214
217
|
| `SURFACES` | const | `readonly Surface[]` | Lists the surfaces an extension may extend, frozen. |
|
|
218
|
+
| `SURFACE_EDIT_LENGTH` | const | `6` | Sets the shortest name length at which a one-edit neighbor counts as a near name. |
|
|
215
219
|
| `TAB_WIDTH` | const | `2` | Sets the columns one tab occupies when the formatter measures a line, matching `tabWidth`. |
|
|
216
220
|
| `TARGET_SKILL_NAMES` | const | `readonly string[]` | Lists the package-facing skills a target receives pointers for, frozen and alphabetical. |
|
|
217
221
|
| `THEMES_BARREL_PATH` | const | `"src/styles/themes/index.scss"` | Names the themes stylesheet marker. |
|
|
@@ -304,11 +308,15 @@ Exported from `@orkestrel/scaffold`, and reachable from
|
|
|
304
308
|
| `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
|
|
305
309
|
| `srcToRoot` | function | `(src: readonly Environment[]) => Environment \| undefined` | Selects the single published environment a package root points at. |
|
|
306
310
|
|
|
307
|
-
| Name | Kind | Signature
|
|
308
|
-
| -------------------------- | -------- |
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
311
|
+
| Name | Kind | Signature | Summary |
|
|
312
|
+
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
313
|
+
| `collectSurfaceAdvisories` | function | `(candidate: SurfaceContract, published: readonly string[], contracts: readonly SurfaceContract[]) => readonly SurfaceAdvisory[]` | Collects the near names and equal contracts other owners claim beside each name a candidate adds. |
|
|
314
|
+
| `collectSurfaceCollisions` | function | `(claims: readonly SurfaceClaim[]) => readonly SurfaceCollision[]` | Collects bare names claimed by distinct owners in sorted order. |
|
|
315
|
+
| `collectSurfaceConflicts` | function | `(owner: string, exports: Readonly<Record<string, readonly string[]>>) => readonly SurfaceConflict[]` | Collects the bare names one owner exports from two or more of its environments. |
|
|
316
|
+
| `compareSurfaceCollisions` | function | `(collisions: readonly SurfaceCollision[], record: readonly SurfaceCollision[]) => readonly SurfaceFinding[]` | Compares collisions with the record and reports errors, recorded subsets, and closures. |
|
|
317
|
+
| `inferSurfaceSimilarity` | function | `(name: string, other: string) => SurfaceSimilarity \| undefined` | Infers how two different names resemble each other by spelling. |
|
|
318
|
+
| `matchesGuideRefusal` | function | `(error: unknown) => boolean` | Checks whether an error is the `TARGET` refusal a surface reader raises for a guide its parser refuses, which carries the parser's code in its context. |
|
|
319
|
+
| `matchesSurfaceStructure` | function | `(signature: string) => boolean` | Checks whether a guide `Signature` cell spells a structure rather than a literal or a type name. |
|
|
312
320
|
|
|
313
321
|
#### Compilers
|
|
314
322
|
|
|
@@ -393,7 +401,7 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
393
401
|
| `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
|
|
394
402
|
| `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
|
|
395
403
|
| `ReadAllowanceInterface` | interface | `{ remaining, spend() }` | Describes the byte allowance one upstream call spends across every read it makes. |
|
|
396
|
-
| `SurfaceModule` | interface | `{ createGuide, createSource, extractSourceLines }`
|
|
404
|
+
| `SurfaceModule` | interface | `{ createGuide, createSource, extractSourceLines, isGuideError }` | Describes the guide module functions required by surface reflection. |
|
|
397
405
|
| `TextReadResult` | interface | `{ lookup, content, note, unreachable? }` | Reports the outcome of one bounded read whose body is taken as text. |
|
|
398
406
|
| `Worktree` | interface | `{ tracked, dirty }` | Describes what git reports about a target's working tree. |
|
|
399
407
|
| `UpstreamInterface` | interface | `{ emitter, lookup(), fetch(), read(), catalog(), inventory(), destroy() }` | Describes the upstream contract: the package's only network reader, and it never writes. |
|
|
@@ -498,10 +506,10 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
|
|
|
498
506
|
| `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
|
|
499
507
|
| `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
|
|
500
508
|
| `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
|
|
501
|
-
| `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly
|
|
509
|
+
| `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
|
|
502
510
|
| `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
|
|
503
|
-
| `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) =>
|
|
504
|
-
| `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) =>
|
|
511
|
+
| `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceContract \| undefined` | Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim. |
|
|
512
|
+
| `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceContract` | Reads one guide's claims and reports parser refusals with its owner and source. |
|
|
505
513
|
| `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
|
|
506
514
|
| `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
|
|
507
515
|
| `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
|
|
@@ -759,8 +767,11 @@ nor `src/`, when its guide exists but is not UTF-8 text within the artifact boun
|
|
|
759
767
|
TypeScript source under `src/` cannot be read. Only `.ts` files under `src/` are read, so a binary
|
|
760
768
|
asset there is ignored. A barrel holding a statement other than `export * from './module.js'`
|
|
761
769
|
refuses with the statement named, because the reflection follows nothing else and an incomplete
|
|
762
|
-
reading never reports clean. When `@orkestrel/guide` refuses a guide from any source
|
|
763
|
-
|
|
770
|
+
reading never reports clean. When `@orkestrel/guide` refuses a guide from any source with an error
|
|
771
|
+
its `isGuideError` guard accepts, such as a `## Surface` header other than
|
|
772
|
+
`Name | Kind | Signature | Summary`, the command refuses with `TARGET`, naming the owner and the
|
|
773
|
+
source, carrying the parser's message, and holding the guide error's `code` in the refusal's
|
|
774
|
+
context. Any other error the parser raises propagates unchanged.
|
|
764
775
|
|
|
765
776
|
Compare unpublished candidates together with this command:
|
|
766
777
|
|
|
@@ -774,6 +785,28 @@ or carrying an owner absent from its recorded owner set, has `error` standing. A
|
|
|
774
785
|
same or fewer owners has `recorded` standing. A recorded name that no longer collides has `closed`
|
|
775
786
|
standing, so a release can shrink the record.
|
|
776
787
|
|
|
788
|
+
A name a candidate adds is one its claims hold and its owner's published guide does not. The
|
|
789
|
+
published guide is read in the order the Claims row gives for any other owner: the guide on `main`,
|
|
790
|
+
then the data root's `guides/<owner>.md`, or that root's guide alone under `--from`. That guide
|
|
791
|
+
sets only the advisory baseline, so when its parser refuses it the command reads the next source,
|
|
792
|
+
and with none left every name the candidate claims counts as added; a refused guide for any other
|
|
793
|
+
owner stops the run. The command compares each added name with every other owner's claimed names, never with the candidate's own,
|
|
794
|
+
and reports an advisory for each near name: a case-fold twin (`case`), a singular or plural form by
|
|
795
|
+
`s`, `es`, or `y` to `ies` (`plural`), or a name one insertion, deletion, or substitution away when
|
|
796
|
+
both names hold at least `SURFACE_EDIT_LENGTH` characters (`edit`). It also reports a different
|
|
797
|
+
name whose `Signature` cell equals the added name's cell (`signature`) when `matchesSurfaceStructure`
|
|
798
|
+
reads that cell as a structure: a member list with at least one member, its array and union forms
|
|
799
|
+
included. A pair that is both a near name and an equal structure reports once in each class. A literal, a bare
|
|
800
|
+
primitive, a type reference, a function type, and an empty member list are no structure, and a name
|
|
801
|
+
only a barrel claims carries no cell. An advisory never changes the exit code; rule each one under
|
|
802
|
+
`.claude/rules/names.md` § Fleet name ownership before you publish. Each advisory prints one line,
|
|
803
|
+
where `NAME` is the added name, `OWNER` the candidate, `PEER` the other name, `HOLDER` the other
|
|
804
|
+
owner, and `CLASS` the similarity:
|
|
805
|
+
|
|
806
|
+
```text
|
|
807
|
+
Surface advisory "NAME": "OWNER" adds it beside "PEER" from "HOLDER" (CLASS). Rule it under fleet name ownership before the upload.
|
|
808
|
+
```
|
|
809
|
+
|
|
777
810
|
The command returns `1` when a collision has `error` standing, a candidate carries a conflict, or
|
|
778
811
|
an owner is unread. A run without
|
|
779
812
|
`--offline` or `--from` also returns `1` when membership fell to the floor catalog table, any
|
|
@@ -781,26 +814,35 @@ owner fell to the floor guide, or the record fell to the floor inventory. Every
|
|
|
781
814
|
|
|
782
815
|
The human report names membership when it fell to the floor catalog table, with the failure the
|
|
783
816
|
registry read reported, then each owner that fell to the floor guide, each unread owner, the record
|
|
784
|
-
when it fell to the floor inventory, each `error` collision with its owners,
|
|
785
|
-
with its owner and environments, then prints the recorded and closed counts. The `--json` option
|
|
786
|
-
emits one value with `owners`, `collisions`, `conflicts`, and `provenance`. Each owner carries `owner`, `source` (`candidate`, `live`, `floor`, or `unread`), and
|
|
817
|
+
when it fell to the floor inventory, each `error` collision with its owners, each conflict
|
|
818
|
+
with its owner and environments, and each advisory, then prints the recorded and closed counts. The `--json` option
|
|
819
|
+
emits one value with `owners`, `collisions`, `conflicts`, `advisories`, and `provenance`. Each owner carries `owner`, `source` (`candidate`, `live`, `floor`, or `unread`), and
|
|
787
820
|
`names` unless it is unread. Each collision carries `name`, `owners`, and `standing`, sorted by
|
|
788
821
|
name, including closed entries with their recorded owners. Each conflict carries `name`, `owner`,
|
|
789
|
-
and `environments`, sorted by name within each candidate.
|
|
822
|
+
and `environments`, sorted by name within each candidate. Each advisory carries the candidate's
|
|
823
|
+
`name` and `owner`, the other owner's name as `peer`, and `similarity`, sorted within each candidate
|
|
824
|
+
by added name, peer owner, and peer name, with a spelling class before `signature`. `provenance.membership` names the
|
|
790
825
|
package list's baseline, `provenance.guides` is `live` only when no owner fell to the floor, and
|
|
791
826
|
`provenance.record` names the record's baseline; a `--from` run reports none of them. The command changes no files.
|
|
792
827
|
|
|
793
828
|
The core `SurfaceClaim` interface carries `owner` and `names`. `SurfaceCollision` carries `name`
|
|
794
829
|
and `owners`; `SurfaceFinding` adds `standing`. `SurfaceConflict` carries `name`, `owner`, and
|
|
795
|
-
`environments
|
|
830
|
+
`environments`. `SurfaceContract` adds `signatures`, the `Signature` cell of each name a guide row
|
|
831
|
+
documents, to a claim, and `SurfaceCandidate` adds `conflicts` to a contract. `SurfaceAdvisory`
|
|
832
|
+
carries `name`, `owner`, `peer`, and a `SurfaceSimilarity` as `similarity`. `collectSurfaceCollisions`
|
|
796
833
|
deduplicates owners, `compareSurfaceCollisions` applies the record, and `collectSurfaceConflicts`
|
|
797
|
-
finds the names one owner exports from more than one environment. `
|
|
834
|
+
finds the names one owner exports from more than one environment. `collectSurfaceAdvisories`
|
|
835
|
+
compares a candidate's added names with other owners' contracts through `inferSurfaceSimilarity`
|
|
836
|
+
and `matchesSurfaceStructure`, and `matchesGuideRefusal` recognizes the refusal a reader raises for
|
|
837
|
+
a guide its parser refuses. `readSurfaceClaims` reads
|
|
798
838
|
immediate package guides, excluding the README index. `readSurfaceCandidate` adds live barrel names
|
|
799
839
|
and the candidate's conflicts. `readSurfaceFile` reads
|
|
800
|
-
one owner's guide file under a root, and `readSurfaceGuide` parses guide text from any source
|
|
840
|
+
one owner's guide file under a root, and `readSurfaceGuide` parses guide text from any source into
|
|
841
|
+
a contract.
|
|
801
842
|
`readSurfaceRecord` reads a data root's record, and `resolveHostRoot` resolves the bundled root.
|
|
802
|
-
`readSurfaceModule` loads `@orkestrel/guide` lazily and narrows it with `isSurfaceModule
|
|
803
|
-
|
|
843
|
+
`readSurfaceModule` loads `@orkestrel/guide` lazily and narrows it with `isSurfaceModule`, which
|
|
844
|
+
requires `createGuide`, `createSource`, `extractSourceLines`, and `isGuideError` as functions, and
|
|
845
|
+
refuses with `TARGET` a module that lacks one or holds another value there; every reader takes an optional `SurfaceLoader` that resolves the module, and requires the package in
|
|
804
846
|
scaffold's resolution path when none is supplied. Importing the server entry alone does not load
|
|
805
847
|
it.
|
|
806
848
|
|
package/dist/host/manifest.json
CHANGED
|
@@ -472,7 +472,7 @@
|
|
|
472
472
|
"storage": "agents/skills/orkestrel-publish/references/wave.md",
|
|
473
473
|
"destination": ".agents/skills/orkestrel-publish/references/wave.md",
|
|
474
474
|
"executable": false,
|
|
475
|
-
"digest": "
|
|
475
|
+
"digest": "51f5303628eae0b7508955382ac4173d2e8245a93e424179dbeb6bd3a4311440"
|
|
476
476
|
},
|
|
477
477
|
{
|
|
478
478
|
"storage": "agents/skills/orkestrel-publish/references/window.md",
|
|
@@ -604,7 +604,7 @@
|
|
|
604
604
|
"storage": "claude/agents/orkestrel.md",
|
|
605
605
|
"destination": ".claude/agents/orkestrel.md",
|
|
606
606
|
"executable": false,
|
|
607
|
-
"digest": "
|
|
607
|
+
"digest": "4ad75a62b6d394db889f1754956bbd053c2a68c5ed34b1cfae0d81841835a6f9"
|
|
608
608
|
},
|
|
609
609
|
{
|
|
610
610
|
"storage": "claude/agents/planner.md",
|
|
@@ -1042,7 +1042,7 @@
|
|
|
1042
1042
|
"storage": "guides/guide.md",
|
|
1043
1043
|
"destination": "guides/guide.md",
|
|
1044
1044
|
"executable": false,
|
|
1045
|
-
"digest": "
|
|
1045
|
+
"digest": "b8747025c58c3ea720c02db45d88a1047093f792c2fccde363080f82b0fb38be"
|
|
1046
1046
|
},
|
|
1047
1047
|
{
|
|
1048
1048
|
"storage": "guides/html.md",
|
|
@@ -1168,7 +1168,7 @@
|
|
|
1168
1168
|
"storage": "guides/scaffold.md",
|
|
1169
1169
|
"destination": "guides/scaffold.md",
|
|
1170
1170
|
"executable": false,
|
|
1171
|
-
"digest": "
|
|
1171
|
+
"digest": "ef9158ff72a362260dece3d5f1bacc37d6c9ceb6f75e4b8814e5b64dabc39a5b"
|
|
1172
1172
|
},
|
|
1173
1173
|
{
|
|
1174
1174
|
"storage": "guides/sea.md",
|
|
@@ -2141,5 +2141,5 @@
|
|
|
2141
2141
|
]
|
|
2142
2142
|
}
|
|
2143
2143
|
],
|
|
2144
|
-
"digest": "
|
|
2144
|
+
"digest": "461c2456d47acc1b510a19690530ee7ee12346677c6a2858210daeb0242f5488"
|
|
2145
2145
|
}
|
package/dist/src/core/index.cjs
CHANGED
|
@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
|
|
|
4
4
|
let _orkestrel_emitter = require("@orkestrel/emitter");
|
|
5
5
|
var package_default = {
|
|
6
6
|
name: "@orkestrel/scaffold",
|
|
7
|
-
version: "0.0.
|
|
7
|
+
version: "0.0.118",
|
|
8
8
|
description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
|
|
9
9
|
keywords: [
|
|
10
10
|
"audit",
|
|
@@ -106,7 +106,7 @@ var package_default = {
|
|
|
106
106
|
devDependencies: {
|
|
107
107
|
"@microsoft/api-extractor": "^7.60.0",
|
|
108
108
|
"@orkestrel/browser": "^0.0.30",
|
|
109
|
-
"@orkestrel/guide": "^0.0.
|
|
109
|
+
"@orkestrel/guide": "^0.0.28",
|
|
110
110
|
"@orkestrel/html": "^0.0.13",
|
|
111
111
|
"@orkestrel/probe": "^0.0.26",
|
|
112
112
|
"@orkestrel/test": "^0.0.31",
|
|
@@ -600,6 +600,8 @@ var MAX_RANGE_LENGTH = 2048;
|
|
|
600
600
|
var MAX_SCRIPT_LENGTH = 4096;
|
|
601
601
|
/** Caps the length of one path, matching the longest a supported filesystem accepts. */
|
|
602
602
|
var MAX_PATH_LENGTH = 32767;
|
|
603
|
+
/** Sets the shortest name length at which a one-edit neighbor counts as a near name. */
|
|
604
|
+
var SURFACE_EDIT_LENGTH = 6;
|
|
603
605
|
/** Caps the items accepted in one public collection. */
|
|
604
606
|
var MAX_COLLECTION_ITEMS = 1e3;
|
|
605
607
|
/** Caps the columns one emitted line may occupy, matching `printWidth` in `.oxfmtrc.json`. */
|
|
@@ -5592,6 +5594,122 @@ function collectSurfaceConflicts(owner, exports) {
|
|
|
5592
5594
|
});
|
|
5593
5595
|
}
|
|
5594
5596
|
/**
|
|
5597
|
+
* Infers how two different names resemble each other by spelling.
|
|
5598
|
+
*
|
|
5599
|
+
* @returns The first class that holds, or `undefined` when none does or the names are equal.
|
|
5600
|
+
*
|
|
5601
|
+
* @remarks
|
|
5602
|
+
* Reads, in order, a case-fold twin, a singular or plural form (`s`, `es`, or `y` to `ies`), and
|
|
5603
|
+
* one insertion, deletion, or substitution of a code unit when both names hold at least
|
|
5604
|
+
* `SURFACE_EDIT_LENGTH` characters. Never returns `signature`, which compares cells.
|
|
5605
|
+
*
|
|
5606
|
+
* @example
|
|
5607
|
+
* ```ts
|
|
5608
|
+
* import { inferSurfaceSimilarity } from '@orkestrel/scaffold'
|
|
5609
|
+
*
|
|
5610
|
+
* inferSurfaceSimilarity('Route', 'Routes') // 'plural'
|
|
5611
|
+
* ```
|
|
5612
|
+
*/
|
|
5613
|
+
function inferSurfaceSimilarity(name, other) {
|
|
5614
|
+
const [short, long] = name.length <= other.length ? [name, other] : [other, name];
|
|
5615
|
+
if (name === other) return void 0;
|
|
5616
|
+
if (name.toLowerCase() === other.toLowerCase()) return "case";
|
|
5617
|
+
if (long === `${short}s` || long === `${short}es` || short.endsWith("y") && long === `${short.slice(0, -1)}ies`) return "plural";
|
|
5618
|
+
if (short.length < 6 || long.length - short.length > 1) return void 0;
|
|
5619
|
+
const found = short.split("").findIndex((character, position) => character !== long[position]);
|
|
5620
|
+
const index = found === -1 ? short.length : found;
|
|
5621
|
+
const rest = long.length === short.length ? short.slice(index + 1) : short.slice(index);
|
|
5622
|
+
return long.slice(index + 1) === rest ? "edit" : void 0;
|
|
5623
|
+
}
|
|
5624
|
+
/**
|
|
5625
|
+
* Checks whether an error is the `TARGET` refusal a surface reader raises for a guide its parser
|
|
5626
|
+
* refuses, which carries the parser's code in its context.
|
|
5627
|
+
*
|
|
5628
|
+
* @returns True if the error is that refusal; false otherwise.
|
|
5629
|
+
*
|
|
5630
|
+
* @example
|
|
5631
|
+
* ```ts
|
|
5632
|
+
* import { matchesGuideRefusal, ScaffoldError } from '@orkestrel/scaffold'
|
|
5633
|
+
*
|
|
5634
|
+
* matchesGuideRefusal(new ScaffoldError('TARGET', 'Refused', { code: 'header' })) // true
|
|
5635
|
+
* ```
|
|
5636
|
+
*/
|
|
5637
|
+
function matchesGuideRefusal(error) {
|
|
5638
|
+
return isScaffoldError(error) && error.code === "TARGET" && (0, _orkestrel_contract.isRecord)(error.context) && (0, _orkestrel_contract.isString)(error.context.code);
|
|
5639
|
+
}
|
|
5640
|
+
/**
|
|
5641
|
+
* Checks whether a guide `Signature` cell spells a structure rather than a literal or a type name.
|
|
5642
|
+
*
|
|
5643
|
+
* @returns True if the cell is one code span that opens with a member list holding at least one
|
|
5644
|
+
* member, its array and union forms included; false otherwise.
|
|
5645
|
+
*
|
|
5646
|
+
* @remarks
|
|
5647
|
+
* A literal (`2000`, `" "`, `'live' | 'floor'`), a bare primitive (`string`), a type reference
|
|
5648
|
+
* (`RegExp`, `Guard<string>`, `readonly string[]`), a function type, an empty member list, and
|
|
5649
|
+
* prose are no structure: two names sharing one of those share a type, not a contract.
|
|
5650
|
+
*
|
|
5651
|
+
* @example
|
|
5652
|
+
* ```ts
|
|
5653
|
+
* import { matchesSurfaceStructure } from '@orkestrel/scaffold'
|
|
5654
|
+
*
|
|
5655
|
+
* matchesSurfaceStructure('`{ owner, names }`') // true
|
|
5656
|
+
* ```
|
|
5657
|
+
*/
|
|
5658
|
+
function matchesSurfaceStructure(signature) {
|
|
5659
|
+
const code = /^`([^`]+)`$/u.exec(signature)?.[1]?.trim();
|
|
5660
|
+
return code !== void 0 && code.startsWith("{") && !/^\{\s*\}$/u.test(code);
|
|
5661
|
+
}
|
|
5662
|
+
/**
|
|
5663
|
+
* Collects the near names and equal contracts other owners claim beside each name a candidate adds.
|
|
5664
|
+
*
|
|
5665
|
+
* @param candidate - The candidate owner's contract.
|
|
5666
|
+
* @param published - The names the candidate owner's published guide claims; empty when none.
|
|
5667
|
+
* @param contracts - Every owner's contract; the candidate owner's own entry is skipped.
|
|
5668
|
+
* @returns One advisory per added name, peer, and class, sorted by added name, peer owner, and peer
|
|
5669
|
+
* name, with a spelling class before `signature`.
|
|
5670
|
+
*
|
|
5671
|
+
* @remarks
|
|
5672
|
+
* An added name is one `candidate` claims and `published` does not. A spelling class comes from
|
|
5673
|
+
* `inferSurfaceSimilarity`; `signature` holds when both names carry equal cells that
|
|
5674
|
+
* `matchesSurfaceStructure` accepts. A name equal to the added name is a collision, not an
|
|
5675
|
+
* advisory.
|
|
5676
|
+
*
|
|
5677
|
+
* @example
|
|
5678
|
+
* ```ts
|
|
5679
|
+
* import { collectSurfaceAdvisories } from '@orkestrel/scaffold'
|
|
5680
|
+
*
|
|
5681
|
+
* const advisories = collectSurfaceAdvisories(
|
|
5682
|
+
* { owner: 'alpha', names: ['Routes'], signatures: new Map() },
|
|
5683
|
+
* [],
|
|
5684
|
+
* [{ owner: 'router', names: ['Route'], signatures: new Map() }],
|
|
5685
|
+
* )
|
|
5686
|
+
* advisories[0]?.similarity // 'plural'
|
|
5687
|
+
* ```
|
|
5688
|
+
*/
|
|
5689
|
+
function collectSurfaceAdvisories(candidate, published, contracts) {
|
|
5690
|
+
const known = new Set(published);
|
|
5691
|
+
const peers = contracts.filter(({ owner }) => owner !== candidate.owner).flatMap(({ owner, names, signatures }) => [...new Set(names)].map((name) => ({
|
|
5692
|
+
name,
|
|
5693
|
+
owner,
|
|
5694
|
+
signature: signatures.get(name)
|
|
5695
|
+
}))).sort((left, right) => (0, _orkestrel_contract.compareValues)(left.owner, right.owner) || (0, _orkestrel_contract.compareValues)(left.name, right.name));
|
|
5696
|
+
return [...new Set(candidate.names)].filter((name) => !known.has(name)).sort(_orkestrel_contract.compareValues).flatMap((name) => {
|
|
5697
|
+
const signature = candidate.signatures.get(name);
|
|
5698
|
+
const structure = signature !== void 0 && matchesSurfaceStructure(signature);
|
|
5699
|
+
return peers.flatMap((peer) => {
|
|
5700
|
+
return [inferSurfaceSimilarity(name, peer.name), structure && peer.name !== name && peer.signature === signature ? "signature" : void 0].flatMap((similarity) => similarity === void 0 ? [] : [{
|
|
5701
|
+
name,
|
|
5702
|
+
owner: candidate.owner,
|
|
5703
|
+
peer: {
|
|
5704
|
+
name: peer.name,
|
|
5705
|
+
owner: peer.owner
|
|
5706
|
+
},
|
|
5707
|
+
similarity
|
|
5708
|
+
}]);
|
|
5709
|
+
});
|
|
5710
|
+
});
|
|
5711
|
+
}
|
|
5712
|
+
/**
|
|
5595
5713
|
* Encodes bytes as exact lowercase hexadecimal text.
|
|
5596
5714
|
*
|
|
5597
5715
|
* @param bytes - The bytes to encode.
|
|
@@ -9793,6 +9911,7 @@ exports.STUDIES_TEST_INCLUDE = STUDIES_TEST_INCLUDE;
|
|
|
9793
9911
|
exports.STYLES_DEV_DEPENDENCIES = STYLES_DEV_DEPENDENCIES;
|
|
9794
9912
|
exports.STYLES_ENTRY_PATH = STYLES_ENTRY_PATH;
|
|
9795
9913
|
exports.SURFACES = SURFACES;
|
|
9914
|
+
exports.SURFACE_EDIT_LENGTH = SURFACE_EDIT_LENGTH;
|
|
9796
9915
|
exports.ScaffoldError = ScaffoldError;
|
|
9797
9916
|
exports.TAB_WIDTH = TAB_WIDTH;
|
|
9798
9917
|
exports.TARGET_SKILL_NAMES = TARGET_SKILL_NAMES;
|
|
@@ -9832,6 +9951,7 @@ exports.blueprintToWritableScripts = blueprintToWritableScripts;
|
|
|
9832
9951
|
exports.bytesToHex = bytesToHex;
|
|
9833
9952
|
exports.catalogToLayers = catalogToLayers;
|
|
9834
9953
|
exports.cloneValue = cloneValue;
|
|
9954
|
+
exports.collectSurfaceAdvisories = collectSurfaceAdvisories;
|
|
9835
9955
|
exports.collectSurfaceCollisions = collectSurfaceCollisions;
|
|
9836
9956
|
exports.collectSurfaceConflicts = collectSurfaceConflicts;
|
|
9837
9957
|
exports.compareSurfaceCollisions = compareSurfaceCollisions;
|
|
@@ -9846,6 +9966,7 @@ exports.extractRangeMajor = extractRangeMajor;
|
|
|
9846
9966
|
exports.extractVersion = extractVersion;
|
|
9847
9967
|
exports.inferDrift = inferDrift;
|
|
9848
9968
|
exports.inferGroup = inferGroup;
|
|
9969
|
+
exports.inferSurfaceSimilarity = inferSurfaceSimilarity;
|
|
9849
9970
|
exports.insertManifestDependencies = insertManifestDependencies;
|
|
9850
9971
|
exports.insertManifestSection = insertManifestSection;
|
|
9851
9972
|
exports.isArtifact = isArtifact;
|
|
@@ -9885,9 +10006,11 @@ exports.manifestToDependencies = manifestToDependencies;
|
|
|
9885
10006
|
exports.manifestToName = manifestToName;
|
|
9886
10007
|
exports.matchesDriftReachability = matchesDriftReachability;
|
|
9887
10008
|
exports.matchesEngines = matchesEngines;
|
|
10009
|
+
exports.matchesGuideRefusal = matchesGuideRefusal;
|
|
9888
10010
|
exports.matchesOrchestrationPath = matchesOrchestrationPath;
|
|
9889
10011
|
exports.matchesPrintWidth = matchesPrintWidth;
|
|
9890
10012
|
exports.matchesRange = matchesRange;
|
|
10013
|
+
exports.matchesSurfaceStructure = matchesSurfaceStructure;
|
|
9891
10014
|
exports.nameToGuide = nameToGuide;
|
|
9892
10015
|
exports.overridesToQuestions = overridesToQuestions;
|
|
9893
10016
|
exports.parseBlueprint = parseBlueprint;
|