@orkestrel/scaffold 0.0.134 → 0.0.136

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 (53) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +777 -83
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +327 -21
  3. package/dist/bin/main.js +254 -36
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +2 -2
  6. package/dist/host/agents/orchestration.md +2 -2
  7. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  8. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +983 -123
  9. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  11. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +403 -32
  12. package/dist/host/claude/agents/orkestrel.md +17 -17
  13. package/dist/host/claude/agents/reviewer.md +1 -1
  14. package/dist/host/claude/rules/architecture.md +1 -1
  15. package/dist/host/claude/rules/documentation.md +1 -1
  16. package/dist/host/claude/rules/patterns.md +4 -2
  17. package/dist/host/claude/rules/workspace.md +73 -67
  18. package/dist/host/configs/helpers.ts +109 -73
  19. package/dist/host/dotfiles/oxlintrc.json +1 -57
  20. package/dist/host/guides/agent.md +989 -395
  21. package/dist/host/guides/contract.md +198 -163
  22. package/dist/host/guides/database.md +978 -503
  23. package/dist/host/guides/indexeddb.md +80 -66
  24. package/dist/host/guides/middleware.md +5 -5
  25. package/dist/host/guides/ollama.md +41 -42
  26. package/dist/host/guides/relation.md +56 -32
  27. package/dist/host/guides/scaffold.md +185 -107
  28. package/dist/host/guides/sqlite.md +44 -23
  29. package/dist/host/guides/study.md +12 -12
  30. package/dist/host/guides/test.md +163 -47
  31. package/dist/host/guides/toolbox.md +127 -81
  32. package/dist/host/guides/workspace.md +21 -14
  33. package/dist/host/manifest.json +30 -30
  34. package/dist/host/scripts/browsers.sh +0 -0
  35. package/dist/host/scripts/codex.sh +0 -0
  36. package/dist/host/scripts/cursor.sh +0 -0
  37. package/dist/host/scripts/deps.sh +0 -0
  38. package/dist/host/scripts/npm.sh +0 -0
  39. package/dist/host/scripts/ollama.sh +0 -0
  40. package/dist/host/tests/config.test.ts +237 -115
  41. package/dist/src/core/index.cjs +591 -218
  42. package/dist/src/core/index.cjs.map +1 -1
  43. package/dist/src/core/index.d.cts +248 -29
  44. package/dist/src/core/index.d.ts +248 -29
  45. package/dist/src/core/index.js +581 -216
  46. package/dist/src/core/index.js.map +1 -1
  47. package/dist/src/server/index.cjs +18 -8
  48. package/dist/src/server/index.cjs.map +1 -1
  49. package/dist/src/server/index.d.cts +4 -3
  50. package/dist/src/server/index.d.ts +4 -3
  51. package/dist/src/server/index.js +19 -9
  52. package/dist/src/server/index.js.map +1 -1
  53. package/package.json +3 -3
