@ontrails/trails 1.0.0-beta.21 → 1.0.0-beta.23

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # trails
 
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- 7c037a0: Allow `trails release check` to pass as a no-op in generated single-package apps
+  that do not declare package workspaces.
+- Updated dependencies [9c5ecdc]
+  - @ontrails/http@1.0.0-beta.23
+  - @ontrails/commander@1.0.0-beta.23
+  - @ontrails/adapter-kit@1.0.0-beta.23
+  - @ontrails/cli@1.0.0-beta.23
+  - @ontrails/core@1.0.0-beta.23
+  - @ontrails/mcp@1.0.0-beta.23
+  - @ontrails/observe@1.0.0-beta.23
+  - @ontrails/permits@1.0.0-beta.23
+  - @ontrails/topographer@1.0.0-beta.23
+  - @ontrails/tracing@1.0.0-beta.23
+  - @ontrails/warden@1.0.0-beta.23
+  - @ontrails/wayfinder@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- cdee4d0: Emit formatter-clean fresh scaffold files so generated apps pass their own
+  `format:check` script before any manual cleanup.
+  - @ontrails/commander@1.0.0-beta.22
+  - @ontrails/adapter-kit@1.0.0-beta.22
+  - @ontrails/cli@1.0.0-beta.22
+  - @ontrails/core@1.0.0-beta.22
+  - @ontrails/http@1.0.0-beta.22
+  - @ontrails/mcp@1.0.0-beta.22
+  - @ontrails/observe@1.0.0-beta.22
+  - @ontrails/permits@1.0.0-beta.22
+  - @ontrails/topographer@1.0.0-beta.22
+  - @ontrails/tracing@1.0.0-beta.22
+  - @ontrails/warden@1.0.0-beta.22
+  - @ontrails/wayfinder@1.0.0-beta.22
+
 ## 1.0.0-beta.21
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.21",
+  "version": "1.0.0-beta.23",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -27,23 +27,23 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.21",
-    "@ontrails/cli": "^1.0.0-beta.21",
-    "@ontrails/commander": "^1.0.0-beta.21",
-    "@ontrails/core": "^1.0.0-beta.21",
-    "@ontrails/http": "^1.0.0-beta.21",
-    "@ontrails/mcp": "^1.0.0-beta.21",
-    "@ontrails/observe": "^1.0.0-beta.21",
-    "@ontrails/permits": "^1.0.0-beta.21",
-    "@ontrails/topographer": "^1.0.0-beta.21",
-    "@ontrails/tracing": "^1.0.0-beta.21",
-    "@ontrails/warden": "^1.0.0-beta.21",
-    "@ontrails/wayfinder": "^1.0.0-beta.21",
+    "@ontrails/adapter-kit": "^1.0.0-beta.23",
+    "@ontrails/cli": "^1.0.0-beta.23",
+    "@ontrails/commander": "^1.0.0-beta.23",
+    "@ontrails/core": "^1.0.0-beta.23",
+    "@ontrails/http": "^1.0.0-beta.23",
+    "@ontrails/mcp": "^1.0.0-beta.23",
+    "@ontrails/observe": "^1.0.0-beta.23",
+    "@ontrails/permits": "^1.0.0-beta.23",
+    "@ontrails/topographer": "^1.0.0-beta.23",
+    "@ontrails/tracing": "^1.0.0-beta.23",
+    "@ontrails/warden": "^1.0.0-beta.23",
+    "@ontrails/wayfinder": "^1.0.0-beta.23",
     "commander": "^14.0.3",
     "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.21"
+    "@ontrails/testing": "^1.0.0-beta.23"
   }
 }

package/src/release/check.ts

