Integrate markup formatter to starter template and forge.

Author: koculu

frontend/purestack.studio/guides/getting-started/purestack-cli.mdx

@@ -131,6 +131,7 @@ Replace `my-site` with your folder name. Skipped installation? Run `yarn install
 | Command | What it does |
 | --- | --- |
 | `yarn dev` | Open your site locally. Saved changes reload in your browser. |
+| `yarn format` | Format your code, MDX components, and TypeScript templates. |
 | `yarn check` | Check code quality and formatting. |
 | `yarn test` | Run app tests while you work. |
 | `yarn build` | Generate the complete site in `dist/dev`. |

package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "purestack-repo",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "packageManager": "yarn@4.18.1",
   "type": "module",
   "sideEffects": false,

packages/purestack/forge/modules/components/setup-step.ts

@@ -20,7 +20,8 @@ const setupStepTemplate = html`<StepPanel
         :checked="workspace.install"
         tone="accent"/>
       <p class="text-subtle fs-xs mt-2 mb-0">
-        Use the package manager configured by the template.
+        Install dependencies, then format your project if the template provides
+        a format script.
       </p>
     </div>
     <div>

packages/purestack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purestack",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "packageManager": "yarn@4.9.2",
   "module": "./dist/purestack.mjs",
   "types": "./dist/purestack.d.mts",

packages/purestack/src/cli/forge/session.test.ts

@@ -13,12 +13,13 @@ import type {
   DevWebSocketConnection,
   DevWebSocketMessage,
 } from '@purestack/ts-ssg'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import type {
   SessionCommand,
   SessionEvent,
 } from '../../../forge/modules/shared/protocol'
 import { createSite } from '../../init/create-site'
+import * as managers from '../../init/package-manager'
 import { readTemplateUi } from '../../init/template-ui'
 import { parseInitArguments } from '../arguments'
 import { Session } from './session'
