@orkestrel/scaffold 0.0.22 → 0.0.23

package/dist/host/claude/agents/orkestrel.md

@@ -35,15 +35,15 @@ descriptions never enter agent instruction context.
 | Package               | Version |
 | --------------------- | ------- |
 | @orkestrel/abort      | 0.0.5   |
-| @orkestrel/agent      | 0.0.13  |
+| @orkestrel/agent      | 0.0.14  |
 | @orkestrel/browser    | 0.0.8   |
 | @orkestrel/budget     | 0.0.5   |
 | @orkestrel/console    | 0.0.4   |
-| @orkestrel/contract   | 0.0.9   |
+| @orkestrel/contract   | 0.0.10  |
 | @orkestrel/csv        | 0.0.2   |
 | @orkestrel/database   | 0.0.7   |
 | @orkestrel/emitter    | 0.0.5   |
-| @orkestrel/guide      | 0.0.8   |
+| @orkestrel/guide      | 0.0.9   |
 | @orkestrel/html       | 0.0.2   |
 | @orkestrel/indexeddb  | 0.0.6   |
 | @orkestrel/interpret  | 0.0.7   |
@@ -61,7 +61,7 @@ descriptions never enter agent instruction context.
 | @orkestrel/reason     | 0.0.4   |
 | @orkestrel/relation   | 0.0.7   |
 | @orkestrel/router     | 0.0.8   |
-| @orkestrel/scaffold   | 0.0.21  |
+| @orkestrel/scaffold   | 0.0.22  |
 | @orkestrel/sea        | 0.0.5   |
 | @orkestrel/server     | 0.0.10  |
 | @orkestrel/sqlite     | 0.0.6   |
@@ -74,7 +74,7 @@ descriptions never enter agent instruction context.
 | @orkestrel/websocket  | 0.0.7   |
 | @orkestrel/worker     | 0.0.6   |
 | @orkestrel/workflow   | 0.0.10  |
-| @orkestrel/workspace  | 0.0.2   |
+| @orkestrel/workspace  | 0.0.3   |
 
 <!-- catalog:end -->
 

package/dist/host/guides/src/scaffold.md

@@ -1261,7 +1261,15 @@ application-browser compiler, without adding another test project.
 `coreViteConfig`, `srcViteConfig`, `binViteConfig`, and `appViteConfig` emit the thin per-target
 wrappers. `coreViteConfig()` is parameterless and never imports or attaches browser CSS machinery;
 the root `srcCore` factory and its wrapper stay host-independent even when the workspace also owns a
-browser target. `binTsconfig` emits the executable declaration scope; `rootViteConfig`,
+browser target. `srcViteConfig` takes the environment plus the blueprint's `name` and `src`, because
+its face declaration has to reach `src/core` through a specifier the published tarball carries.
+`bundleTypes` rolls the face up through API Extractor, which leaves each core re-export behind a
+relative `../core/index.ts` path no consumer can resolve; a workspace declaring `core` therefore
+emits a `beforeWriteFile` rewrite turning that path into `@orkestrel/<name>`, its own published root
+export. The rewrite matches the final face roll-up only — applying it to the intermediate
+declarations makes API Extractor analyse `src/core`'s source and abort — and a workspace with no
+`core` emits no rewrite at all. `binTsconfig` emits the executable declaration scope;
+`rootViteConfig`,
 `singleSrcViteConfig`, and `applicationViteConfig` emit the root configuration for a library-only,
 single non-core `src` environment, and application-bearing workspace respectively; and
 `policyViteProject`, `configViteProject`, `guidesViteProject`, `integrationViteProject`, and
@@ -1970,6 +1978,34 @@ it is not a general-purpose source analyzer. Generated workspaces receive the sa
 module as a host-origin file and run it as a dedicated Node-only `policy` test project over
 `tests/policy.test.ts`.
 