@@ -170,7 +170,7 @@ export const discoverWorkspaces = async (
   const root = await readJson<PackageJson>(join(repoRoot, 'package.json'));
 
   if (!root.workspaces || root.workspaces.length === 0) {
-    throw new Error('Root package.json has no workspaces field');
+    return [];
   }
 
   const dirs = await discoverWorkspaceDirs(repoRoot, root.workspaces);
@@ -756,9 +756,19 @@ export const runReleaseCheck = async (
   const baseRef =
     options.baseRef ??
     (options.changedFilesPath === undefined ? 'origin/main' : undefined);
-  const changedFiles = options.changedFilesPath
-    ? readChangedFiles(options.changedFilesPath)
-    : readLocalChangedFiles(options.repoRoot, baseRef ?? 'origin/main');
+  let changedFiles: readonly string[];
+
+  if (options.changedFilesPath !== undefined) {
+    changedFiles = readChangedFiles(options.changedFilesPath);
+  } else if (workspaces.length > 0) {
+    changedFiles = readLocalChangedFiles(
+      options.repoRoot,
+      baseRef ?? 'origin/main'
+    );
+  } else {
+    changedFiles = [];
+  }
+
   const loadedConfig = await loadReleaseConfig({
     ...(options.configPath === undefined
       ? {}

package/src/trails/add-surface.ts

@@ -17,6 +17,7 @@ import {
 } from '../project-writes.js';
 import { ontrailsPackageRange } from '../versions.js';
 import { findTopoPath } from './project.js';
+import { stringifyScaffoldPackageJson } from './scaffold-json.js';
 
 type Surface = 'cli' | 'http' | 'mcp';
 
@@ -107,7 +108,7 @@ const updatePkgJsonForSurface = async (
   const written = await writeProjectFile(
     cwd,
     'package.json',
-    `${JSON.stringify(pkg, null, 2)}\n`
+    stringifyScaffoldPackageJson(pkg)
   );
   return written.isErr() ? Result.err(written.error) : Result.ok(depName);
 };

package/src/trails/add-verify.ts

@@ -19,6 +19,7 @@ import {
   ontrailsPackageRange,
   scaffoldDependencyVersions,
 } from '../versions.js';
+import { stringifyScaffoldPackageJson } from './scaffold-json.js';
 
 // ---------------------------------------------------------------------------
 // Content generators
@@ -81,7 +82,7 @@ const updatePackageJsonForVerify = async (
   const written = await writeProjectFile(
     projectDir,
     'package.json',
-    `${JSON.stringify(pkg, null, 2)}\n`
+    stringifyScaffoldPackageJson(pkg)
   );
   return written.isErr() ? Result.err(written.error) : Result.ok();
 };

package/src/trails/create-scaffold.ts

@@ -25,6 +25,10 @@ import {
   scaffoldDependencyVersions,
   trailsPackageVersion,
 } from '../versions.js';
+import {
+  stringifyScaffoldJson,
+  stringifyScaffoldPackageJson,
+} from './scaffold-json.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -96,55 +100,45 @@ const generatePackageJson = (name: string): string => {
     version: '0.1.0',
   };
 
-  return JSON.stringify(pkg, null, 2);
+  return stringifyScaffoldPackageJson(pkg);
 };
 
 const generateScaffoldProvenance = (starter: Starter): string =>
-  JSON.stringify(
-    {
-      generatedAt: new Date().toISOString(),
-      scaffoldVersion: trailsPackageVersion,
-      schemaVersion: 1,
-      template: starter,
-    },
-    null,
-    2
-  );
-
-const TSCONFIG_CONTENT = JSON.stringify(
-  {
-    compilerOptions: {
-      declaration: true,
-      module: 'ESNext',
-      moduleResolution: 'bundler',
-      noUncheckedIndexedAccess: true,
-      outDir: 'dist',
-      rootDir: 'src',
-      skipLibCheck: true,
-      strict: true,
-      target: 'ESNext',
-      verbatimModuleSyntax: true,
-    },
-    include: ['src'],
+  stringifyScaffoldJson({
+    generatedAt: new Date().toISOString(),
+    scaffoldVersion: trailsPackageVersion,
+    schemaVersion: 1,
+    template: starter,
+  });
+
+const TSCONFIG_CONTENT = `{
+  "compilerOptions": {
+    "declaration": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noUncheckedIndexedAccess": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ESNext",
+    "verbatimModuleSyntax": true
   },
-  null,
-  2
-);
-
-const TSCONFIG_TESTS_CONTENT = JSON.stringify(
-  {
-    compilerOptions: {
-      noEmit: true,
-      rootDir: '.',
-      types: ['bun'],
-    },
-    exclude: [],
-    extends: './tsconfig.json',
-    include: ['src', '__tests__'],
+  "include": ["src"]
+}
+`;
+
+const TSCONFIG_TESTS_CONTENT = `{
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".",
+    "types": ["bun"]
   },
-  null,
-  2
-);
+  "exclude": [],
+  "extends": "./tsconfig.json",
+  "include": ["src", "__tests__"]
+}
+`;
 
 const AGENTS_CONTENT = `# AGENTS.md
 
@@ -226,7 +220,16 @@ export default defineConfig({
 `;
 
 const OXFMTRC_CONTENT = `{
-  // ultracite defaults
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "proseWrap": "never",
+  "printWidth": 80,
 }
 `;
 
@@ -235,6 +238,10 @@ const generateHelloTrail = (): string =>
 import { z } from 'zod';
 
 export const hello = trail('hello', {
+  blaze: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: \`Hello, \${name}!\` });
+  },
   description: 'Say hello',
   examples: [
     {
@@ -248,17 +255,13 @@ export const hello = trail('hello', {
       name: 'Named greeting',
     },
   ],
-  blaze: (input) => {
-    const name = input.name ?? 'world';
-    return Result.ok({ message: \`Hello, \${name}!\` });
-  },
   input: z.object({
     name: z.string().optional(),
   }),
+  intent: 'read',
   output: z.object({
     message: z.string(),
   }),
-  intent: 'read',
 });
 `;
 
@@ -276,14 +279,6 @@ const entitySchema = z.object({
 });
 
 export const show = trail('entity.show', {
-  description: 'Show an entity by ID',
-  examples: [
-    {
-      expected: { id: '1', name: 'Example' },
-      input: { id: '1' },
-      name: 'Show entity',
-    },
-  ],
   blaze: (input, ctx) => {
     const store = entityStore.from(ctx);
     const entity = store.get(input.id);
@@ -292,13 +287,27 @@ export const show = trail('entity.show', {
     }
     return Result.ok(entity);
   },
+  description: 'Show an entity by ID',
+  examples: [
+    {
+      expected: { id: '1', name: 'Example' },
+      input: { id: '1' },
+      name: 'Show entity',
+    },
+  ],
   input: z.object({ id: z.string() }),
-  output: entitySchema,
   intent: 'read',
+  output: entitySchema,
   resources: [entityStore],
 });
 
 export const add = trail('entity.add', {
+  blaze: (input, ctx) => {
+    const store = entityStore.from(ctx);
+    const entity = { id: randomUUID(), name: input.name };
+    store.add(entity);
+    return Result.ok(entity);
+  },
   description: 'Add a new entity',
   examples: [
     {
@@ -307,20 +316,18 @@ export const add = trail('entity.add', {
       name: 'Add entity',
     },
   ],
-  blaze: (input, ctx) => {
-    const store = entityStore.from(ctx);
-    const entity = { id: randomUUID(), name: input.name };
-    store.add(entity);
-    return Result.ok(entity);
-  },
   input: z.object({ name: z.string() }),
-  output: entitySchema,
   intent: 'write',
+  output: entitySchema,
   permit: { scopes: ['entity:write'] },
   resources: [entityStore],
 });
 
 export const list = trail('entity.list', {
+  blaze: (_input, ctx) => {
+    const store = entityStore.from(ctx);
+    return Result.ok({ entities: store.list() });
+  },
   description: 'List entities',
   examples: [
     {
@@ -329,19 +336,20 @@ export const list = trail('entity.list', {
       name: 'List entities',
     },
   ],
-  blaze: (_input, ctx) => {
-    const store = entityStore.from(ctx);
-    return Result.ok({ entities: store.list() });
-  },
   input: z.object({}),
+  intent: 'read',
   output: z.object({
     entities: z.array(entitySchema),
   }),
-  intent: 'read',
   resources: [entityStore],
 });
 
 export const remove = trail('entity.delete', {
+  blaze: (input, ctx) => {
+    const store = entityStore.from(ctx);
+    const deleted = store.delete(input.id);
+    return Result.ok({ deleted, id: input.id });
+  },
   description: 'Delete an entity by ID',
   examples: [
     {
@@ -350,17 +358,12 @@ export const remove = trail('entity.delete', {
       name: 'Delete entity',
     },
   ],
-  blaze: (input, ctx) => {
-    const store = entityStore.from(ctx);
-    const deleted = store.delete(input.id);
-    return Result.ok({ deleted, id: input.id });
-  },
   input: z.object({ id: z.string() }),
+  intent: 'destroy',
   output: z.object({
     deleted: z.boolean(),
     id: z.string(),
   }),
-  intent: 'destroy',
   permit: { scopes: ['entity:write'] },
   resources: [entityStore],
 });
@@ -371,6 +374,9 @@ const generateSearchTrail = (): string =>
 import { z } from 'zod';
 
 export const search = trail('search', {
+  blaze: () => {
+    return Result.ok({ results: [] });
+  },
   description: 'Search entities by query',
   examples: [
     {
@@ -379,14 +385,11 @@ export const search = trail('search', {
       name: 'Search entities',
     },
   ],
-  blaze: () => {
-    return Result.ok({ results: [] });
-  },
   input: z.object({ query: z.string() }),
+  intent: 'read',
   output: z.object({
     results: z.array(z.object({ id: z.string(), name: z.string() })),
   }),
-  intent: 'read',
 });
 `;
 
@@ -395,8 +398,6 @@ const generateOnboardTrail = (): string =>
 import { z } from 'zod';
 
 export const onboard = trail('entity.onboard', {
-  description: 'Onboard a new entity end-to-end',
-  composes: ['entity.add'],
   blaze: async (input, ctx) => {
     const result = await ctx.compose('entity.add', { name: input.name });
     if (result.isErr()) {
@@ -404,9 +405,11 @@ export const onboard = trail('entity.onboard', {
     }
     return Result.ok({ onboarded: true });
   },
+  composes: ['entity.add'],
+  description: 'Onboard a new entity end-to-end',
   input: z.object({ name: z.string() }),
-  output: z.object({ onboarded: z.boolean() }),
   intent: 'write',
+  output: z.object({ onboarded: z.boolean() }),
   permit: { scopes: ['entity:write'] },
 });
 `;
@@ -458,14 +461,14 @@ export const createEntityStore = (
       return store.get(id);
     },
     list() {
-      return Array.from(store.values());
+      return [...store.values()];
     },
   };
 };
 
 export const entityStore = resource('entity.store', {
-  description: 'In-memory entity store for the entity starter.',
   create: () => Result.ok(createEntityStore()),
+  description: 'In-memory entity store for the entity starter.',
   mock: createEntityStore,
 });
 `;
@@ -491,19 +494,31 @@ const starterImports: Record<
   },
 };
 
+const renderTopoExpression = (
+  appNameLiteral: string,
+  modules: readonly string[]
+): string => {
+  if (modules.length === 0) {
+    return `topo(${appNameLiteral})`;
+  }
+
+  if (modules.length === 1) {
+    return `topo(${appNameLiteral}, ${modules[0]})`;
+  }
+
+  return `topo(\n  ${[appNameLiteral, ...modules].join(',\n  ')}\n)`;
+};
+
 const generateAppTs = (name: string, starter: Starter): string => {
   const { imports, modules } = starterImports[starter];
-  const appNameLiteral = JSON.stringify(name);
-  const topoArgs =
-    modules.length > 0
-      ? `${appNameLiteral}, ${modules.join(', ')}`
-      : appNameLiteral;
+  const appNameLiteral = `'${name}'`;
+  const topoExpression = renderTopoExpression(appNameLiteral, modules);
 
   return [
     "import { topo } from '@ontrails/core';",
     ...imports,
     '',
-    `export const app = topo(${topoArgs});`,
+    `export const app = ${topoExpression};`,
     '',
   ].join('\n');
 };

package/src/trails/scaffold-json.ts

@@ -0,0 +1,58 @@
+const packageKeyOrder = [
+  'name',
+  'version',
+  'bin',
+  'type',
+  'scripts',
+  'dependencies',
+  'devDependencies',
+] as const;
+
+const packageMapKeys = new Set<string>([
+  'bin',
+  'dependencies',
+  'devDependencies',
+  'scripts',
+]);
+
+export type ScaffoldPackageJson = Record<string, unknown>;
+
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const sortRecord = (record: Record<string, unknown>): Record<string, unknown> =>
+  Object.fromEntries(
+    Object.entries(record).toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    )
+  );
+
+const normalizePackageValue = (key: string, value: unknown): unknown =>
+  packageMapKeys.has(key) && isPlainRecord(value) ? sortRecord(value) : value;
+
+export const normalizeScaffoldPackageJson = (
+  pkg: ScaffoldPackageJson
+): ScaffoldPackageJson => {
+  const normalized: ScaffoldPackageJson = {};
+
+  for (const key of packageKeyOrder) {
+    if (pkg[key] !== undefined) {
+      normalized[key] = normalizePackageValue(key, pkg[key]);
+    }
+  }
+
+  for (const key of Object.keys(pkg).toSorted()) {
+    if (!(key in normalized)) {
+      normalized[key] = normalizePackageValue(key, pkg[key]);
+    }
+  }
+
+  return normalized;
+};
+
+export const stringifyScaffoldJson = (value: unknown): string =>
+  `${JSON.stringify(value, null, 2)}\n`;
+
+export const stringifyScaffoldPackageJson = (
+  pkg: ScaffoldPackageJson
+): string => stringifyScaffoldJson(normalizeScaffoldPackageJson(pkg));