@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/orchestrators/codegen/format.mjs

@@ -12,8 +12,17 @@ const SENSITIVE_HEADER = [
 	"// credentials, or user extras). The output directory ships a .gitignore",
 	"// covering it; this banner is a belt-and-braces reminder."
 ].join("\n");
-/** Render an emitted file to a TS source string. Throws a tagged
-*  error class when the value is unserialisable. */
+const renderErr = (input, detail) => ({
+	ok: false,
+	error: new CodegenRenderError({
+		emitterName: input.emitterName,
+		outputPath: input.outputPath,
+		detail
+	})
+});
+/** Render an emitted file to a TS source string. Returns a discriminated
+*  `RenderResult` — `{ok: true, text}` on success, `{ok: false, error}`
+*  when the value is unserialisable or imports forbidden paths. */
 const renderFile = (input) => {
 	const lines = [];
 	lines.push(GENERATED_HEADER);
@@ -24,11 +33,7 @@ const renderFile = (input) => {
 	lines.push("");
 	if (input.imports && input.imports.length > 0) {
 		for (const imp of input.imports) {
-			if (isForbiddenGeneratedImport(imp)) return new CodegenRenderError({
-				emitterName: input.emitterName,
-				outputPath: input.outputPath,
-				detail: `generated files must not import devstack source: ${imp}`
-			});
+			if (isForbiddenGeneratedImport(imp)) return renderErr(input, `generated files must not import devstack source: ${imp}`);
 			lines.push(imp);
 		}
 		lines.push("");
@@ -37,68 +42,71 @@ const renderFile = (input) => {
 	for (const key of keys) {
 		const value = input.exports[key];
 		const rendered = tryRender(value, /* @__PURE__ */ new Set());
-		if (rendered instanceof Error) return new CodegenRenderError({
-			emitterName: input.emitterName,
-			outputPath: input.outputPath,
-			detail: `export '${key}': ${rendered.message}`
-		});
-		if (!isIdentifier(key)) return new CodegenRenderError({
-			emitterName: input.emitterName,
-			outputPath: input.outputPath,
-			detail: `export key '${key}' is not a valid TS identifier`
-		});
-		lines.push(`export const ${key} = ${rendered} as const;`);
+		if (!rendered.ok) return renderErr(input, `export '${key}': ${rendered.detail}`);
+		if (!isIdentifier(key)) return renderErr(input, `export key '${key}' is not a valid TS identifier`);
+		lines.push(`export const ${key} = ${rendered.text} as const;`);
 		lines.push("");
 	}
 	while (lines.length > 1 && lines[lines.length - 1] === "" && lines[lines.length - 2] === "") lines.pop();
-	return lines.join("\n") + (lines[lines.length - 1] === "" ? "" : "\n");
+	return {
+		ok: true,
+		text: lines.join("\n") + (lines[lines.length - 1] === "" ? "" : "\n")
+	};
 };
 const INDENT = "	";
+const tryOk = (text) => ({
+	ok: true,
+	text
+});
+const tryErr = (detail) => ({
+	ok: false,
+	detail
+});
 const tryRender = (value, seen, depth = 1) => {
-	if (value === null) return "null";
-	if (value === void 0) return /* @__PURE__ */ new Error("undefined is not serialisable — emit null instead");
+	if (value === null) return tryOk("null");
+	if (value === void 0) return tryErr("undefined is not serialisable — emit null instead");
 	const t = typeof value;
-	if (t === "string") return JSON.stringify(value);
+	if (t === "string") return tryOk(JSON.stringify(value));
 	if (t === "number") {
-		if (!Number.isFinite(value)) return /* @__PURE__ */ new Error("non-finite number");
-		return String(value);
+		if (!Number.isFinite(value)) return tryErr("non-finite number");
+		return tryOk(String(value));
 	}
-	if (t === "boolean") return String(value);
-	if (t === "bigint") return JSON.stringify(value.toString());
-	if (t === "function" || t === "symbol") return /* @__PURE__ */ new Error(`${t} is not serialisable`);
+	if (t === "boolean") return tryOk(String(value));
+	if (t === "bigint") return tryOk(JSON.stringify(value.toString()));
+	if (t === "function" || t === "symbol") return tryErr(`${t} is not serialisable`);
 	if (Array.isArray(value)) {
-		if (seen.has(value)) return /* @__PURE__ */ new Error("circular reference");
+		if (seen.has(value)) return tryErr("circular reference");
 		seen.add(value);
-		if (value.length === 0) return "[]";
+		if (value.length === 0) return tryOk("[]");
 		const inner = [];
 		for (const item of value) {
 			const r = tryRender(item, seen, depth + 1);
-			if (r instanceof Error) return r;
-			inner.push(INDENT.repeat(depth) + r);
+			if (!r.ok) return r;
+			inner.push(INDENT.repeat(depth) + r.text);
 		}
 		seen.delete(value);
-		return `[\n${inner.join(",\n")},\n${INDENT.repeat(depth - 1)}]`;
+		return tryOk(`[\n${inner.join(",\n")},\n${INDENT.repeat(depth - 1)}]`);
 	}
 	if (t === "object") {
 		const obj = value;
-		if (seen.has(obj)) return /* @__PURE__ */ new Error("circular reference");
+		if (seen.has(obj)) return tryErr("circular reference");
 		seen.add(obj);
 		const keys = Object.keys(obj).sort();
-		if (keys.length === 0) return "{}";
+		if (keys.length === 0) return tryOk("{}");
 		const lines = [];
 		for (const k of keys) {
 			const v = obj[k];
 			if (v === void 0) continue;
 			const r = tryRender(v, seen, depth + 1);
-			if (r instanceof Error) return r;
+			if (!r.ok) return r;
 			const keyText = isIdentifier(k) ? k : JSON.stringify(k);
-			lines.push(`${INDENT.repeat(depth)}${keyText}: ${r}`);
+			lines.push(`${INDENT.repeat(depth)}${keyText}: ${r.text}`);
 		}
 		seen.delete(obj);
-		if (lines.length === 0) return "{}";
-		return `{\n${lines.join(",\n")},\n${INDENT.repeat(depth - 1)}}`;
+		if (lines.length === 0) return tryOk("{}");
+		return tryOk(`{\n${lines.join(",\n")},\n${INDENT.repeat(depth - 1)}}`);
 	}
-	return /* @__PURE__ */ new Error(`unsupported value type ${t}`);
+	return tryErr(`unsupported value type ${t}`);
 };
 const IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const isIdentifier = (s) => IDENT_RE.test(s);

package/dist/orchestrators/codegen/format.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"format.mjs","names":[],"sources":["../../../src/orchestrators/codegen/format.ts"],"sourcesContent":["// TypeScript source rendering for codegen-emitted files.\n//\n// Distilled-doc § \"Hand-rolled TS-object-literal rendering ... drifts\n// subtly between emitters; a small shared renderer would absorb the\n// variation and own the bigint policy in one place.\" This module IS\n// that shared renderer.\n//\n// Output shape (one emitted file):\n//\n//   <generated-header>\n//   <do-not-commit-banner if sensitive>\n//   <imports?>\n//   <one `export const <name> = <literal> as const;` per export>\n//   <trailing newline>\n//\n// The renderer:\n//   - sorts object keys (deterministic re-emit, distilled-doc\n//     invariant \"Deterministic re-emit\"),\n//   - quotes identifier-unsafe keys with double-quoted strings,\n//   - serialises bigints as quoted decimal strings for\n//     `BigInt(<string>)` consumers,\n//   - refuses functions / symbols / undefined / circular refs with a\n//     typed render error,\n//   - emits arrays and records as readonly literal forms.\n//\n// The renderer does NOT format with prettier; it aims for\n// prettier-compatible spacing (two-space indent, trailing commas,\n// double-quoted strings, semicolons) so a prettier-on-write user\n// hook is a no-op on emitted bytes — that's load-bearing for the\n// \"no mtime touch on identical content\" idempotency invariant.\n\nimport { CodegenRenderError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Headers\n// -----------------------------------------------------------------------------\n\nconst GENERATED_HEADER = [\n\t'// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'// Do not edit by hand — your changes will be overwritten on the next',\n\t'// `devstack up` cycle. Apps consume codegen output; codegen output never',\n\t'// imports from devstack.',\n].join('\\n');\n\nconst SENSITIVE_HEADER = [\n\t'// !!! DO NOT COMMIT THIS FILE !!!',\n\t'// This file carries sensitive material (wallet pair token, database',\n\t'// credentials, or user extras). The output directory ships a .gitignore',\n\t'// covering it; this banner is a belt-and-braces reminder.',\n].join('\\n');\n\n// -----------------------------------------------------------------------------\n// Public render entry\n// -----------------------------------------------------------------------------\n\nexport interface RenderInput {\n\treadonly emitterName: string;\n\treadonly outputPath: string;\n\treadonly sensitive: boolean;\n\t/** The declarations written by `Codegenable.emit(ctx)`. Each entry\n\t *  becomes one `export const <key> = <literal> as const;`. */\n\treadonly exports: { readonly [key: string]: unknown };\n\t/** Optional import lines the emitter wants prepended (e.g. a\n\t *  type import from `@mysten/dapp-kit` for the wallet config).\n\t *  Each entry is a raw import statement string. */\n\treadonly imports?: ReadonlyArray<string>;\n}\n\n/** Render an emitted file to a TS source string. Throws a tagged\n *  error class when the value is unserialisable. */\nexport const renderFile = (input: RenderInput): string | CodegenRenderError => {\n\tconst lines: Array<string> = [];\n\tlines.push(GENERATED_HEADER);\n\tif (input.sensitive) {\n\t\tlines.push('');\n\t\tlines.push(SENSITIVE_HEADER);\n\t}\n\tlines.push('');\n\tif (input.imports && input.imports.length > 0) {\n\t\tfor (const imp of input.imports) {\n\t\t\tif (isForbiddenGeneratedImport(imp)) {\n\t\t\t\treturn new CodegenRenderError({\n\t\t\t\t\temitterName: input.emitterName,\n\t\t\t\t\toutputPath: input.outputPath,\n\t\t\t\t\tdetail: `generated files must not import devstack source: ${imp}`,\n\t\t\t\t});\n\t\t\t}\n\t\t\tlines.push(imp);\n\t\t}\n\t\tlines.push('');\n\t}\n\t// Stable export order: keys lexicographically sorted.\n\tconst keys = Object.keys(input.exports).sort();\n\tfor (const key of keys) {\n\t\tconst value = input.exports[key];\n\t\tconst rendered = tryRender(value, new Set());\n\t\tif (rendered instanceof Error) {\n\t\t\treturn new CodegenRenderError({\n\t\t\t\temitterName: input.emitterName,\n\t\t\t\toutputPath: input.outputPath,\n\t\t\t\tdetail: `export '${key}': ${rendered.message}`,\n\t\t\t});\n\t\t}\n\t\tif (!isIdentifier(key)) {\n\t\t\treturn new CodegenRenderError({\n\t\t\t\temitterName: input.emitterName,\n\t\t\t\toutputPath: input.outputPath,\n\t\t\t\tdetail: `export key '${key}' is not a valid TS identifier`,\n\t\t\t});\n\t\t}\n\t\tlines.push(`export const ${key} = ${rendered} as const;`);\n\t\tlines.push('');\n\t}\n\t// Single trailing newline; never two.\n\twhile (lines.length > 1 && lines[lines.length - 1] === '' && lines[lines.length - 2] === '') {\n\t\tlines.pop();\n\t}\n\treturn lines.join('\\n') + (lines[lines.length - 1] === '' ? '' : '\\n');\n};\n\n// -----------------------------------------------------------------------------\n// Value rendering\n// -----------------------------------------------------------------------------\n\nconst INDENT = '\\t';\n\nconst tryRender = (value: unknown, seen: Set<object>, depth = 1): string | Error => {\n\tif (value === null) return 'null';\n\tif (value === undefined) {\n\t\treturn new Error('undefined is not serialisable — emit null instead');\n\t}\n\tconst t = typeof value;\n\tif (t === 'string') return JSON.stringify(value);\n\tif (t === 'number') {\n\t\tif (!Number.isFinite(value as number)) {\n\t\t\treturn new Error('non-finite number');\n\t\t}\n\t\treturn String(value);\n\t}\n\tif (t === 'boolean') return String(value);\n\tif (t === 'bigint') {\n\t\treturn JSON.stringify(value.toString());\n\t}\n\tif (t === 'function' || t === 'symbol') {\n\t\treturn new Error(`${t} is not serialisable`);\n\t}\n\tif (Array.isArray(value)) {\n\t\tif (seen.has(value)) return new Error('circular reference');\n\t\tseen.add(value);\n\t\tif (value.length === 0) return '[]';\n\t\tconst inner: Array<string> = [];\n\t\tfor (const item of value) {\n\t\t\tconst r = tryRender(item, seen, depth + 1);\n\t\t\tif (r instanceof Error) return r;\n\t\t\tinner.push(INDENT.repeat(depth) + r);\n\t\t}\n\t\tseen.delete(value);\n\t\treturn `[\\n${inner.join(',\\n')},\\n${INDENT.repeat(depth - 1)}]`;\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tif (seen.has(obj)) return new Error('circular reference');\n\t\tseen.add(obj);\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return '{}';\n\t\tconst lines: Array<string> = [];\n\t\tfor (const k of keys) {\n\t\t\tconst v = obj[k];\n\t\t\tif (v === undefined) continue; // drop undefined props (distilled-doc skip-emit-explicit)\n\t\t\tconst r = tryRender(v, seen, depth + 1);\n\t\t\tif (r instanceof Error) return r;\n\t\t\tconst keyText = isIdentifier(k) ? k : JSON.stringify(k);\n\t\t\tlines.push(`${INDENT.repeat(depth)}${keyText}: ${r}`);\n\t\t}\n\t\tseen.delete(obj);\n\t\tif (lines.length === 0) return '{}';\n\t\treturn `{\\n${lines.join(',\\n')},\\n${INDENT.repeat(depth - 1)}}`;\n\t}\n\treturn new Error(`unsupported value type ${t}`);\n};\n\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\nconst isIdentifier = (s: string): boolean => IDENT_RE.test(s);\n\nconst isForbiddenGeneratedImport = (line: string): boolean =>\n\t/\\bfrom\\s+[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bfrom\\s+[\"'][./][^\"']*\\/src\\//.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"'][./][^\"']*\\/src\\//.test(line);\n"],"mappings":"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"}
+{"version":3,"file":"format.mjs","names":[],"sources":["../../../src/orchestrators/codegen/format.ts"],"sourcesContent":["// TypeScript source rendering for codegen-emitted files.\n//\n// Distilled-doc § \"Hand-rolled TS-object-literal rendering ... drifts\n// subtly between emitters; a small shared renderer would absorb the\n// variation and own the bigint policy in one place.\" This module IS\n// that shared renderer.\n//\n// Output shape (one emitted file):\n//\n//   <generated-header>\n//   <do-not-commit-banner if sensitive>\n//   <imports?>\n//   <one `export const <name> = <literal> as const;` per export>\n//   <trailing newline>\n//\n// The renderer:\n//   - sorts object keys (deterministic re-emit, distilled-doc\n//     invariant \"Deterministic re-emit\"),\n//   - quotes identifier-unsafe keys with double-quoted strings,\n//   - serialises bigints as quoted decimal strings for\n//     `BigInt(<string>)` consumers,\n//   - refuses functions / symbols / undefined / circular refs with a\n//     typed render error,\n//   - emits arrays and records as readonly literal forms.\n//\n// The renderer does NOT format with prettier; it aims for\n// prettier-compatible spacing (two-space indent, trailing commas,\n// double-quoted strings, semicolons) so a prettier-on-write user\n// hook is a no-op on emitted bytes — that's load-bearing for the\n// \"no mtime touch on identical content\" idempotency invariant.\n\nimport { CodegenRenderError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Headers\n// -----------------------------------------------------------------------------\n\nconst GENERATED_HEADER = [\n\t'// THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'// Do not edit by hand — your changes will be overwritten on the next',\n\t'// `devstack up` cycle. Apps consume codegen output; codegen output never',\n\t'// imports from devstack.',\n].join('\\n');\n\nconst SENSITIVE_HEADER = [\n\t'// !!! DO NOT COMMIT THIS FILE !!!',\n\t'// This file carries sensitive material (wallet pair token, database',\n\t'// credentials, or user extras). The output directory ships a .gitignore',\n\t'// covering it; this banner is a belt-and-braces reminder.',\n].join('\\n');\n\n// -----------------------------------------------------------------------------\n// Public render entry\n// -----------------------------------------------------------------------------\n\nexport interface RenderInput {\n\treadonly emitterName: string;\n\treadonly outputPath: string;\n\treadonly sensitive: boolean;\n\t/** The declarations written by `Codegenable.emit(ctx)`. Each entry\n\t *  becomes one `export const <key> = <literal> as const;`. */\n\treadonly exports: { readonly [key: string]: unknown };\n\t/** Optional import lines the emitter wants prepended (e.g. a\n\t *  type import from `@mysten/dapp-kit` for the wallet config).\n\t *  Each entry is a raw import statement string. */\n\treadonly imports?: ReadonlyArray<string>;\n}\n\n/** Result of a render attempt. Discriminated so callers can dispatch\n *  on `ok` without resorting to `instanceof` checks (STYLE_GUIDE §2). */\nexport type RenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly error: CodegenRenderError };\n\nconst renderErr = (\n\tinput: RenderInput,\n\tdetail: string,\n): { readonly ok: false; readonly error: CodegenRenderError } => ({\n\tok: false,\n\terror: new CodegenRenderError({\n\t\temitterName: input.emitterName,\n\t\toutputPath: input.outputPath,\n\t\tdetail,\n\t}),\n});\n\n/** Render an emitted file to a TS source string. Returns a discriminated\n *  `RenderResult` — `{ok: true, text}` on success, `{ok: false, error}`\n *  when the value is unserialisable or imports forbidden paths. */\nexport const renderFile = (input: RenderInput): RenderResult => {\n\tconst lines: Array<string> = [];\n\tlines.push(GENERATED_HEADER);\n\tif (input.sensitive) {\n\t\tlines.push('');\n\t\tlines.push(SENSITIVE_HEADER);\n\t}\n\tlines.push('');\n\tif (input.imports && input.imports.length > 0) {\n\t\tfor (const imp of input.imports) {\n\t\t\tif (isForbiddenGeneratedImport(imp)) {\n\t\t\t\treturn renderErr(input, `generated files must not import devstack source: ${imp}`);\n\t\t\t}\n\t\t\tlines.push(imp);\n\t\t}\n\t\tlines.push('');\n\t}\n\t// Stable export order: keys lexicographically sorted.\n\tconst keys = Object.keys(input.exports).sort();\n\tfor (const key of keys) {\n\t\tconst value = input.exports[key];\n\t\tconst rendered = tryRender(value, new Set());\n\t\tif (!rendered.ok) {\n\t\t\treturn renderErr(input, `export '${key}': ${rendered.detail}`);\n\t\t}\n\t\tif (!isIdentifier(key)) {\n\t\t\treturn renderErr(input, `export key '${key}' is not a valid TS identifier`);\n\t\t}\n\t\tlines.push(`export const ${key} = ${rendered.text} as const;`);\n\t\tlines.push('');\n\t}\n\t// Single trailing newline; never two.\n\twhile (lines.length > 1 && lines[lines.length - 1] === '' && lines[lines.length - 2] === '') {\n\t\tlines.pop();\n\t}\n\treturn {\n\t\tok: true,\n\t\ttext: lines.join('\\n') + (lines[lines.length - 1] === '' ? '' : '\\n'),\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Value rendering\n// -----------------------------------------------------------------------------\n\nconst INDENT = '\\t';\n\ntype TryRenderResult =\n\t| { readonly ok: true; readonly text: string }\n\t| { readonly ok: false; readonly detail: string };\n\nconst tryOk = (text: string): TryRenderResult => ({ ok: true, text });\nconst tryErr = (detail: string): TryRenderResult => ({ ok: false, detail });\n\nconst tryRender = (value: unknown, seen: Set<object>, depth = 1): TryRenderResult => {\n\tif (value === null) return tryOk('null');\n\tif (value === undefined) return tryErr('undefined is not serialisable — emit null instead');\n\tconst t = typeof value;\n\tif (t === 'string') return tryOk(JSON.stringify(value));\n\tif (t === 'number') {\n\t\tif (!Number.isFinite(value as number)) return tryErr('non-finite number');\n\t\treturn tryOk(String(value));\n\t}\n\tif (t === 'boolean') return tryOk(String(value));\n\tif (t === 'bigint') return tryOk(JSON.stringify(value.toString()));\n\tif (t === 'function' || t === 'symbol') return tryErr(`${t} is not serialisable`);\n\tif (Array.isArray(value)) {\n\t\tif (seen.has(value)) return tryErr('circular reference');\n\t\tseen.add(value);\n\t\tif (value.length === 0) return tryOk('[]');\n\t\tconst inner: Array<string> = [];\n\t\tfor (const item of value) {\n\t\t\tconst r = tryRender(item, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tinner.push(INDENT.repeat(depth) + r.text);\n\t\t}\n\t\tseen.delete(value);\n\t\treturn tryOk(`[\\n${inner.join(',\\n')},\\n${INDENT.repeat(depth - 1)}]`);\n\t}\n\tif (t === 'object') {\n\t\tconst obj = value as Record<string, unknown>;\n\t\tif (seen.has(obj)) return tryErr('circular reference');\n\t\tseen.add(obj);\n\t\tconst keys = Object.keys(obj).sort();\n\t\tif (keys.length === 0) return tryOk('{}');\n\t\tconst lines: Array<string> = [];\n\t\tfor (const k of keys) {\n\t\t\tconst v = obj[k];\n\t\t\tif (v === undefined) continue; // drop undefined props (distilled-doc skip-emit-explicit)\n\t\t\tconst r = tryRender(v, seen, depth + 1);\n\t\t\tif (!r.ok) return r;\n\t\t\tconst keyText = isIdentifier(k) ? k : JSON.stringify(k);\n\t\t\tlines.push(`${INDENT.repeat(depth)}${keyText}: ${r.text}`);\n\t\t}\n\t\tseen.delete(obj);\n\t\tif (lines.length === 0) return tryOk('{}');\n\t\treturn tryOk(`{\\n${lines.join(',\\n')},\\n${INDENT.repeat(depth - 1)}}`);\n\t}\n\treturn tryErr(`unsupported value type ${t}`);\n};\n\nconst IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;\nconst isIdentifier = (s: string): boolean => IDENT_RE.test(s);\n\nconst isForbiddenGeneratedImport = (line: string): boolean =>\n\t/\\bfrom\\s+[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"']@mysten-incubation\\/devstack(?:-rewrite)?(?:\\/|[\"'])/.test(line) ||\n\t/\\bfrom\\s+[\"'][./][^\"']*\\/src\\//.test(line) ||\n\t/\\bimport\\s*\\(\\s*[\"'][./][^\"']*\\/src\\//.test(line);\n"],"mappings":"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"}

package/dist/orchestrators/codegen/gitignore.mjs

@@ -1,5 +1,6 @@
 import { CodegenWriteFailed } from "./errors.mjs";
 import { emitOne } from "./emit.mjs";
+import "./permissions.mjs";
 import { Effect, FileSystem } from "effect";
 //#region src/orchestrators/codegen/gitignore.ts
 const USER_BLOCK_START = "# user: customisations below preserved across re-emits";
@@ -46,7 +47,8 @@ const writeGitignore = (input) => Effect.gen(function* () {
 	yield* emitOne({
 		path: input.path,
 		content,
-		mode: 420
+		mode: 420,
+		parentMode: input.parentMode ?? 493
 	}).pipe(Effect.mapError((e) => new CodegenWriteFailed({
 		outputPath: input.path,
 		stage: "gitignore",

package/dist/orchestrators/codegen/gitignore.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"gitignore.mjs","names":[],"sources":["../../../src/orchestrators/codegen/gitignore.ts"],"sourcesContent":["// .gitignore emission for the codegen output directory.\n//\n// Distilled-doc §\"Boundary helpers\": \"A `.gitignore` inside the\n// output directory, covering sensitive emitted files by default and\n// preserving user customizations.\" Two design points:\n//\n//   1. The entire output directory is engine-managed and the\n//      pragmatic default is \"ignore everything emitted here\". The\n//      `*` line lives at the top of the file with a comment\n//      explaining the policy.\n//   2. Sensitive files get an explicit second mention so the\n//      `.gitignore` reads as documentation in addition to enforcing\n//      the policy.\n//   3. User customisations land in a tracked `# user:` block — any\n//      content the user adds between the `# user:` and `# /user:`\n//      markers is preserved verbatim across re-emits.\n//\n// The `.gitignore` is emitted with the same per-file atomic writer as\n// the rest of the codegen tree.\n\nimport { Effect, FileSystem } from 'effect';\n\nimport { emitOne } from './emit.ts';\nimport { CodegenWriteFailed } from './errors.ts';\nimport { NON_SENSITIVE_FILE_MODE } from './permissions.ts';\n\nconst USER_BLOCK_START = '# user: customisations below preserved across re-emits';\nconst USER_BLOCK_END = '# /user: do not edit below this line';\n\nconst DEFAULT_USER_BLOCK = `${USER_BLOCK_START}\\n${USER_BLOCK_END}`;\n\nconst HEADER = [\n\t'# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'# The codegen output directory is engine-managed; the whole tree is',\n\t'# ignored from git by default. Sensitive files have an explicit mention',\n\t'# below for documentation. Add user customisations inside the `# user:`',\n\t'# block; the rest is rewritten on every emit cycle.',\n].join('\\n');\n\nexport interface GitignoreInput {\n\treadonly path: string;\n\t/** Relative paths inside the output dir that are sensitive — get\n\t *  an explicit gitignore line. Sorted lexicographically. */\n\treadonly sensitivePaths: ReadonlyArray<string>;\n}\n\n/**\n * Compose the gitignore content, preserving any user customisations\n * between the `# user:` markers in any existing file at `path`.\n */\nexport const composeGitignore = (existing: string | null, input: GitignoreInput): string => {\n\tconst userBlock = existing !== null ? extractUserBlock(existing) : null;\n\tconst sortedSensitive = [...input.sensitivePaths].sort();\n\tconst lines: Array<string> = [];\n\tlines.push(HEADER);\n\tlines.push('');\n\tlines.push('# default policy: ignore the whole output directory.');\n\tlines.push('*');\n\tlines.push('# but keep this .gitignore tracked so cloners get the policy.');\n\tlines.push('!.gitignore');\n\tif (sortedSensitive.length > 0) {\n\t\tlines.push('');\n\t\tlines.push('# sensitive files — never commit even if you override the `*` above.');\n\t\tfor (const p of sortedSensitive) lines.push(p);\n\t}\n\tlines.push('');\n\tlines.push(userBlock !== null ? userBlock : DEFAULT_USER_BLOCK);\n\treturn lines.join('\\n') + '\\n';\n};\n\n/**\n * Write the gitignore. Idempotent via `emitOne`'s no-touch path.\n */\nexport const writeGitignore = (\n\tinput: GitignoreInput,\n): Effect.Effect<void, CodegenWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst existing = yield* fs.readFileString(input.path).pipe(\n\t\t\tEffect.match({\n\t\t\t\tonSuccess: (text) => text,\n\t\t\t\tonFailure: () => null,\n\t\t\t}),\n\t\t);\n\t\tconst content = composeGitignore(existing, input);\n\t\tyield* emitOne({\n\t\t\tpath: input.path,\n\t\t\tcontent,\n\t\t\tmode: NON_SENSITIVE_FILE_MODE,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(e) =>\n\t\t\t\t\tnew CodegenWriteFailed({\n\t\t\t\t\t\toutputPath: input.path,\n\t\t\t\t\t\tstage: 'gitignore',\n\t\t\t\t\t\tcause: e,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t}).pipe(\n\t\tEffect.withSpan('codegen.writeGitignore', {\n\t\t\tattributes: { 'codegen.path': input.path },\n\t\t}),\n\t);\n\nconst extractUserBlock = (text: string): string | null => {\n\tconst startIdx = text.indexOf(USER_BLOCK_START);\n\tconst endIdx = text.indexOf(USER_BLOCK_END);\n\tif (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;\n\t// Include both markers in the returned block.\n\tconst endLineEnd = text.indexOf('\\n', endIdx);\n\tconst stop = endLineEnd === -1 ? text.length : endLineEnd;\n\treturn text.slice(startIdx, stop);\n};\n"],"mappings":";;;;AA0BA,MAAM,mBAAmB;AACzB,MAAM,iBAAiB;AAEvB,MAAM,qBAAqB,GAAG,iBAAiB,IAAI;AAEnD,MAAM,SAAS;CACd;CACA;CACA;CACA;CACA;CACA,CAAC,KAAK,KAAK;;;;;AAaZ,MAAa,oBAAoB,UAAyB,UAAkC;CAC3F,MAAM,YAAY,aAAa,OAAO,iBAAiB,SAAS,GAAG;CACnE,MAAM,kBAAkB,CAAC,GAAG,MAAM,eAAe,CAAC,MAAM;CACxD,MAAM,QAAuB,EAAE;AAC/B,OAAM,KAAK,OAAO;AAClB,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,uDAAuD;AAClE,OAAM,KAAK,IAAI;AACf,OAAM,KAAK,gEAAgE;AAC3E,OAAM,KAAK,cAAc;AACzB,KAAI,gBAAgB,SAAS,GAAG;AAC/B,QAAM,KAAK,GAAG;AACd,QAAM,KAAK,uEAAuE;AAClF,OAAK,MAAM,KAAK,gBAAiB,OAAM,KAAK,EAAE;;AAE/C,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,cAAc,OAAO,YAAY,mBAAmB;AAC/D,QAAO,MAAM,KAAK,KAAK,GAAG;;;;;AAM3B,MAAa,kBACZ,UAEA,OAAO,IAAI,aAAa;CAQvB,MAAM,UAAU,iBAAiB,QANT,OADN,WAAW,YACF,eAAe,MAAM,KAAK,CAAC,KACrD,OAAO,MAAM;EACZ,YAAY,SAAS;EACrB,iBAAiB;EACjB,CAAC,CACF,EAC0C,MAAM;AACjD,QAAO,QAAQ;EACd,MAAM,MAAM;EACZ;EACA,MAAA;EACA,CAAC,CAAC,KACF,OAAO,UACL,MACA,IAAI,mBAAmB;EACtB,YAAY,MAAM;EAClB,OAAO;EACP,OAAO;EACP,CAAC,CACH,CACD;EACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY,EAAE,gBAAgB,MAAM,MAAM,EAC1C,CAAC,CACF;AAEF,MAAM,oBAAoB,SAAgC;CACzD,MAAM,WAAW,KAAK,QAAQ,iBAAiB;CAC/C,MAAM,SAAS,KAAK,QAAQ,eAAe;AAC3C,KAAI,aAAa,MAAM,WAAW,MAAM,SAAS,SAAU,QAAO;CAElE,MAAM,aAAa,KAAK,QAAQ,MAAM,OAAO;CAC7C,MAAM,OAAO,eAAe,KAAK,KAAK,SAAS;AAC/C,QAAO,KAAK,MAAM,UAAU,KAAK"}
+{"version":3,"file":"gitignore.mjs","names":[],"sources":["../../../src/orchestrators/codegen/gitignore.ts"],"sourcesContent":["// .gitignore emission for the codegen output directory.\n//\n// Distilled-doc §\"Boundary helpers\": \"A `.gitignore` inside the\n// output directory, covering sensitive emitted files by default and\n// preserving user customizations.\" Two design points:\n//\n//   1. The entire output directory is engine-managed and the\n//      pragmatic default is \"ignore everything emitted here\". The\n//      `*` line lives at the top of the file with a comment\n//      explaining the policy.\n//   2. Sensitive files get an explicit second mention so the\n//      `.gitignore` reads as documentation in addition to enforcing\n//      the policy.\n//   3. User customisations land in a tracked `# user:` block — any\n//      content the user adds between the `# user:` and `# /user:`\n//      markers is preserved verbatim across re-emits.\n//\n// The `.gitignore` is emitted with the same per-file atomic writer as\n// the rest of the codegen tree.\n\nimport { Effect, FileSystem } from 'effect';\n\nimport { emitOne } from './emit.ts';\nimport { CodegenWriteFailed } from './errors.ts';\nimport { NON_SENSITIVE_DIR_MODE, NON_SENSITIVE_FILE_MODE } from './permissions.ts';\n\nconst USER_BLOCK_START = '# user: customisations below preserved across re-emits';\nconst USER_BLOCK_END = '# /user: do not edit below this line';\n\nconst DEFAULT_USER_BLOCK = `${USER_BLOCK_START}\\n${USER_BLOCK_END}`;\n\nconst HEADER = [\n\t'# THIS FILE IS AUTO-GENERATED BY @mysten/devstack.',\n\t'# The codegen output directory is engine-managed; the whole tree is',\n\t'# ignored from git by default. Sensitive files have an explicit mention',\n\t'# below for documentation. Add user customisations inside the `# user:`',\n\t'# block; the rest is rewritten on every emit cycle.',\n].join('\\n');\n\nexport interface GitignoreInput {\n\treadonly path: string;\n\treadonly parentMode?: number;\n\t/** Relative paths inside the output dir that are sensitive — get\n\t *  an explicit gitignore line. Sorted lexicographically. */\n\treadonly sensitivePaths: ReadonlyArray<string>;\n}\n\n/**\n * Compose the gitignore content, preserving any user customisations\n * between the `# user:` markers in any existing file at `path`.\n */\nexport const composeGitignore = (existing: string | null, input: GitignoreInput): string => {\n\tconst userBlock = existing !== null ? extractUserBlock(existing) : null;\n\tconst sortedSensitive = [...input.sensitivePaths].sort();\n\tconst lines: Array<string> = [];\n\tlines.push(HEADER);\n\tlines.push('');\n\tlines.push('# default policy: ignore the whole output directory.');\n\tlines.push('*');\n\tlines.push('# but keep this .gitignore tracked so cloners get the policy.');\n\tlines.push('!.gitignore');\n\tif (sortedSensitive.length > 0) {\n\t\tlines.push('');\n\t\tlines.push('# sensitive files — never commit even if you override the `*` above.');\n\t\tfor (const p of sortedSensitive) lines.push(p);\n\t}\n\tlines.push('');\n\tlines.push(userBlock !== null ? userBlock : DEFAULT_USER_BLOCK);\n\treturn lines.join('\\n') + '\\n';\n};\n\n/**\n * Write the gitignore. Idempotent via `emitOne`'s no-touch path.\n */\nexport const writeGitignore = (\n\tinput: GitignoreInput,\n): Effect.Effect<void, CodegenWriteFailed, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst existing = yield* fs.readFileString(input.path).pipe(\n\t\t\tEffect.match({\n\t\t\t\tonSuccess: (text) => text,\n\t\t\t\tonFailure: () => null,\n\t\t\t}),\n\t\t);\n\t\tconst content = composeGitignore(existing, input);\n\t\tyield* emitOne({\n\t\t\tpath: input.path,\n\t\t\tcontent,\n\t\t\tmode: NON_SENSITIVE_FILE_MODE,\n\t\t\tparentMode: input.parentMode ?? NON_SENSITIVE_DIR_MODE,\n\t\t}).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(e) =>\n\t\t\t\t\tnew CodegenWriteFailed({\n\t\t\t\t\t\toutputPath: input.path,\n\t\t\t\t\t\tstage: 'gitignore',\n\t\t\t\t\t\tcause: e,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t}).pipe(\n\t\tEffect.withSpan('codegen.writeGitignore', {\n\t\t\tattributes: { 'codegen.path': input.path },\n\t\t}),\n\t);\n\nconst extractUserBlock = (text: string): string | null => {\n\tconst startIdx = text.indexOf(USER_BLOCK_START);\n\tconst endIdx = text.indexOf(USER_BLOCK_END);\n\tif (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;\n\t// Include both markers in the returned block.\n\tconst endLineEnd = text.indexOf('\\n', endIdx);\n\tconst stop = endLineEnd === -1 ? text.length : endLineEnd;\n\treturn text.slice(startIdx, stop);\n};\n"],"mappings":";;;;;AA0BA,MAAM,mBAAmB;AACzB,MAAM,iBAAiB;AAEvB,MAAM,qBAAqB,GAAG,iBAAiB,IAAI;AAEnD,MAAM,SAAS;CACd;CACA;CACA;CACA;CACA;CACA,CAAC,KAAK,KAAK;;;;;AAcZ,MAAa,oBAAoB,UAAyB,UAAkC;CAC3F,MAAM,YAAY,aAAa,OAAO,iBAAiB,SAAS,GAAG;CACnE,MAAM,kBAAkB,CAAC,GAAG,MAAM,eAAe,CAAC,MAAM;CACxD,MAAM,QAAuB,EAAE;AAC/B,OAAM,KAAK,OAAO;AAClB,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,uDAAuD;AAClE,OAAM,KAAK,IAAI;AACf,OAAM,KAAK,gEAAgE;AAC3E,OAAM,KAAK,cAAc;AACzB,KAAI,gBAAgB,SAAS,GAAG;AAC/B,QAAM,KAAK,GAAG;AACd,QAAM,KAAK,uEAAuE;AAClF,OAAK,MAAM,KAAK,gBAAiB,OAAM,KAAK,EAAE;;AAE/C,OAAM,KAAK,GAAG;AACd,OAAM,KAAK,cAAc,OAAO,YAAY,mBAAmB;AAC/D,QAAO,MAAM,KAAK,KAAK,GAAG;;;;;AAM3B,MAAa,kBACZ,UAEA,OAAO,IAAI,aAAa;CAQvB,MAAM,UAAU,iBAAiB,QANT,OADN,WAAW,YACF,eAAe,MAAM,KAAK,CAAC,KACrD,OAAO,MAAM;EACZ,YAAY,SAAS;EACrB,iBAAiB;EACjB,CAAC,CACF,EAC0C,MAAM;AACjD,QAAO,QAAQ;EACd,MAAM,MAAM;EACZ;EACA,MAAA;EACA,YAAY,MAAM,cAAA;EAClB,CAAC,CAAC,KACF,OAAO,UACL,MACA,IAAI,mBAAmB;EACtB,YAAY,MAAM;EAClB,OAAO;EACP,OAAO;EACP,CAAC,CACH,CACD;EACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EACzC,YAAY,EAAE,gBAAgB,MAAM,MAAM,EAC1C,CAAC,CACF;AAEF,MAAM,oBAAoB,SAAgC;CACzD,MAAM,WAAW,KAAK,QAAQ,iBAAiB;CAC/C,MAAM,SAAS,KAAK,QAAQ,eAAe;AAC3C,KAAI,aAAa,MAAM,WAAW,MAAM,SAAS,SAAU,QAAO;CAElE,MAAM,aAAa,KAAK,QAAQ,MAAM,OAAO;CAC7C,MAAM,OAAO,eAAe,KAAK,KAAK,SAAS;AAC/C,QAAO,KAAK,MAAM,UAAU,KAAK"}

package/dist/orchestrators/codegen/output-location.mjs

@@ -0,0 +1,41 @@
+import { isAbsolute, resolve } from "node:path";
+//#region src/orchestrators/codegen/output-location.ts
+/** Default primary-stack output dir (relative to `appRoot`). */
+const PRIMARY_OUTPUT_SUBPATH = "src/generated";
+/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated` for a
+*  secondary stack — sibling of that stack's manifest. */
+const secondaryOutputDir = (appRoot, stack) => resolve(appRoot, ".devstack", "stacks", stack, "generated");
+/**
+* Resolve the codegen output location for a stack. See the module
+* header for the rule. Pure — same inputs always yield the same
+* absolute paths.
+*
+* Precedence:
+*   1. Explicit `defineDevstack({ codegen.outputDir })` → honored
+*      verbatim (relative → resolved against `appRoot`). The explicit
+*      `stackSubdir` rides along.
+*   2. Primary stack (`effectiveStack === primaryStack`, or no
+*      `primaryStack` declared) → `<appRoot>/src/generated`,
+*      `stackSubdir: null`.
+*   3. Secondary stack → `<appRoot>/.devstack/stacks/<effectiveStack>/generated`,
+*      `stackSubdir: null`.
+*/
+const resolveCodegenOutput = (input) => {
+	const { appRoot, effectiveStack, primaryStack } = input;
+	const explicitStackSubdir = input.explicitStackSubdir ?? null;
+	if (input.explicitOutputDir !== void 0) {
+		const target = input.explicitOutputDir;
+		return {
+			outputDir: isAbsolute(target) ? target : resolve(appRoot, target),
+			stackSubdir: explicitStackSubdir
+		};
+	}
+	return {
+		outputDir: effectiveStack === (primaryStack ?? effectiveStack) ? resolve(appRoot, PRIMARY_OUTPUT_SUBPATH) : secondaryOutputDir(appRoot, effectiveStack),
+		stackSubdir: null
+	};
+};
+//#endregion
+export { resolveCodegenOutput };
+
+//# sourceMappingURL=output-location.mjs.map

package/dist/orchestrators/codegen/output-location.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-location.mjs","names":[],"sources":["../../../src/orchestrators/codegen/output-location.ts"],"sourcesContent":["// Per-stack codegen output-location resolver.\n//\n// notes/per-stack-codegen-design.md §\"Output-location rule\": two stacks\n// of the same app must not emit Move codegen into the SAME\n// `src/generated/` dir — the second stack's `codegen.emitted` would\n// clobber the first's package-id / wallet-pair-token literals and break\n// the already-running app. This pure function is the single decision\n// point: it maps (appRoot, effective stack, primary stack) → the output\n// dir codegen owns for THIS stack.\n//\n//   - Primary stack (`effectiveStack === primaryStack`, no explicit\n//     `--stack`/`$DEVSTACK_STACK` override) → `<appRoot>/src/generated`\n//     (canonical, unchanged, committed-ignored).\n//   - Secondary stack (`test`/`e2e`/`demo`/...) →\n//     `<appRoot>/.devstack/stacks/<effectiveStack>/generated` — a\n//     sibling of that stack's manifest at\n//     `.devstack/stacks/<stack>/manifest.json`, already gitignored +\n//     tsconfig-excluded.\n//   - An app that sets `codegen.outputDir` / `codegen.stackSubdir`\n//     explicitly (`defineDevstack({ codegen })`) keeps that behavior\n//     verbatim (back-compat escape hatch); per-stack isolation is then\n//     the app's responsibility.\n//\n// The decision is made ONCE here, at the boot seam where both the\n// primary and effective stack names are in scope, and the resolved\n// absolute `outputDir` is then recorded in the per-stack manifest\n// (`codegen.generatedDir`) so the reader (the Vite plugin) consults the\n// SAME location the writer chose — read and write are gated by one\n// decision, not two. Pure + unit-testable; no `process.env`, no I/O.\n\nimport { isAbsolute, resolve } from 'node:path';\n\nexport interface ResolveCodegenOutputInput {\n\t/** The user application root — codegen output is resolved against\n\t *  it. */\n\treadonly appRoot: string;\n\t/** The stack the supervisor is actually running (the resolved\n\t *  identity's stack: explicit `--stack`/`$DEVSTACK_STACK` >\n\t *  `config.stackName` > inferred). */\n\treadonly effectiveStack: string;\n\t/** The config's declared `stackName` (`stack.options.stackName`) —\n\t *  the primary stack. `undefined` when the config declares none —\n\t *  then there is no override to diverge from, so the run is treated\n\t *  as primary. */\n\treadonly primaryStack: string | undefined;\n\t/** Explicit `defineDevstack({ codegen: { outputDir } })` value, if\n\t *  the app pinned one. Honored verbatim (back-compat) — relative\n\t *  paths resolve against `appRoot`. */\n\treadonly explicitOutputDir?: string | undefined;\n\t/** Explicit `defineDevstack({ codegen: { stackSubdir } })` value, if\n\t *  the app pinned one. Passed through unchanged. */\n\treadonly explicitStackSubdir?: string | null | undefined;\n}\n\nexport interface ResolvedCodegenOutput {\n\t/** Absolute path to the directory codegen owns and overwrites for\n\t *  THIS stack. Recorded in the manifest as `codegen.generatedDir`. */\n\treadonly outputDir: string;\n\t/** Per-stack subdirectory under `outputDir`, threaded through to\n\t *  `CodegenRoot.stackSubdir` unchanged. `null` for the\n\t *  primary/secondary default rules (the `.devstack/stacks/<stack>`\n\t *  location already isolates per stack, so no extra subdir is\n\t *  needed); only an explicit `defineDevstack({ codegen.stackSubdir })`\n\t *  populates it. */\n\treadonly stackSubdir: string | null;\n}\n\n/** Default primary-stack output dir (relative to `appRoot`). */\nconst PRIMARY_OUTPUT_SUBPATH = 'src/generated';\n\n/** Resolve `<appRoot>/.devstack/stacks/<stack>/generated` for a\n *  secondary stack — sibling of that stack's manifest. */\nconst secondaryOutputDir = (appRoot: string, stack: string): string =>\n\tresolve(appRoot, '.devstack', 'stacks', stack, 'generated');\n\n/**\n * Resolve the codegen output location for a stack. See the module\n * header for the rule. Pure — same inputs always yield the same\n * absolute paths.\n *\n * Precedence:\n *   1. Explicit `defineDevstack({ codegen.outputDir })` → honored\n *      verbatim (relative → resolved against `appRoot`). The explicit\n *      `stackSubdir` rides along.\n *   2. Primary stack (`effectiveStack === primaryStack`, or no\n *      `primaryStack` declared) → `<appRoot>/src/generated`,\n *      `stackSubdir: null`.\n *   3. Secondary stack → `<appRoot>/.devstack/stacks/<effectiveStack>/generated`,\n *      `stackSubdir: null`.\n */\nexport const resolveCodegenOutput = (input: ResolveCodegenOutputInput): ResolvedCodegenOutput => {\n\tconst { appRoot, effectiveStack, primaryStack } = input;\n\tconst explicitStackSubdir = input.explicitStackSubdir ?? null;\n\n\t// (1) Explicit override wins — back-compat escape hatch. Per-stack\n\t// isolation is the app's responsibility once it pins `outputDir`.\n\tif (input.explicitOutputDir !== undefined) {\n\t\tconst target = input.explicitOutputDir;\n\t\treturn {\n\t\t\toutputDir: isAbsolute(target) ? target : resolve(appRoot, target),\n\t\t\tstackSubdir: explicitStackSubdir,\n\t\t};\n\t}\n\n\t// `primaryStack === undefined` means the config declared no `stackName`,\n\t// so there is no config value for `effectiveStack` to diverge from —\n\t// the run is the primary run by definition (it falls through to the\n\t// inferred/default stack with no explicit override). Collapse it to\n\t// `effectiveStack` so the equality below reads `true`.\n\tconst isPrimary = effectiveStack === (primaryStack ?? effectiveStack);\n\n\t// (2) Primary → canonical `src/generated`. (3) Secondary → per-stack\n\t// `.devstack/stacks/<stack>/generated`. Neither uses `stackSubdir`\n\t// (the `.devstack` path already isolates per stack); an explicit\n\t// `stackSubdir` only rides the explicit-outputDir branch above.\n\treturn {\n\t\toutputDir: isPrimary\n\t\t\t? resolve(appRoot, PRIMARY_OUTPUT_SUBPATH)\n\t\t\t: secondaryOutputDir(appRoot, effectiveStack),\n\t\tstackSubdir: null,\n\t};\n};\n"],"mappings":";;;AAoEA,MAAM,yBAAyB;;;AAI/B,MAAM,sBAAsB,SAAiB,UAC5C,QAAQ,SAAS,aAAa,UAAU,OAAO,YAAY;;;;;;;;;;;;;;;;AAiB5D,MAAa,wBAAwB,UAA4D;CAChG,MAAM,EAAE,SAAS,gBAAgB,iBAAiB;CAClD,MAAM,sBAAsB,MAAM,uBAAuB;AAIzD,KAAI,MAAM,sBAAsB,KAAA,GAAW;EAC1C,MAAM,SAAS,MAAM;AACrB,SAAO;GACN,WAAW,WAAW,OAAO,GAAG,SAAS,QAAQ,SAAS,OAAO;GACjE,aAAa;GACb;;AAcF,QAAO;EACN,WAPiB,oBAAoB,gBAAgB,kBAQlD,QAAQ,SAAS,uBAAuB,GACxC,mBAAmB,SAAS,eAAe;EAC9C,aAAa;EACb"}

package/dist/orchestrators/codegen/paths.d.mts

@@ -1 +1 @@
-import { Context, Layer, Path } from "effect";
+import { Context, Effect, Layer, Path } from "effect";

package/dist/orchestrators/codegen/paths.mjs

@@ -1,9 +1,29 @@
+import { CodegenPathConflict } from "./errors.mjs";
 import { Context, Effect, Layer, Path } from "effect";
 //#region src/orchestrators/codegen/paths.ts
-var CodegenRoot = class extends Context.Service()("@devstack-rewrite/orchestrator/CodegenRoot") {};
+/** Guard plugin-authored `CodegenableDecl.outputPath` against `..`
+*  traversal and absolute paths. Fails with a typed
+*  `CodegenPathConflict({kind:'non-relative'})` — defense-in-depth
+*  for the file-layout invariants. Called once inside `buildAt` so
+*  both the root bundle and any `withRoot`-rebased view enforce the
+*  same `..`-rejecting `resolve` discipline.
+*
+*  POSIX-only: devstack runs on POSIX filesystems (substrate paths
+*  are POSIX-shaped throughout), so this check intentionally inspects
+*  only `/`-rooted absolutes and the `..` substring. A Windows-style
+*  `'foo/bar\\..\\baz'` would slip past — that's accepted because
+*  devstack never executes on a Windows runtime.
+*
+*  STYLE_GUIDE §2 rule 5 — orchestrator failures are typed. */
+const assertRelativeCodegenOutputPath = (outputPath) => outputPath.includes("..") || outputPath.startsWith("/") ? Effect.fail(new CodegenPathConflict({
+	kind: "non-relative",
+	outputPath,
+	emitters: []
+})) : Effect.void;
+var CodegenRoot = class extends Context.Service()("@devstack/orchestrator/CodegenRoot") {};
 /** Build a `CodegenRoot` layer pinned to a literal path. */
 const layerCodegenRoot = (root) => Layer.succeed(CodegenRoot)(root);
-var CodegenPathsService = class extends Context.Service()("@devstack-rewrite/orchestrator/CodegenPaths") {};
+var CodegenPathsService = class extends Context.Service()("@devstack/orchestrator/CodegenPaths") {};
 /**
 * Materialize the resolver from `CodegenRoot` + Effect's `Path`
 * service. Stack subdir, if present, is appended:
@@ -13,19 +33,25 @@ const layerCodegenPaths = Layer.effect(CodegenPathsService, Effect.gen(function*
 	const root = yield* CodegenRoot;
 	const path = yield* Path.Path;
 	const outputDir = root.stackSubdir ? path.join(root.outputDir, root.stackSubdir) : root.outputDir;
-	const bindingsDir = path.join(outputDir, "bindings");
-	const resolve = (outputPath) => {
-		if (outputPath.includes("..") || outputPath.startsWith("/")) throw new Error(`codegen.outputPath must be a relative path without '..'; got '${outputPath}'`);
-		return path.join(outputDir, outputPath);
+	const codegenLockFile = `${outputDir}.codegen.lock`;
+	const buildAt = (atRoot) => {
+		const bindingsDir = path.join(atRoot, "bindings");
+		const resolve = (outputPath) => Effect.gen(function* () {
+			yield* assertRelativeCodegenOutputPath(outputPath);
+			return path.join(atRoot, outputPath);
+		});
+		const resolveBindingsPackage = (packageName) => path.join(bindingsDir, packageName);
+		return {
+			outputDir: atRoot,
+			gitignoreFile: path.join(atRoot, ".gitignore"),
+			bindingsDir,
+			codegenLockFile,
+			resolve,
+			resolveBindingsPackage,
+			withRoot: (newRoot) => buildAt(newRoot)
+		};
 	};
-	const resolveBindingsPackage = (packageName) => path.join(bindingsDir, packageName);
-	return CodegenPathsService.of({
-		outputDir,
-		gitignoreFile: path.join(outputDir, ".gitignore"),
-		bindingsDir,
-		resolve,
-		resolveBindingsPackage
-	});
+	return CodegenPathsService.of(buildAt(outputDir));
 }));
 //#endregion
 export { CodegenPathsService, layerCodegenPaths, layerCodegenRoot };

package/dist/orchestrators/codegen/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/orchestrators/codegen/paths.ts"],"sourcesContent":["// Codegen output-path layout.\n//\n// Distilled-doc § \"All outputs land under a single user-chosen\n// directory (default `./src/generated/`)\" + §\"Stable output paths\".\n// One file owns the layout so emitters never assemble paths by hand.\n//\n// Default root is `<appRoot>/src/generated/`. Tests and parallel\n// stacks pin a per-test root; the substrate's `RuntimeRoot` is for\n// engine-private state (~/.devstack/...), NOT for codegen output.\n// Codegen output lives in the USER's source tree.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\n/**\n * Codegen output root — the directory codegen owns and overwrites.\n * Pinned at boot time from the user's `defineDevstack` options\n * (default `./src/generated/` resolved against the app's cwd).\n *\n * Held as a service so emitters can yield it without a function\n * argument; mirrors the substrate's `RuntimeRoot` pattern.\n */\nexport interface CodegenRootShape {\n\t/** Absolute path to the output directory. The orchestrator\n\t *  manages it; the user never writes here. */\n\treadonly outputDir: string;\n\t/** Optional per-stack subdirectory under `outputDir`. When set,\n\t *  parallel stacks emit into sibling directories under the same\n\t *  output root (distilled-doc §\"per-stack subdirectory\"). */\n\treadonly stackSubdir: string | null;\n}\n\nexport class CodegenRoot extends Context.Service<CodegenRoot, CodegenRootShape>()(\n\t'@devstack-rewrite/orchestrator/CodegenRoot',\n) {}\n\n/** Build a `CodegenRoot` layer pinned to a literal path. */\nexport const layerCodegenRoot = (root: CodegenRootShape): Layer.Layer<CodegenRoot> =>\n\tLayer.succeed(CodegenRoot)(root);\n\n/** Closed bundle the resolver returns. Mirrors substrate `StackPaths`. */\nexport interface CodegenPaths {\n\t/** The directory the orchestrator emits into (after applying\n\t *  per-stack subdirectory if configured). The watcher MUST\n\t *  exclude this directory. */\n\treadonly outputDir: string;\n\t/** Path to the `.gitignore` inside `outputDir`. Written every\n\t *  emit (the dir is gitignored). */\n\treadonly gitignoreFile: string;\n\t/** Subtree where Move-to-TS bindings land. */\n\treadonly bindingsDir: string;\n\t/** Helper: resolve an emitter's `outputPath` (e.g. `sui/network.ts`)\n\t *  against the output root. */\n\treadonly resolve: (outputPath: string) => string;\n\t/** Helper: resolve a per-package bindings subtree path. */\n\treadonly resolveBindingsPackage: (packageName: string) => string;\n}\n\nexport class CodegenPathsService extends Context.Service<CodegenPathsService, CodegenPaths>()(\n\t'@devstack-rewrite/orchestrator/CodegenPaths',\n) {}\n\n/**\n * Materialize the resolver from `CodegenRoot` + Effect's `Path`\n * service. Stack subdir, if present, is appended:\n *   `<outputDir>` or `<outputDir>/<stackSubdir>`.\n */\nexport const layerCodegenPaths: Layer.Layer<CodegenPathsService, never, CodegenRoot | Path.Path> =\n\tLayer.effect(\n\t\tCodegenPathsService,\n\t\tEffect.gen(function* () {\n\t\t\tconst root = yield* CodegenRoot;\n\t\t\tconst path = yield* Path.Path;\n\t\t\tconst outputDir = root.stackSubdir\n\t\t\t\t? path.join(root.outputDir, root.stackSubdir)\n\t\t\t\t: root.outputDir;\n\t\t\tconst bindingsDir = path.join(outputDir, 'bindings');\n\t\t\tconst resolve = (outputPath: string): string => {\n\t\t\t\t// Defense-in-depth: refuse `..` traversal so an emitter\n\t\t\t\t// can't write outside its declared output dir. The\n\t\t\t\t// declared `CodegenableDecl.outputPath` is plugin-authored\n\t\t\t\t// and trusted but the check costs nothing.\n\t\t\t\tif (outputPath.includes('..') || outputPath.startsWith('/')) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`codegen.outputPath must be a relative path without '..'; got '${outputPath}'`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn path.join(outputDir, outputPath);\n\t\t\t};\n\t\t\tconst resolveBindingsPackage = (packageName: string): string =>\n\t\t\t\tpath.join(bindingsDir, packageName);\n\t\t\treturn CodegenPathsService.of({\n\t\t\t\toutputDir,\n\t\t\t\tgitignoreFile: path.join(outputDir, '.gitignore'),\n\t\t\t\tbindingsDir,\n\t\t\t\tresolve,\n\t\t\t\tresolveBindingsPackage,\n\t\t\t});\n\t\t}),\n\t);\n"],"mappings":";;AA+BA,IAAa,cAAb,cAAiC,QAAQ,SAAwC,CAChF,6CACA,CAAC;;AAGF,MAAa,oBAAoB,SAChC,MAAM,QAAQ,YAAY,CAAC,KAAK;AAoBjC,IAAa,sBAAb,cAAyC,QAAQ,SAA4C,CAC5F,8CACA,CAAC;;;;;;AAOF,MAAa,oBACZ,MAAM,OACL,qBACA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;CACpB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,cACpB,KAAK,KAAK,KAAK,WAAW,KAAK,YAAY,GAC3C,KAAK;CACR,MAAM,cAAc,KAAK,KAAK,WAAW,WAAW;CACpD,MAAM,WAAW,eAA+B;AAK/C,MAAI,WAAW,SAAS,KAAK,IAAI,WAAW,WAAW,IAAI,CAC1D,OAAM,IAAI,MACT,iEAAiE,WAAW,GAC5E;AAEF,SAAO,KAAK,KAAK,WAAW,WAAW;;CAExC,MAAM,0BAA0B,gBAC/B,KAAK,KAAK,aAAa,YAAY;AACpC,QAAO,oBAAoB,GAAG;EAC7B;EACA,eAAe,KAAK,KAAK,WAAW,aAAa;EACjD;EACA;EACA;EACA,CAAC;EACD,CACF"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../../../src/orchestrators/codegen/paths.ts"],"sourcesContent":["// Codegen output-path layout.\n//\n// Distilled-doc § \"All outputs land under a single user-chosen\n// directory (default `./src/generated/`)\" + §\"Stable output paths\".\n// One file owns the layout so emitters never assemble paths by hand.\n//\n// Default root is `<appRoot>/src/generated/`. Tests and parallel\n// stacks pin a per-test root; the substrate's `RuntimeRoot` is for\n// engine-private state (~/.devstack/...), NOT for codegen output.\n// Codegen output lives in the USER's source tree.\n\nimport { Context, Effect, Layer, Path } from 'effect';\n\nimport { CodegenPathConflict } from './errors.ts';\n\n/** Guard plugin-authored `CodegenableDecl.outputPath` against `..`\n *  traversal and absolute paths. Fails with a typed\n *  `CodegenPathConflict({kind:'non-relative'})` — defense-in-depth\n *  for the file-layout invariants. Called once inside `buildAt` so\n *  both the root bundle and any `withRoot`-rebased view enforce the\n *  same `..`-rejecting `resolve` discipline.\n *\n *  POSIX-only: devstack runs on POSIX filesystems (substrate paths\n *  are POSIX-shaped throughout), so this check intentionally inspects\n *  only `/`-rooted absolutes and the `..` substring. A Windows-style\n *  `'foo/bar\\\\..\\\\baz'` would slip past — that's accepted because\n *  devstack never executes on a Windows runtime.\n *\n *  STYLE_GUIDE §2 rule 5 — orchestrator failures are typed. */\nexport const assertRelativeCodegenOutputPath = (\n\toutputPath: string,\n): Effect.Effect<void, CodegenPathConflict> =>\n\toutputPath.includes('..') || outputPath.startsWith('/')\n\t\t? Effect.fail(\n\t\t\t\tnew CodegenPathConflict({\n\t\t\t\t\tkind: 'non-relative',\n\t\t\t\t\toutputPath,\n\t\t\t\t\temitters: [],\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.void;\n\n/**\n * Codegen output root — the directory codegen owns and overwrites.\n * Pinned at boot time from the user's `defineDevstack` options\n * (default `./src/generated/` resolved against the app's cwd).\n *\n * Held as a service so emitters can yield it without a function\n * argument; mirrors the substrate's `RuntimeRoot` pattern.\n */\nexport interface CodegenRootShape {\n\t/** Absolute path to the output directory. The orchestrator\n\t *  manages it; the user never writes here. */\n\treadonly outputDir: string;\n\t/** Optional per-stack subdirectory under `outputDir`. When set,\n\t *  parallel stacks emit into sibling directories under the same\n\t *  output root (distilled-doc §\"per-stack subdirectory\"). */\n\treadonly stackSubdir: string | null;\n}\n\nexport class CodegenRoot extends Context.Service<CodegenRoot, CodegenRootShape>()(\n\t'@devstack/orchestrator/CodegenRoot',\n) {}\n\n/** Build a `CodegenRoot` layer pinned to a literal path. */\nexport const layerCodegenRoot = (root: CodegenRootShape): Layer.Layer<CodegenRoot> =>\n\tLayer.succeed(CodegenRoot)(root);\n\n/** Closed bundle the resolver returns. Mirrors substrate `StackPaths`. */\nexport interface CodegenPaths {\n\t/** The directory the orchestrator emits into (after applying\n\t *  per-stack subdirectory if configured). The watcher MUST\n\t *  exclude this directory. */\n\treadonly outputDir: string;\n\t/** Path to the `.gitignore` inside `outputDir`. Written every\n\t *  emit (the dir is gitignored). */\n\treadonly gitignoreFile: string;\n\t/** Subtree where Move-to-TS bindings land. */\n\treadonly bindingsDir: string;\n\t/** Per-process lock file gating `runEmitCycle`. Sibling to\n\t *  `outputDir` so concurrent invocations (e.g. CLI direct-callers\n\t *  racing the supervisor) serialize cleanly without blocking the\n\t *  short-section substrate `stack.lock`. Codegen cycles can be\n\t *  file-system heavy (multi-emitter, Move-bindings compilation);\n\t *  the substrate lock is reserved for short sections per the\n\t *  cross-process safety protocol. */\n\treadonly codegenLockFile: string;\n\t/** Helper: resolve an emitter's `outputPath` (e.g. `sui/network.ts`)\n\t *  against the output root. Fails with `CodegenPathConflict({kind:\n\t *  'non-relative'})` if the supplied path escapes the root. */\n\treadonly resolve: (outputPath: string) => Effect.Effect<string, CodegenPathConflict>;\n\t/** Helper: resolve a per-package bindings subtree path. */\n\treadonly resolveBindingsPackage: (packageName: string) => string;\n\t/** Data-driven rebase: re-root the entire bundle at `newRoot`.\n\t *  Preserves the layout (bindings under `<root>/bindings`, gitignore\n\t *  at `<root>/.gitignore`) and the `..`-rejecting `resolve`\n\t *  discipline; only the prefix changes. Used by the stage-and-swap\n\t *  build to redirect the emit pipeline at the staging directory\n\t *  WITHOUT string-surgery in the caller.\n\t *\n\t *  Note: `codegenLockFile` is preserved verbatim — the lock is\n\t *  acquired ONCE outside the staging build, so the rebased view\n\t *  must still name the real lock path. */\n\treadonly withRoot: (newRoot: string) => CodegenPaths;\n}\n\nexport class CodegenPathsService extends Context.Service<CodegenPathsService, CodegenPaths>()(\n\t'@devstack/orchestrator/CodegenPaths',\n) {}\n\n/**\n * Materialize the resolver from `CodegenRoot` + Effect's `Path`\n * service. Stack subdir, if present, is appended:\n *   `<outputDir>` or `<outputDir>/<stackSubdir>`.\n */\nexport const layerCodegenPaths: Layer.Layer<CodegenPathsService, never, CodegenRoot | Path.Path> =\n\tLayer.effect(\n\t\tCodegenPathsService,\n\t\tEffect.gen(function* () {\n\t\t\tconst root = yield* CodegenRoot;\n\t\t\tconst path = yield* Path.Path;\n\t\t\tconst outputDir = root.stackSubdir\n\t\t\t\t? path.join(root.outputDir, root.stackSubdir)\n\t\t\t\t: root.outputDir;\n\t\t\t// Sibling of `outputDir` (NOT inside it) so the stage-and-swap\n\t\t\t// rename never sees the lock file as part of the output tree.\n\t\t\t// Captured once at boot — `withRoot` re-roots the rest of the\n\t\t\t// bundle but preserves the original lock path so the rebased\n\t\t\t// view names the real cross-process lock (the lock is acquired\n\t\t\t// ONCE outside the staging build).\n\t\t\tconst codegenLockFile = `${outputDir}.codegen.lock`;\n\t\t\tconst buildAt = (atRoot: string): CodegenPaths => {\n\t\t\t\tconst bindingsDir = path.join(atRoot, 'bindings');\n\t\t\t\tconst resolve = (outputPath: string): Effect.Effect<string, CodegenPathConflict> =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* assertRelativeCodegenOutputPath(outputPath);\n\t\t\t\t\t\treturn path.join(atRoot, outputPath);\n\t\t\t\t\t});\n\t\t\t\tconst resolveBindingsPackage = (packageName: string): string =>\n\t\t\t\t\tpath.join(bindingsDir, packageName);\n\t\t\t\tconst bundle: CodegenPaths = {\n\t\t\t\t\toutputDir: atRoot,\n\t\t\t\t\tgitignoreFile: path.join(atRoot, '.gitignore'),\n\t\t\t\t\tbindingsDir,\n\t\t\t\t\tcodegenLockFile,\n\t\t\t\t\tresolve,\n\t\t\t\t\tresolveBindingsPackage,\n\t\t\t\t\twithRoot: (newRoot: string) => buildAt(newRoot),\n\t\t\t\t};\n\t\t\t\treturn bundle;\n\t\t\t};\n\t\t\treturn CodegenPathsService.of(buildAt(outputDir));\n\t\t}),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;;;AA6BA,MAAa,mCACZ,eAEA,WAAW,SAAS,KAAK,IAAI,WAAW,WAAW,IAAI,GACpD,OAAO,KACP,IAAI,oBAAoB;CACvB,MAAM;CACN;CACA,UAAU,EAAE;CACZ,CAAC,CACF,GACA,OAAO;AAoBX,IAAa,cAAb,cAAiC,QAAQ,SAAwC,CAChF,qCACA,CAAC;;AAGF,MAAa,oBAAoB,SAChC,MAAM,QAAQ,YAAY,CAAC,KAAK;AAwCjC,IAAa,sBAAb,cAAyC,QAAQ,SAA4C,CAC5F,sCACA,CAAC;;;;;;AAOF,MAAa,oBACZ,MAAM,OACL,qBACA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO;CACpB,MAAM,OAAO,OAAO,KAAK;CACzB,MAAM,YAAY,KAAK,cACpB,KAAK,KAAK,KAAK,WAAW,KAAK,YAAY,GAC3C,KAAK;CAOR,MAAM,kBAAkB,GAAG,UAAU;CACrC,MAAM,WAAW,WAAiC;EACjD,MAAM,cAAc,KAAK,KAAK,QAAQ,WAAW;EACjD,MAAM,WAAW,eAChB,OAAO,IAAI,aAAa;AACvB,UAAO,gCAAgC,WAAW;AAClD,UAAO,KAAK,KAAK,QAAQ,WAAW;IACnC;EACH,MAAM,0BAA0B,gBAC/B,KAAK,KAAK,aAAa,YAAY;AAUpC,SAAO;GARN,WAAW;GACX,eAAe,KAAK,KAAK,QAAQ,aAAa;GAC9C;GACA;GACA;GACA;GACA,WAAW,YAAoB,QAAQ,QAAQ;GAEnC;;AAEd,QAAO,oBAAoB,GAAG,QAAQ,UAAU,CAAC;EAChD,CACF"}

package/dist/orchestrators/codegen/permissions.mjs

@@ -1,6 +1,8 @@
 /** File mode for one codegen contribution. */
 const modeFor = (decl) => decl.sensitive === true ? 384 : 420;
+/** Parent-directory mode given a set of contributions inside it. */
+const dirModeFor = (decls) => decls.some((d) => d.sensitive === true) ? 448 : 493;
 //#endregion
-export { modeFor };
+export { dirModeFor, modeFor };
 
 //# sourceMappingURL=permissions.mjs.map

package/dist/orchestrators/codegen/permissions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.mjs","names":[],"sources":["../../../src/orchestrators/codegen/permissions.ts"],"sourcesContent":["// Permission policy for codegen-emitted files.\n//\n// Distilled-doc § \"Sensitive emitted files have restrictive\n// filesystem permissions, re-applied on every emit (not just on\n// create) to recover from manual chmods\". The orchestrator hands the\n// emit/swap layer the mode it should apply.\n//\n// Two-axis policy:\n//   - `sensitive: true` → 0o600 (rw user only).\n//   - `sensitive: false` → 0o644 (rw user, r world).\n// The parent directory the emit lives in inherits the strictest\n// sensitivity of any file inside it — 0o700 when any file is\n// sensitive, 0o755 otherwise. The orchestrator applies parent mode\n// at swap time, separate from per-file modes.\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nexport const SENSITIVE_FILE_MODE = 0o600;\nexport const NON_SENSITIVE_FILE_MODE = 0o644;\nexport const SENSITIVE_DIR_MODE = 0o700;\nexport const NON_SENSITIVE_DIR_MODE = 0o755;\n\n/** File mode for one codegen contribution. */\nexport const modeFor = (decl: Pick<CodegenableDecl, 'sensitive'>): number =>\n\tdecl.sensitive === true ? SENSITIVE_FILE_MODE : NON_SENSITIVE_FILE_MODE;\n\n/** Parent-directory mode given a set of contributions inside it. */\nexport const dirModeFor = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): number =>\n\tdecls.some((d) => d.sensitive === true) ? SENSITIVE_DIR_MODE : NON_SENSITIVE_DIR_MODE;\n\n/** True if ANY contribution in the set is sensitive — gates the\n *  `.gitignore` \"cover by default\" rule and the parent-mode policy. */\nexport const anySensitive = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): boolean =>\n\tdecls.some((d) => d.sensitive === true);\n"],"mappings":";AAuBA,MAAa,WAAW,SACvB,KAAK,cAAc,OAAA,MAAA"}
+{"version":3,"file":"permissions.mjs","names":[],"sources":["../../../src/orchestrators/codegen/permissions.ts"],"sourcesContent":["// Permission policy for codegen-emitted files.\n//\n// Distilled-doc § \"Sensitive emitted files have restrictive\n// filesystem permissions, re-applied on every emit (not just on\n// create) to recover from manual chmods\". The orchestrator hands the\n// emit/swap layer the mode it should apply.\n//\n// Two-axis policy:\n//   - `sensitive: true` → 0o600 (rw user only).\n//   - `sensitive: false` → 0o644 (rw user, r world).\n// The parent directory the emit lives in inherits the strictest\n// sensitivity of any file inside it — 0o700 when any file is\n// sensitive, 0o755 otherwise. The orchestrator applies parent mode\n// at swap time, separate from per-file modes.\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nexport const SENSITIVE_FILE_MODE = 0o600;\nexport const NON_SENSITIVE_FILE_MODE = 0o644;\nexport const SENSITIVE_DIR_MODE = 0o700;\nexport const NON_SENSITIVE_DIR_MODE = 0o755;\n\n/** File mode for one codegen contribution. */\nexport const modeFor = (decl: Pick<CodegenableDecl, 'sensitive'>): number =>\n\tdecl.sensitive === true ? SENSITIVE_FILE_MODE : NON_SENSITIVE_FILE_MODE;\n\n/** Parent-directory mode given a set of contributions inside it. */\nexport const dirModeFor = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): number =>\n\tdecls.some((d) => d.sensitive === true) ? SENSITIVE_DIR_MODE : NON_SENSITIVE_DIR_MODE;\n\n/** True if ANY contribution in the set is sensitive — gates the\n *  `.gitignore` \"cover by default\" rule and the parent-mode policy. */\nexport const anySensitive = (decls: ReadonlyArray<Pick<CodegenableDecl, 'sensitive'>>): boolean =>\n\tdecls.some((d) => d.sensitive === true);\n"],"mappings":";AAuBA,MAAa,WAAW,SACvB,KAAK,cAAc,OAAA,MAAA;;AAGpB,MAAa,cAAc,UAC1B,MAAM,MAAM,MAAM,EAAE,cAAc,KAAK,GAAA,MAAA"}