+**Fleet policy purity.** Both policy files are fleet-owned: scaffold copies its own
+[`tests/setupPolicy.ts`](../../tests/setupPolicy.ts) into every workspace verbatim and regenerates
+[`tests/policy.test.ts`](../../tests/policy.test.ts) from the shipped template, so a local addition
+to either is discarded at the next bump. A second pass therefore guards them against accumulating
+any one package's architecture. It derives the forbidden identifier tokens from the consuming
+workspace's own declared package name — the short name's upper-snake and Pascal spellings, deduped —
+so the pass states no package literal and can never report itself. It reports every identifier that
+begins with one of those tokens, and it rejects any string or template literal naming a
+source-environment path under the `src/` prefix. Policy names an environment without that prefix
+when it must name one at all, so the rule does not fight the files' real needs. The generated test
+sweeps both files and plants a violation built from the same derived token, so a clean sweep is
+evidence rather than an instrument that has never fired.
+
+**Why the token match is a prefix.** A package's architecture reaches these files as identifiers
+named for the package — `MCP_PATH`, `RouterPlan` — so the identifier must _begin_ with the token.
+A word that merely holds the token somewhere inside it is fleet vocabulary, not one package's
+architecture, and the pass leaves it alone. That is the rule on its own terms, and it also settles
+the collision the fleet actually has: `@orkestrel/contract` derives `Contract`, which
+[`tests/setupPolicy.ts`](../../tests/setupPolicy.ts) holds inside `isContractProperty`, and that
+workspace now adopts the pass unchanged. The match stays case-sensitive, so `mcpValue` is not the
+`MCP` token.
+
+One collision stays open, and its report is correct rather than a false positive. `@orkestrel/policy`
+derives `POLICY`, which both files use as an identifier prefix many times over — the pass would be
+reporting the vocabulary it is built from. A workspace cannot be named for that and adopt this pass;
+it renames or omits the pass. Every other name in the line derives tokens no policy identifier
+begins with.
+
 **The configuration suite.** Policy reads source, the `config` project exercises the root
 configuration, and integration builds for real. Every generated workspace therefore receives a
 universal Node-only
@@ -2528,7 +2564,7 @@ viteMachinery([], ['core', 'browser']) // { browser: true, vue: true, output: tr
 renderViteTest([{ project: 'srcCore' }], false).includes('projects: [srcCore]') // true
 viteHeader(viteMachinery([], ['core', 'browser'])) // the shared header, with browser and Vue support
 coreViteConfig()
-srcViteConfig('browser')
+srcViteConfig('browser', { name: 'router', src: ['core', 'browser'] })
 appViteConfig('server')
 policyViteProject()
 configViteProject()

package/dist/host/tests/setupPolicy.ts