@@ -122,6 +123,51 @@ async function fixture(previewFails = false) {
 }
 
 describe('Forge session', () => {
+  it('streams formatting progress after installation and before starting the live site', async () => {
+    const test = await fixture()
+    const prepare = vi
+      .spyOn(managers, 'preparePackageManager')
+      .mockResolvedValue(undefined)
+    const run = vi.spyOn(managers, 'runPackageManager').mockResolvedValue('')
+    test.gate.resolve()
+    try {
+      test.peer.request({
+        type: 'create',
+        configuration: {
+          ...test.session.snapshot.configuration,
+          install: true,
+        },
+      })
+      await expect.poll(() => test.session.snapshot.status).toBe('ready')
+      const tasks = test.session.snapshot.tasks
+      const labels = tasks.map((task) => task.label)
+      expect(labels.indexOf('Format project files')).toBeGreaterThan(
+        labels.indexOf('Install dependencies'),
+      )
+      expect(labels.indexOf('Format project files')).toBeLessThan(
+        labels.indexOf('Start live site'),
+      )
+      expect(tasks.every((task) => task.state === 'done')).toBe(true)
+      expect(
+        test.peer.events.some(
+          (event) =>
+            event.type === 'snapshot' &&
+            event.snapshot.tasks.some(
+              (task) =>
+                task.label === 'Format project files' &&
+                task.state === 'running',
+            ),
+        ),
+      ).toBe(true)
+      expect(test.session.snapshot.result?.failures).toEqual([])
+      expect(test.counts().previews).toBe(1)
+    } finally {
+      await test.close()
+      prepare.mockRestore()
+      run.mockRestore()
+    }
+  })
+
   it('creates once, streams tasks, survives reconnects and keeps the live site open until finishing', async () => {
     const test = await fixture()
     try {

packages/purestack/src/index.ts

@@ -1,3 +1,3 @@
-export const version: string = '1.1.23'
+export const version: string = '1.1.24'
 
 export * from '@purestack/ts-ssg'

packages/purestack/src/init/create-site.ts

@@ -67,6 +67,7 @@ export async function createSite(
   const temporary = await mkdtemp(path.join(tmpdir(), 'purestack-init-'))
   let template: string
   let packageManager: PackageManager
+  let hasFormatScript: boolean
   try {
     const unpacked = path.join(temporary, 'unpacked')
     const templateRoot = options.templateRoot
@@ -104,6 +105,7 @@ export async function createSite(
     })
     template = `${project.name}@${project.version}`
     packageManager = project.packageManager
+    hasFormatScript = project.hasFormatScript
   } finally {
     await rm(temporary, { recursive: true, force: true })
   }
@@ -141,6 +143,23 @@ export async function createSite(
       )
     }
   }
+  if (result.installed && hasFormatScript) {
+    try {
+      await perform('Format project files', () =>
+        runPackageManager(packageManager, ['run', 'format'], directory, {
+          capture: true,
+          signal: options.signal,
+        }),
+      )
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') throw error
+      const command =
+        packageManager === 'yarn' ? 'yarn format' : 'npm run format'
+      result.failures.push(
+        `Project formatting failed: ${error instanceof Error ? error.message : String(error)}\nRetry ${command} in the project directory.`,
+      )
+    }
+  }
   if (plan.git) {
     try {
       await perform('Set up Git', async () => {

packages/purestack/src/init/init.test.ts

@@ -562,11 +562,122 @@ describe('project generation', () => {
     expect(result.failures).toEqual([
       expect.stringContaining('Retry yarn install'),
     ])
+    expect(install).toHaveBeenCalledTimes(1)
     expect(
       await readFile(path.join(destination, 'README.md'), 'utf8'),
     ).toContain('PureStack')
   })
 
+  it.each(['yarn', 'npm'] as const)(
+    'formats after installing with %s and before setting up Git',
+    async (manager) => {
+      const templateRoot = await fixture()
+      if (manager === 'npm') {
+        const file = path.join(templateRoot, 'template/package.json')
+        const project = JSON.parse(await readFile(file, 'utf8'))
+        delete project.packageManager
+        await writeFile(file, JSON.stringify(project))
+      }
+      const destination = path.join(temporary, 'project')
+      const run = vi.spyOn(managers, 'runPackageManager').mockResolvedValue('')
+      vi.spyOn(processes, 'runProcess').mockResolvedValue(repository)
+      const labels: string[] = []
+      const signal = new AbortController().signal
+      const result = await createSite(
+        plan(destination, 'starter', { install: true, git: true }),
+        cliVersion,
+        repository,
+        async (label, action) => {
+          labels.push(label)
+          return action()
+        },
+        { templateRoot, signal },
+      )
+      expect(result.installed).toBe(true)
+      expect(result.failures).toEqual([])
+      expect(run.mock.calls.map((call) => call[1])).toEqual([
+        manager === 'yarn' ? ['install', '--no-immutable'] : ['install'],
+        ['run', 'format'],
+      ])
+      expect(run).toHaveBeenLastCalledWith(
+        manager,
+        ['run', 'format'],
+        destination,
+        { capture: true, signal },
+      )
+      expect(labels.slice(-3)).toEqual([
+        'Install dependencies',
+        'Format project files',
+        'Set up Git',
+      ])
+    },
+  )
+
+  it.each([undefined, '   '])(
+    'skips formatting when the template has no usable format script (%s)',
+    async (format) => {
+      const templateRoot = await fixture()
+      const file = path.join(templateRoot, 'template/package.json')
+      const project = JSON.parse(await readFile(file, 'utf8'))
+      project.scripts.format = format
+      await writeFile(file, JSON.stringify(project))
+      const run = vi.spyOn(managers, 'runPackageManager').mockResolvedValue('')
+      const result = await createSite(
+        plan(path.join(temporary, 'project'), 'starter', { install: true }),
+        cliVersion,
+        repository,
+        undefined,
+        { templateRoot },
+      )
+      expect(result.installed).toBe(true)
+      expect(result.failures).toEqual([])
+      expect(run).toHaveBeenCalledTimes(1)
+    },
+  )
+
+  it('preserves the installed project and continues Git setup when formatting fails', async () => {
+    const destination = path.join(temporary, 'project')
+    vi.spyOn(managers, 'runPackageManager')
+      .mockResolvedValueOnce('')
+      .mockRejectedValueOnce(new Error('Invalid markup'))
+    vi.spyOn(processes, 'runProcess').mockResolvedValue(repository)
+    const result = await createSite(
+      plan(destination, 'starter', { install: true, git: true }),
+      cliVersion,
+      repository,
+      undefined,
+      { templateRoot: await fixture() },
+    )
+    expect(result.installed).toBe(true)
+    expect(result.git).toBe('existing')
+    expect(result.failures).toEqual([
+      'Project formatting failed: Invalid markup\nRetry yarn format in the project directory.',
+    ])
+    expect(await readdir(destination)).toContain('README.md')
+  })
+
+  it('propagates formatting cancellation and does not start Git setup', async () => {
+    const cancelled = new Error('Cancelled')
+    cancelled.name = 'AbortError'
+    vi.spyOn(managers, 'runPackageManager')
+      .mockResolvedValueOnce('')
+      .mockRejectedValueOnce(cancelled)
+    const git = vi.spyOn(processes, 'runProcess')
+    await expect(
+      createSite(
+        plan(path.join(temporary, 'project'), 'starter', {
+          install: true,
+          git: true,
+        }),
+        cliVersion,
+        repository,
+        undefined,
+        { templateRoot: await fixture() },
+      ),
+    ).rejects.toBe(cancelled)
+    expect(git).not.toHaveBeenCalled()
+  })
+
   it('skips Git initialization inside an existing repository', async () => {
     const archive = await archiveFixture()
     vi.spyOn(console, 'log').mockImplementation(() => {})

packages/purestack/src/init/template.ts

@@ -357,6 +357,8 @@ export async function prepareProject(
     name: pkg.name,
     version: pkg.version,
     packageManager,
+    hasFormatScript:
+      typeof scripts.format === 'string' && scripts.format.trim().length > 0,
   }
 }
 

packages/ts-common/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purestack/ts-common",
-  "version": "1.1.23",
+  "version": "1.1.24",
   "packageManager": "yarn@4.9.2",
   "module": "./dist/ts-common.mjs",
   "types": "./dist/ts-common.d.mts",