@@ -22,6 +22,7 @@ import {
22
22
  import {
23
23
  basename,
24
24
  dirname,
25
+ extname,
25
26
  isAbsolute,
26
27
  join,
27
28
  relative,
@@ -373,11 +374,28 @@ export function findPackageDirectory(current: string): string | undefined {
373
374
  return parent === current ? undefined : findPackageDirectory(parent)
374
375
  }
375
376
 
377
+ /**
378
+ * Checks whether a path names an existing directory.
379
+ *
380
+ * @remarks
381
+ * Reads presence through `existsSync`, which answers `false` for an absent path and for a path
382
+ * beneath a file on every host; `lstatSync` with `throwIfNoEntry: false` returns `undefined` for
383
+ * the second on Windows (`ENOENT`) and throws on Linux (`ENOTDIR`).
384
+ *
385
+ * @param path - The path to check.
386
+ * @returns True if the path names an existing directory; false otherwise.
387
+ * @example
388
+ * ```ts
389
+ * isDirectoryPath(process.cwd()) // true
390
+ * ```
391
+ */
392
+ export function isDirectoryPath(path: string): boolean {
393
+ return existsSync(path) && lstatSync(path).isDirectory()
394
+ }
395
+
376
396
  export function packageRootOf(packageName: string, resolvedPath: string): string | undefined {
377
397
  const physical = physicalPath(resolvedPath)
378
- const directory = findPackageDirectory(
379
- lstatSync(physical, { throwIfNoEntry: false })?.isDirectory() ? physical : dirname(physical),
380
- )
398
+ const directory = findPackageDirectory(isDirectoryPath(physical) ? physical : dirname(physical))
381
399
  return directory !== undefined && packageManifestName(directory) === packageName
382
400
  ? realpathSync.native(directory)
383
401
  : undefined
@@ -385,9 +403,7 @@ export function packageRootOf(packageName: string, resolvedPath: string): string
385
403
 
386
404
  export function packageRootForResolved(resolvedPath: string): string | undefined {
387
405
  const physical = physicalPath(resolvedPath)
388
- const directory = findPackageDirectory(
389
- lstatSync(physical, { throwIfNoEntry: false })?.isDirectory() ? physical : dirname(physical),
390
- )
406
+ const directory = findPackageDirectory(isDirectoryPath(physical) ? physical : dirname(physical))
391
407
  return directory !== undefined && packageManifestName(directory) !== undefined
392
408
  ? realpathSync.native(directory)
393
409
  : undefined
@@ -522,7 +538,7 @@ export class BuildState {
522
538
  #building = false
523
539
  #output: string
524
540
  #root = WORKSPACE_ROOT
525
- #source = ''
541
+ #entries: Readonly<Record<string, string>> = {}
526
542
  readonly #trusted = new Set<string>()
527
543
 
528
544
  constructor(output = WORKSPACE_ROOT) {
@@ -544,9 +560,9 @@ export class BuildState {
544
560
  return this.#root
545
561
  }
546
562
 
547
- /** The library entry path, or an empty string when the build has none. */
548
- get source(): string {
549
- return this.#source
563
+ /** The library entry paths by entry name, empty when the build has none. */
564
+ get entries(): Readonly<Record<string, string>> {
565
+ return this.#entries
550
566
  }
551
567
 
552
568
  /**
@@ -571,7 +587,10 @@ export class BuildState {
571
587
  }
572
588
 
573
589
  /**
574
- * Reads the command, output directory, project root, and library entry from a resolved config.
590
+ * Reads the command, output directory, project root, and library entries from a resolved config.
591
+ *
592
+ * @remarks
593
+ * A single-path entry and each member of an entry list take their file's stem as their name.
575
594
  *
576
595
  * @param config - The resolved Vite configuration.
577
596
  */
@@ -579,10 +598,11 @@ export class BuildState {
579
598
  this.#building = config.command === 'build'
580
599
  this.#output = resolvePath(config.root, config.build.outDir)
581
600
  this.#root = physicalPath(config.root)
582
- this.#source =
583
- config.build.lib !== false && typeof config.build.lib.entry === 'string'
584
- ? config.build.lib.entry
585
- : ''
601
+ const entry = config.build.lib === false ? {} : config.build.lib.entry
602
+ this.#entries =
603
+ typeof entry === 'string' || Array.isArray(entry)
604
+ ? Object.fromEntries([entry].flat().map((path) => [basename(path, extname(path)), path]))
605
+ : { ...entry }
586
606
  }
587
607
  }
588
608
 
@@ -696,13 +716,15 @@ export interface ExtractorModule {
696
716
  *
697
717
  * @remarks
698
718
  * `project` is the absolute path of that face's TypeScript project file. `types` overrides the
699
- * `types` the extractor's own program reads, and defaults to the face's resolved `types`. `rewrite`
700
- * receives the finished roll-up and returns what the face ships; a face that omits it ships the
701
- * roll-up as the extractor wrote it.
719
+ * `types` the extractor's own program reads, and defaults to the face's resolved `types`. `entries`
720
+ * names the library entries that roll up, and defaults to every entry the build declares; a
721
+ * single-path entry takes its file's stem as its name. `rewrite` receives each finished roll-up and
722
+ * returns what the face ships; a face that omits it ships the roll-up as the extractor wrote it.
702
723
  */
703
724
  export interface DeclarationRollupOptions {
704
725
  readonly project: string
705
726
  readonly types?: readonly string[]
727
+ readonly entries?: readonly string[]
706
728
  readonly rewrite?: (content: string) => string
707
729
  }
708
730
 
@@ -878,27 +900,28 @@ export function rewriteBrowserSpecifier(content: string): string {
878
900
  }
879
901
 
880
902
  /**
881
- * Rewrites every server alias in a roll-up to the built server entry beside the reporter output.
903
+ * Rewrites every source environment alias in a roll-up to the built environment beside `dist/bin`.
882
904
  *
883
905
  * @param content - The finished roll-up.
884
- * @returns That roll-up with each `@src/server` specifier replaced by `../src/server/index.js`.
906
+ * @returns That roll-up with each `@src/<environment>` specifier replaced by
907
+ * `../src/<environment>/index.js`.
885
908
  *
886
909
  * @remarks
887
- * The reporter entry reaches the server class through the `@src/server` alias, and the extractor
888
- * keeps it external and writes it through unchanged. `dist/reporter/main.d.ts` resolves the server
889
- * declarations at the same relative path its `main.js` imports through `output.paths`.
910
+ * A `src/bin` module reaches a library environment through its `@src/*` alias, and the extractor
911
+ * keeps the alias external and writes it through unchanged. `dist/bin/<name>.d.ts` resolves the
912
+ * environment's declarations at the relative path its `<name>.js` imports through `output.paths`.
890
913
  *
891
914
  * @example
892
915
  * ```ts
893
- * rewriteServerSpecifier("from '@src/server'") // "from '../src/server/index.js'"
916
+ * rewriteSourceSpecifier("from '@src/server'") // "from '../src/server/index.js'"
894
917
  * ```
895
918
  */
896
- export function rewriteServerSpecifier(content: string): string {
897
- return content.replaceAll('@src/server', '../src/server/index.js')
919
+ export function rewriteSourceSpecifier(content: string): string {
920
+ return content.replaceAll(/@src\/([a-z][a-z0-9-]*)(?=['"])/gu, '../src/$1/index.js')
898
921
  }
899
922
 
900
923
  /**
901
- * Rolls one published face's declarations into the single file that face ships.
924
+ * Rolls each named library entry's declarations into the single file that entry ships.
902
925
  *
903
926
  * @param options - The face's roll-up options.
904
927
  * @returns The Vite plugin that performs that roll-up.
@@ -906,9 +929,10 @@ export function rewriteServerSpecifier(content: string): string {
906
929
  * @remarks
907
930
  * At `closeBundle`, after Vite has written every format of the face, the plugin emits the face's
908
931
  * declarations with the workspace compiler run as a process into a scratch directory made fresh
909
- * under the host temporary directory, hands the emitted entry to the extractor's own engine,
910
- * applies `rewrite`, and removes the scratch directory. The roll-up takes the entry's own name, so
911
- * an `index.ts` face ships `index.d.ts` and a `main.ts` entry ships `main.d.ts`. Keeping the
932
+ * under the host temporary directory, hands each named entry to the extractor's own engine,
933
+ * applies `rewrite`, and removes the scratch directory. Each roll-up takes its entry's name, so
934
+ * an `index.ts` face ships `index.d.ts` and a `reporter` entry ships `reporter.d.ts`. An empty
935
+ * `entries` list rolls up nothing. Keeping the
912
936
  * scratch outside the face's own output means its unconditional removal can never take a sibling
913
937
  * the face already published, such as its own `declarations` folder. The extractor is a publishing
914
938
  * workspace's development dependency, so this vendored leaf defers loading it to that hook: a
@@ -924,12 +948,20 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
924
948
  },
925
949
  closeBundle() {
926
950
  if (!state.building) return
927
- const declaration = state.source.replace(/\.tsx?$/, '.d.ts')
928
- if (declaration === state.source) {
951
+ const named = options.entries ?? Object.keys(state.entries)
952
+ const declarations = named.map((name) => {
953
+ const source = state.entries[name] ?? ''
954
+ return { name, source, declaration: source.replace(/\.tsx?$/, '.d.ts') }
955
+ })
956
+ if (
957
+ (options.entries === undefined && declarations.length === 0) ||
958
+ declarations.some(({ source, declaration }) => declaration === source)
959
+ ) {
929
960
  throw new Error(
930
- '[orkestrel-declaration-rollup] The face must build one TypeScript library entry',
961
+ '[orkestrel-declaration-rollup] The face must build each named TypeScript library entry',
931
962
  )
932
963
  }
964
+ if (declarations.length === 0) return
933
965
  const load = createRequire(import.meta.url)
934
966
  const compiler = resolveCompiler(import.meta.url)
935
967
  const scope = parseProjectScope(
@@ -942,7 +974,6 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
942
974
  )
943
975
  }
944
976
  const scratch = mkdtempSync(join(tmpdir(), 'orkestrel-declarations-'))
945
- const rollup = resolvePath(state.output, basename(declaration))
946
977
  try {
947
978
  readCompilerOutput(compiler, [
948
979
  '-p',
@@ -954,7 +985,6 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
954
985
  '--outDir',
955
986
  scratch,
956
987
  ])
957
- const entry = resolvePath(scratch, relative(scope.root, declaration))
958
988
  // A literal `import()` of the extractor reddens `tsc` in a workspace that does not
959
989
  // install it, so the literal `createRequire` call is the form that clears the
960
990
  // typecheck in an app-only workspace.
@@ -964,45 +994,51 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
964
994
  '[orkestrel-declaration-rollup] The declaration extractor exposes no entry point',
965
995
  )
966
996
  }
967
- const prepared: unknown = loaded.ExtractorConfig.prepare({
968
- configObject: {
969
- projectFolder: WORKSPACE_ROOT,
970
- mainEntryPointFilePath: entry,
971
- bundledPackages: [],
972
- compiler: {
973
- overrideTsconfig: buildExtractorOverride(
974
- entry,
975
- scope.lib,
976
- options.types ?? scope.types,
977
- ),
978
- },
979
- apiReport: { enabled: false },
980
- docModel: { enabled: false },
981
- tsdocMetadata: { enabled: false },
982
- dtsRollup: { enabled: true, untrimmedFilePath: rollup },
983
- messages: {
984
- compilerMessageReporting: { default: { logLevel: 'none' } },
985
- extractorMessageReporting: { default: { logLevel: 'none' } },
986
- tsdocMessageReporting: { default: { logLevel: 'none' } },
997
+ for (const { name, declaration } of declarations) {
998
+ const entry = resolvePath(scratch, relative(scope.root, declaration))
999
+ const rollup = resolvePath(state.output, `${name}.d.ts`)
1000
+ const prepared: unknown = loaded.ExtractorConfig.prepare({
1001
+ configObject: {
1002
+ projectFolder: WORKSPACE_ROOT,
1003
+ mainEntryPointFilePath: entry,
1004
+ bundledPackages: [],
1005
+ compiler: {
1006
+ overrideTsconfig: buildExtractorOverride(
1007
+ entry,
1008
+ scope.lib,
1009
+ options.types ?? scope.types,
1010
+ ),
1011
+ },
1012
+ apiReport: { enabled: false },
1013
+ docModel: { enabled: false },
1014
+ tsdocMetadata: { enabled: false },
1015
+ dtsRollup: { enabled: true, untrimmedFilePath: rollup },
1016
+ messages: {
1017
+ compilerMessageReporting: { default: { logLevel: 'none' } },
1018
+ extractorMessageReporting: { default: { logLevel: 'none' } },
1019
+ tsdocMessageReporting: { default: { logLevel: 'none' } },
1020
+ },
987
1021
  },
988
- },
989
- configObjectFullPath: resolvePath(WORKSPACE_ROOT, 'api-extractor.json'),
990
- packageJsonFullPath: resolvePath(WORKSPACE_ROOT, 'package.json'),
991
- })
992
- const outcome: unknown = loaded.Extractor.invoke(prepared, {
993
- localBuild: true,
994
- showVerboseMessages: false,
995
- showDiagnostics: false,
996
- })
997
- const succeeded: unknown =
998
- typeof outcome === 'object' && outcome !== null
999
- ? Reflect.get(outcome, 'succeeded')
1000
- : undefined
1001
- if (succeeded !== true) {
1002
- throw new Error('[orkestrel-declaration-rollup] The declaration roll-up failed')
1003
- }
1004
- if (options.rewrite !== undefined) {
1005
- writeFileSync(rollup, options.rewrite(readFileSync(rollup, 'utf8')), 'utf8')
1022
+ configObjectFullPath: resolvePath(WORKSPACE_ROOT, 'api-extractor.json'),
1023
+ packageJsonFullPath: resolvePath(WORKSPACE_ROOT, 'package.json'),
1024
+ })
1025
+ const outcome: unknown = loaded.Extractor.invoke(prepared, {
1026
+ localBuild: true,
1027
+ showVerboseMessages: false,
1028
+ showDiagnostics: false,
1029
+ })
1030
+ const succeeded: unknown =
1031
+ typeof outcome === 'object' && outcome !== null
1032
+ ? Reflect.get(outcome, 'succeeded')
1033
+ : undefined
1034
+ if (succeeded !== true) {
1035
+ throw new Error(
1036
+ `[orkestrel-declaration-rollup] The declaration roll-up of ${name} failed`,
1037
+ )
1038
+ }
1039
+ if (options.rewrite !== undefined) {
1040
+ writeFileSync(rollup, options.rewrite(readFileSync(rollup, 'utf8')), 'utf8')
1041
+ }
1006
1042
  }
1007
1043
  } finally {
1008
1044
  rmSync(scratch, { recursive: true, force: true })
@@ -89,7 +89,7 @@
89
89
  }
90
90
  },
91
91
  {
92
- "files": ["src/reporter/main.ts"],
92
+ "files": ["src/bin/*.ts"],
93
93
  "rules": {
94
94
  "import/no-default-export": "off"
95
95
  }
@@ -779,62 +779,6 @@
779
779
  ]
780
780
  }
781
781
  },
782
- {
783
- "files": ["src/reporter/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}"],
784
- "rules": {
785
- "no-restricted-imports": [
786
- "error",
787
- {
788
- "patterns": [
789
- {
790
- "regex": "^(?:/|[A-Za-z]:[\\\\/])",
791
- "message": "imports must not use machine-specific absolute paths"
792
- },
793
- {
794
- "regex": "^(?:[A-Za-mo-z][A-Za-z0-9+.-]*|n(?:[A-Za-np-z0-9+.-][A-Za-z0-9+.-]*)?|no(?:[A-Za-ce-z0-9+.-][A-Za-z0-9+.-]*)?|nod(?:[A-Za-df-z0-9+.-][A-Za-z0-9+.-]*)?|node[A-Za-z0-9+.-]+):",
795
- "message": "imports must not use non-Node URL schemes"
796
- },
797
- {
798
- "regex": "(?:^|/)(?:[^/.][^/]*|\\.[^/.][^/]*|\\.\\.[^/]+)/\\.{1,2}(?:/|$)",
799
- "message": "internal import paths must not contain noncanonical dot segments"
800
- },
801
- {
802
- "regex": "^(?:(?:\\./)+\\.\\.(?:/|$)|(?:\\.\\./)+(?:\\./)+)|//",
803
- "message": "relative import paths must not contain normalized traversal segments"
804
- },
805
- {
806
- "regex": "\\\\",
807
- "message": "import paths must use portable forward slashes"
808
- },
809
- {
810
- "regex": "^typescript(?:[/?#]|$)",
811
- "message": "the in-process compiler API is not a surface the fleet uses"
812
- },
813
- {
814
- "regex": "\\.(?:css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:[?#]|$)",
815
- "message": "src/reporter must not import browser stylesheets"
816
- },
817
- {
818
- "regex": "^(?:@app(?:[/?#]|$)|(?:\\.\\./)+app(?:[/?#]|$))",
819
- "message": "src/reporter must not depend on private app modules"
820
- },
821
- {
822
- "regex": "^(?:(?:vue|vite)(?:[/?#]|$)|@(?:vue|vitejs)/|@src/(?:browser|vue)(?:[/?#]|$)|@orkestrel/[^/]+/(?:browser|vue)(?:[/?#]|$)|(?:\\.\\./)+(?:browser|vue|src/(?:browser|vue)|app/browser)(?:[/?#]|$))",
823
- "message": "src/reporter must not depend on browser-only modules"
824
- },
825
- {
826
- "regex": "^(?:\\.\\./)+(?:src/)?core(?:[/?#]|$)",
827
- "message": "src/reporter must import src/core through the @src/core alias"
828
- },
829
- {
830
- "regex": "^(?:\\.\\./)+(?:src/)?server(?:[/?#]|$)",
831
- "message": "src/reporter must import src/server through the @src/server alias"
832
- }
833
- ]
834
- }
835
- ]
836
- }
837
- },
838
782
  {
839
783
  "files": [
840
784
  "tests/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx,vue}",