@@ -112,6 +112,32 @@ export const CODING_SOURCE_EXTENSIONS: readonly string[] = Object.freeze([
 /** Production-source glob derived from the complete inspected extension vocabulary. */
 export const CODING_SOURCE_GLOB = `{app,src}/**/*.{${CODING_SOURCE_EXTENSIONS.join(',')}}`
 
+/** Fleet-owned policy files that must stay free of any one package's architecture. */
+export const POLICY_INFRASTRUCTURE_FILES: readonly string[] = Object.freeze([
+	'tests/policy.test.ts',
+	'tests/setupPolicy.ts',
+])
+
+/** Source environments whose prefixed paths fleet policy must not name in a literal. */
+export const POLICY_SOURCE_ENVIRONMENTS: readonly string[] = Object.freeze([
+	'browser',
+	'core',
+	'server',
+])
+
+/**
+ * The prefixed source-environment path fleet policy must not name in a literal.
+ *
+ * @remarks
+ * Built rather than written, so this file states no matching literal of its own
+ * and can never report itself. Policy names an environment without the source
+ * prefix when it must name one at all, which is why the prefix is the rule.
+ */
+export const POLICY_ENVIRONMENT_PATTERN: RegExp = new RegExp(
+	`src/(?:${POLICY_SOURCE_ENVIRONMENTS.join('|')})/`,
+	'u',
+)
+
 /** Virtual source text used while binding one policy-inspected module. */
 export const POLICY_SOURCE_TEXTS: Map<string, string> = new Map()
 
@@ -767,3 +793,104 @@ export function inspectCodingWorkspace(
 	}
 	return violations
 }
+
+/**
+ * Read one workspace's declared package name.
+ *
+ * @param root - The workspace root holding the package manifest
+ * @returns The declared package name
+ */
+export function readPackageName(root: string): string {
+	const manifest: unknown = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+	const name =
+		typeof manifest === 'object' && manifest !== null && 'name' in manifest
+			? manifest.name
+			: undefined
+	if (typeof name !== 'string') throw new Error(`Package manifest at ${root} declares no name`)
+	return name
+}
+
+/**
+ * Derive the identifier prefixes fleet policy must not use from a package name.
+ *
+ * @param name - The declared package name, scoped or bare
+ * @returns The short name's upper-snake and Pascal spellings, deduped
+ *
+ * @example
+ * ```ts
+ * derivePolicyTokens('@orkestrel/my-router') // ['MY_ROUTER', 'MyRouter']
+ * ```
+ */
+export function derivePolicyTokens(name: string): readonly string[] {
+	const short = name.slice(name.lastIndexOf('/') + 1)
+	const words = short.split(/[^A-Za-z0-9]+/u).filter((word) => word.length > 0)
+	const upper = words.map((word) => word.toUpperCase()).join('_')
+	const pascal = words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join('')
+	return [...new Set([upper, pascal])].filter((token) => token.length > 0)
+}
+
+/**
+ * Add package-architecture violations while traversing one fleet policy source tree.
+ *
+ * @remarks
+ * An identifier carries a package's architecture when it is named for that package,
+ * so it must begin with the token. A word that merely holds the token somewhere
+ * inside it belongs to the fleet's own vocabulary and is left alone.
+ */
+export function inspectPolicyNode(
+	path: string,
+	node: ts.Node,
+	violations: string[],
+	tokens: readonly string[],
+): void {
+	if (ts.isIdentifier(node)) {
+		const token = tokens.find((candidate) => node.text.startsWith(candidate))
+		if (token !== undefined) {
+			violations.push(`${path}:${formatPolicyPosition(node)} forbids the ${token} package token`)
+		}
+	}
+	if (
+		(ts.isStringLiteral(node) || ts.isTemplateLiteralToken(node)) &&
+		POLICY_ENVIRONMENT_PATTERN.test(node.text)
+	) {
+		violations.push(
+			`${path}:${formatPolicyPosition(node)} forbids a source-environment path literal`,
+		)
+	}
+	ts.forEachChild(node, (child) => inspectPolicyNode(path, child, violations, tokens))
+}
+
+/**
+ * Inspect one fleet policy module for a single package's architecture.
+ *
+ * @param path - The workspace-relative source path used in diagnostics
+ * @param content - The TypeScript source text to inspect
+ * @param tokens - The package identifier tokens no identifier may begin with
+ * @returns Every violation, in source-position order
+ */
+export function inspectPolicyPurity(
+	path: string,
+	content: string,
+	tokens: readonly string[],
+): readonly string[] {
+	const violations: string[] = []
+	const source = ts.createSourceFile(path, content, ts.ScriptTarget.Latest, true)
+	inspectPolicyNode(path, source, violations, tokens)
+	return violations
+}
+
+/**
+ * Inspect every fleet policy module under one workspace.
+ *
+ * @param root - The workspace root whose manifest names the consuming package
+ * @returns Every violation across the fleet policy files, in file and position order
+ */
+export function inspectPolicyWorkspace(root: string): readonly string[] {
+	const tokens = derivePolicyTokens(readPackageName(root))
+	const violations: string[] = []
+	for (const path of POLICY_INFRASTRUCTURE_FILES) {
+		const content = readFileSync(join(root, path), 'utf8')
+		violations.push(...inspectPolicyPurity(path, content, tokens))
+	}
+	return violations
+}

package/dist/src/core/index.cjs

@@ -275,7 +275,7 @@ var DEFAULT_VERSION = "0.0.1";
 /** The `engines.node` range the `blueprint` builder fills. */
 var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 /** The devDependency range generated packages pin `@orkestrel/scaffold` at. */
-var SCAFFOLD_RANGE = "^0.0.22";
+var SCAFFOLD_RANGE = "^0.0.23";
 /** Tooling versions shared by scaffold and every generated workspace. */
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
@@ -4700,8 +4700,19 @@ exit 1
 		content: `import { globSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
 import { isBrowserVuePath } from './setup.js'
-import { inspectCodingLaw, inspectCodingWorkspace, isFunctionDomainPath } from './setupPolicy.js'{{vuePolicyImport}}
-
+import {
+	derivePolicyTokens,
+	inspectCodingLaw,
+	inspectCodingWorkspace,
+	inspectPolicyPurity,
+	inspectPolicyWorkspace,
+	isFunctionDomainPath,
+	POLICY_SOURCE_ENVIRONMENTS,
+	readPackageName,
+} from './setupPolicy.js'{{vuePolicyImport}}
+
+${CONST_KEYWORD} POLICY_PLANTED_PATH = 'tests/setupPolicy.ts'
+${CONST_KEYWORD} POLICY_TOKENS = derivePolicyTokens(readPackageName(process.cwd()))
 ${CONST_KEYWORD} FUNCTION_MODULE_PATH = 'app/browser/composables/useTheme.ts'
 ${CONST_KEYWORD} FUNCTION_MODULE_VIOLATION =
 	FUNCTION_MODULE_PATH + ' declarations do not form one matching exported function implementation'
@@ -4840,6 +4851,30 @@ describe('repository coding law', () => {
 		expect(inspectCodingLaw(path, content)).toEqual([])
 	})
 })
+
+describe('fleet policy purity', () => {
+	it('keeps fleet policy files free of this package architecture', () => {
+		expect(inspectPolicyWorkspace(process.cwd())).toEqual([])
+	})
+
+	it('reports planted package architecture, so a clean sweep is evidence', () => {
+		const token = POLICY_TOKENS[0]
+		const environment = POLICY_SOURCE_ENVIRONMENTS[0]
+		if (token === undefined || environment === undefined) {
+			throw new Error('The package manifest derived no policy token to plant')
+		}
+		const planted = [
+			'export const ' + token + '_PATH = []',
+			"export const path = 'src/" + environment + "/index.ts'",
+			'',
+		].join('\\n')
+
+		expect(inspectPolicyPurity(POLICY_PLANTED_PATH, planted, POLICY_TOKENS)).toEqual([
+			POLICY_PLANTED_PATH + ':1:14 forbids the ' + token + ' package token',
+			POLICY_PLANTED_PATH + ':2:21 forbids a source-environment path literal',
+		])
+	})
+})
 `
 	}),
 	setupServer: Object.freeze({
@@ -9288,28 +9323,60 @@ function srcTsconfig(environment) {
 * `build.lib` / externals live in the root `srcBrowser` / `srcServer` export
 * instead (per the live exemplars).
 *
+* @remarks
+* `bundleTypes` rolls the face up through API Extractor, which leaves every
+* `src/core` re-export behind a relative `../core/index.ts` specifier — a path no
+* published tarball carries. A workspace that also declares `core` therefore emits
+* a `beforeWriteFile` rewrite turning that specifier into `@orkestrel/<name>`, the
+* package's own published root export. The rewrite is narrowed to the FINAL face
+* roll-up: applying it to the intermediate declarations makes API Extractor analyse
+* `src/core`'s own source and abort. A workspace with no `core` emits no rewrite,
+* because it has no cross-environment specifier to externalize.
+*
 * @param environment - The non-`core` environment to derive the `vite.config.ts` for.
+* @param spec - The blueprint slice naming the package and its declared source environments.
 * @returns The environment `vite.config.ts` file content, newline-terminated.
 *
 * @example
 * ```ts
-* srcViteConfig('browser').includes('srcBrowser') // true
+* srcViteConfig('browser', { name: 'router', src: ['core', 'browser'] }).includes('srcBrowser')
 * ```
 */
-function srcViteConfig(environment) {
+function srcViteConfig(environment, spec) {
 	const anchor = environment === "browser" ? "srcBrowser" : "srcServer";
+	const specifier = `'@orkestrel/${spec.name}'`;
+	const pattern = "/(?:\\.\\.\\/)+core\\/index\\.ts/g";
+	const inlineCall = `\t\t\t\t\t\t? content.replaceAll(${pattern}, ${specifier})`;
+	const call = fitsPrintWidth(inlineCall) ? [inlineCall] : [
+		"						? content.replaceAll(",
+		`\t\t\t\t\t\t\t\t${pattern},`,
+		`\t\t\t\t\t\t\t\t${specifier},`,
+		"							)"
+	];
+	const face = `/[\\\\/]dist[\\\\/]src[\\\\/]${environment}[\\\\/]index\\.d\\.ts$/`;
+	const external = spec.src.includes("core");
+	const rewrite = external ? `\n${[
+		"				beforeWriteFile: (path, content) => ({",
+		`\t\t\t\t\tcontent: ${face}.test(path)`,
+		...call,
+		"						: content,",
+		"				}),"
+	].join("\n")}` : "";
 	return `import { defineConfig } from 'vite'
 import dts from 'vite-plugin-dts'
 import { ${anchor}, resolveWorkspacePath } from '../../vite.config.ts'
 
-// Types are bundled inline by vite-plugin-dts (see configs/src/vite.core.config.ts
-// for the same pattern).
+${external ? `// vite-plugin-dts rolls this face into one declaration, and the roll-up reaches
+// src/core through a relative source path the tarball does not carry. The rewrite
+// below externalizes core through the package's own published root export, on the
+// final roll-up only.` : `// vite-plugin-dts rolls this face into one declaration. This workspace declares no
+// src/core, so the roll-up has no cross-environment specifier to externalize.`}
 export default defineConfig(
 	${anchor}({
 		plugins: [
 			dts({
 				tsconfigPath: resolveWorkspacePath('configs/src/tsconfig.${environment}.json'),
-				bundleTypes: true,
+				bundleTypes: true,${rewrite}
 			}),
 		],
 	}),
@@ -9525,7 +9592,7 @@ function configArtifacts(spec) {
 		const row = SRC_MATRIX[environment];
 		for (const path of row.configs) {
 			const isTsconfig = path.endsWith(".json");
-			const content = environment === "core" ? isTsconfig ? coreTsconfig() : coreViteConfig() : isTsconfig ? srcTsconfig(environment) : srcViteConfig(environment);
+			const content = environment === "core" ? isTsconfig ? coreTsconfig() : coreViteConfig() : isTsconfig ? srcTsconfig(environment) : srcViteConfig(environment, spec);
 			artifacts.push({
 				path,
 				group: "configs",